Add npm launcher package

Author: ithiria894

docs/NPM_RELEASE.md

@@ -0,0 +1,47 @@
+# npm release notes
+
+IntentProbe's npm package is a thin launcher for JavaScript, MCP, and agent
+users who expect `npx intentprobe ...`.
+
+The scanner core stays in Python. Do not move Torch, Transformers, or probe
+artifacts into npm.
+
+Publish the Python package first, then publish npm. The npm launcher defaults
+to `uvx --from intentprobe intentprobe ...` when a local Python install is not
+available, so the PyPI package must exist before `npx intentprobe ...` is a
+good public first-run experience.
+
+## Package
+
+- npm package name: `intentprobe`
+- package directory: `npm/`
+- binaries: `intentprobe`, `intentprobe-hook`
+- current version: `0.1.0`
+
+## Publish checklist
+
+From the repository root:
+
+```bash
+npm view intentprobe name version dist-tags --json
+npm whoami
+npm --prefix npm run check
+INTENTPROBE_PYTHON=.venv/bin/python node npm/bin/intentprobe.mjs --help
+npm --prefix npm run pack:dry
+npm publish ./npm
+```
+
+After publish, verify:
+
+```bash
+npm view intentprobe name version dist-tags --json
+npx intentprobe --help
+```
+
+Only after the package is live should the root README advertise `npx
+intentprobe ...` as the primary install path.
+
+## Auth blocker seen locally
+
+`npm whoami` returned `ENEEDAUTH`, so publishing needs an npm login or npm
+automation token before this can go live.

npm/README.md

@@ -0,0 +1,44 @@
+# IntentProbe npm launcher
+
+Run IntentProbe from JavaScript, MCP, and agent workflows:
+
+```bash
+npx intentprobe scan-path ./some-mcp-server --format summary
+npx intentprobe scan --text "Reads SSH config and uploads private keys." --format summary
+```
+
+IntentProbe is the first open-source activation-probe-based scanner for MCP/tool
+poisoning. It runs locally and reads model-internal activations instead of only
+matching text patterns.
+
+## What this package is
+
+This npm package is a thin launcher. The scanner core is the Python package
+`intentprobe`, because activation probing uses PyTorch / Transformers.
+
+The launcher tries, in order:
+
+1. `INTENTPROBE_PYTHON=/path/to/python`, if set.
+2. `python3 -m intentprobe`, if the Python package is installed.
+3. `python -m intentprobe`, if available.
+4. `uvx --from intentprobe intentprobe`, if `uvx` is installed.
+
+## Python scanner install
+
+```bash
+pipx install intentprobe
+# or
+python3 -m pip install intentprobe
+```
+
+First scan downloads the small base model once. After that, scans stay local.
+
+## Runtime hook
+
+The package also exposes `intentprobe-hook`:
+
+```bash
+npx intentprobe-hook --help
+```
+
+Repository: https://github.com/mcpware/IntentProbe

npm/bin/intentprobe.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+import { spawn, spawnSync } from "node:child_process";
+import { basename } from "node:path";
+
+const PACKAGE_NAME = "intentprobe";
+const invokedAs = basename(process.argv[1] || "intentprobe");
+const entrypoint = invokedAs === "intentprobe-hook" ? "intentprobe-hook" : "intentprobe";
+const pythonModule = entrypoint === "intentprobe-hook" ? "intentprobe.hook" : "intentprobe";
+const args = process.argv.slice(2);
+
+function canRun(command, commandArgs) {
+  const result = spawnSync(command, commandArgs, { stdio: "ignore" });
+  return !result.error && result.status === 0;
+}
+
+function pythonHasIntentProbe(python) {
+  return canRun(python, ["-c", "import intentprobe"]);
+}
+
+function findPythonWithIntentProbe() {
+  const candidates = [
+    process.env.INTENTPROBE_PYTHON,
+    "python3",
+    "python"
+  ].filter(Boolean);
+
+  for (const python of candidates) {
+    if (pythonHasIntentProbe(python)) {
+      return python;
+    }
+  }
+
+  return null;
+}
+
+function run(command, commandArgs) {
+  const child = spawn(command, commandArgs, {
+    stdio: "inherit",
+    env: process.env
+  });
+
+  child.on("error", (error) => {
+    console.error(`intentprobe: failed to start ${command}: ${error.message}`);
+    process.exit(127);
+  });
+
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+      return;
+    }
+    process.exit(code ?? 1);
+  });
+}
+
+const python = findPythonWithIntentProbe();
+if (python) {
+  run(python, ["-m", pythonModule, ...args]);
+} else if (canRun("uvx", ["--version"])) {
+  const source = process.env.INTENTPROBE_UVX_SOURCE || PACKAGE_NAME;
+  run("uvx", ["--from", source, entrypoint, ...args]);
+} else {
+  console.error(`IntentProbe's npm package is a thin launcher for the Python scanner.
+
+Could not find a Python environment with the "intentprobe" module, and "uvx"
+is not available for one-shot execution.
+
+Install the Python scanner first:
+
+  pipx install intentprobe
+  # or
+  python3 -m pip install intentprobe
+
+Then run:
+
+  npx intentprobe scan-path ./some-mcp-server --format summary
+
+For a custom environment:
+
+  INTENTPROBE_PYTHON=/path/to/python npx intentprobe --help
+`);
+  process.exit(127);
+}

npm/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "intentprobe",
+  "version": "0.1.0",
+  "description": "Thin npm launcher for IntentProbe, a local activation-probe scanner for MCP/tool poisoning.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "intentprobe": "bin/intentprobe.mjs",
+    "intentprobe-hook": "bin/intentprobe.mjs"
+  },
+  "files": [
+    "bin/intentprobe.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "ai-security",
+    "mcp",
+    "tool-poisoning",
+    "activation-probe",
+    "scanner",
+    "agent-security"
+  ],
+  "homepage": "https://github.com/mcpware/IntentProbe#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcpware/IntentProbe.git",
+    "directory": "npm"
+  },
+  "bugs": {
+    "url": "https://github.com/mcpware/IntentProbe/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "node --check ./bin/intentprobe.mjs",
+    "pack:dry": "npm pack --dry-run"
+  }
+}