@securevector/cli 5.3.0

package/README.md

@@ -0,0 +1,75 @@
+# SecureVector for npm
+
+Security and observability for AI agents. This package is the launcher for
+people whose toolchain is Node; the product itself is a Python application
+published on PyPI, and this installs and runs the matching version.
+
+```bash
+npm install -g @securevector/cli
+securevector
+```
+
+or without installing anything globally:
+
+```bash
+npx @securevector/cli
+```
+
+## What happens when you install it
+
+Nothing. `npm install` writes files and stops. It runs no install script and
+makes no network request beyond fetching the package itself.
+
+The first time you actually run `securevector`, it creates a virtual
+environment under your own data directory and installs the matching release
+from PyPI, telling you what it is doing as it does it. Every run after that
+starts immediately.
+
+That is deliberate. A postinstall script that downloads and executes code is
+the exact supply-chain shape this product exists to warn people about. It would
+be a strange thing for a security tool to ship, however convenient, so it does
+not.
+
+## Requirements
+
+Python 3.10 or newer, on PATH. This package will not install a language runtime
+for you. If Python is missing or too old, `securevector doctor` says so and
+tells you what to do.
+
+## Commands
+
+```
+securevector [app] [...]     Start the local app (default)
+securevector monitor [...]   The sv-monitor CLI
+securevector proxy [...]     The LLM proxy
+securevector mcp [...]       The MCP server
+securevector doctor          Check this machine and report what is missing
+securevector where           Print the managed environment path
+securevector --version
+```
+
+Everything after the verb is passed through untouched, so
+
+```bash
+securevector monitor status
+```
+
+is exactly `sv-monitor status`.
+
+## Versions
+
+The npm version and the PyPI version are the same number for the same product.
+`npm install @securevector/cli@5.3.0` gives you exactly what
+`pip install securevector-ai-monitor==5.3.0` gives you. The launcher pins that
+exact version and never resolves `latest`.
+
+## Uninstalling
+
+```bash
+npm uninstall -g @securevector/cli
+rm -rf "$(securevector where)"     # run this first, it needs the command
+```
+
+## Licence
+
+Apache-2.0. See the repository for the full text.

package/bin/securevector.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `securevector` for people who install things with npm.
+ *
+ * This is a launcher, not a reimplementation. It finds a usable Python, makes
+ * sure the matching PyPI release is installed in a virtual environment it
+ * manages, and then hands over. Everything the product does, it does in the
+ * Python process; nothing about behaviour is decided here.
+ *
+ * The one thing this file is opinionated about is that installing software is
+ * an explicit act. `npm install` of this package touches the network exactly
+ * zero times. The first real run says what it is going to do before it does it.
+ */
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+const pkg = require('../package.json');
+const { findPython, explainMissing, MIN_MAJOR, MIN_MINOR } = require('../lib/python');
+const { isReady, install, venvBin, venvPath, envRoot } = require('../lib/bootstrap');
+
+// The npm version and the PyPI version are the same product, so the launcher
+// pins to its own version rather than resolving "latest". Installing
+// @securevector/cli@6.0.0 must never give you a different SecureVector than
+// pip install securevector-ai-monitor==6.0.0 does.
+const VERSION = pkg.version;
+
+// Which Python entry point each verb runs. Names must match setup.py's
+// console_scripts; a typo here is a confusing "command not found" inside the
+// venv rather than an error anyone can act on, so there is a test for it.
+const ENTRY_POINTS = {
+  app: 'securevector-app',
+  monitor: 'sv-monitor',
+  proxy: 'securevector-proxy',
+  mcp: 'securevector-mcp',
+};
+const DEFAULT_VERB = 'app';
+
+function usage() {
+  return [
+    `SecureVector ${VERSION}`,
+    '',
+    'Usage:',
+    '  securevector [app] [...]      Start the local app (default)',
+    '  securevector monitor [...]    The sv-monitor CLI, including session commands',
+    '  securevector proxy [...]      The LLM proxy',
+    '  securevector mcp [...]        The MCP server',
+    '  securevector doctor           Check this machine and report what is missing',
+    '  securevector where            Print the managed environment path',
+    '  securevector --version',
+    '',
+    'Anything after the verb is passed through untouched, so',
+    '  securevector monitor session list',
+    'is exactly sv-monitor session list.',
+  ].join('\n');
+}
+
+function doctor() {
+  const { best, seen } = findPython();
+  const lines = [`SecureVector ${VERSION} (npm launcher)`, ''];
+  lines.push(`node            ${process.version}`);
+  lines.push(`platform        ${process.platform} ${process.arch}`);
+  lines.push(`python floor    ${MIN_MAJOR}.${MIN_MINOR}`);
+  if (best) {
+    lines.push(`python found    ${best.candidate} (${best.version.join('.')})`);
+  } else {
+    lines.push('python found    none usable');
+  }
+  if (seen.length) {
+    lines.push('interpreters    ' + seen.map((s) => `${s.candidate}=${s.version.join('.')}`).join('  '));
+  }
+  lines.push(`environment     ${venvPath(VERSION)}`);
+  const ready = isReady(VERSION, ENTRY_POINTS[DEFAULT_VERB]);
+  lines.push(`installed       ${ready ? 'yes' : 'no, the first run will set it up'}`);
+  lines.push('');
+  if (!best) {
+    lines.push(explainMissing(seen));
+    return { text: lines.join('\n'), code: 1 };
+  }
+  lines.push(ready ? 'Ready.' : 'Ready to set up. Run `securevector` to start.');
+  return { text: lines.join('\n'), code: 0 };
+}
+
+function main(argv) {
+  const args = argv.slice(2);
+
+  if (args[0] === '--version' || args[0] === '-v') {
+    process.stdout.write(VERSION + '\n');
+    return 0;
+  }
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    process.stdout.write(usage() + '\n');
+    return 0;
+  }
+  if (args[0] === 'doctor') {
+    const r = doctor();
+    process.stdout.write(r.text + '\n');
+    return r.code;
+  }
+  if (args[0] === 'where') {
+    process.stdout.write(envRoot() + '\n');
+    return 0;
+  }
+
+  // An unrecognised first argument is a flag or an argument for the default
+  // verb, not a typo to reject: `securevector --web` has to keep working.
+  const verb = Object.prototype.hasOwnProperty.call(ENTRY_POINTS, args[0]) ? args[0] : DEFAULT_VERB;
+  const rest = verb === args[0] ? args.slice(1) : args;
+  const entryPoint = ENTRY_POINTS[verb];
+
+  const { best, seen } = findPython();
+  if (!best) {
+    process.stderr.write('\n' + explainMissing(seen) + '\n\n');
+    return 1;
+  }
+
+  if (!isReady(VERSION, entryPoint)) {
+    const result = install(best.candidate, VERSION);
+    if (!result.ok) {
+      process.stderr.write('\n' + result.reason + '\n\n');
+      return 1;
+    }
+    if (!isReady(VERSION, entryPoint)) {
+      process.stderr.write(
+        `\nThe install finished but ${entryPoint} is not in ${venvPath(VERSION)}.\n` +
+          'Run `securevector doctor`, and if that looks fine, delete the path above and try again.\n\n'
+      );
+      return 1;
+    }
+  }
+
+  const child = spawn(venvBin(VERSION, entryPoint), rest, { stdio: 'inherit' });
+  child.on('error', (err) => {
+    process.stderr.write(`\nCould not start ${entryPoint}: ${err.message}\n\n`);
+    process.exitCode = 1;
+  });
+  // Signals belong to the child: it owns a server, a proxy or a terminal
+  // session, and this process is a thin parent that must not swallow a Ctrl-C
+  // the child needs to shut down cleanly.
+  child.on('exit', (code, signal) => {
+    process.exitCode = signal ? 1 : (code ?? 0);
+  });
+  return null; // async from here; exit code set on the child's exit
+}
+
+if (require.main === module) {
+  const code = main(process.argv);
+  if (code !== null) process.exitCode = code;
+}
+
+module.exports = { main, doctor, usage, ENTRY_POINTS, DEFAULT_VERB, VERSION };

package/lib/bootstrap.js

@@ -0,0 +1,127 @@
+'use strict';
+
+/**
+ * The managed virtual environment this launcher installs into, and the rules
+ * about when it is allowed to touch the network.
+ *
+ * The shape of the whole thing: `npm install` does NOTHING but put files on
+ * disk. The first time someone actually runs `securevector`, and only then, we
+ * create a virtual environment under their own data directory and pip install
+ * the exact matching version from PyPI, saying so as it happens. Every run
+ * after that is a process exec and nothing else.
+ *
+ * A postinstall script that downloads and executes code is precisely the
+ * supply-chain shape this product warns people about. Shipping one in a
+ * security tool would be indefensible whatever the convenience argument, so
+ * this package does not have one.
+ */
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const PYPI_PACKAGE = 'securevector-ai-monitor';
+
+/**
+ * Where the managed environment lives.
+ *
+ * Under the user's own data directory, never inside node_modules: a global npm
+ * prefix can be root-owned or on a read-only volume, and reinstalling or
+ * updating the npm package would otherwise throw away a working environment
+ * and re-download it.
+ */
+function envRoot() {
+  const home = os.homedir();
+  if (os.platform() === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'SecureVector', 'npm-runtime');
+  }
+  if (os.platform() === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'SecureVector', 'npm-runtime');
+  }
+  return path.join(process.env.XDG_DATA_HOME || path.join(home, '.local', 'share'), 'securevector', 'npm-runtime');
+}
+
+/** One environment per version, so upgrading never half-migrates an old one. */
+function venvPath(version) {
+  return path.join(envRoot(), `v${version}`);
+}
+
+function venvBin(version, exe) {
+  const dir = os.platform() === 'win32' ? 'Scripts' : 'bin';
+  const suffix = os.platform() === 'win32' ? '.exe' : '';
+  return path.join(venvPath(version), dir, exe + suffix);
+}
+
+/** Is the environment for this version present and carrying the entry points? */
+function isReady(version, entryPoint) {
+  try {
+    return fs.existsSync(venvBin(version, entryPoint));
+  } catch {
+    return false;
+  }
+}
+
+function run(command, args, opts = {}) {
+  const res = spawnSync(command, args, { stdio: 'inherit', ...opts });
+  if (res.error) throw res.error;
+  return res.status === 0;
+}
+
+/**
+ * Create the environment and install the pinned version. Talks while it works,
+ * because it is a network install and a silent 30 second pause during what
+ * looked like a launch is indistinguishable from a hang.
+ */
+function install(python, version, { extras = 'app', quiet = false } = {}) {
+  const target = venvPath(version);
+  const spec = `${PYPI_PACKAGE}[${extras}]==${version}`;
+  const say = (line) => {
+    if (!quiet) process.stderr.write(line + '\n');
+  };
+
+  say('');
+  say(`  SecureVector ${version} is not set up yet on this machine.`);
+  say('');
+  say('  This will now, once:');
+  say(`    create a virtual environment  ${target}`);
+  say(`    install from PyPI             ${spec}`);
+  say('');
+  say('  Nothing was downloaded during npm install. Later runs start immediately.');
+  say('');
+
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+
+  const { command, args } = splitPython(python);
+  if (!run(command, [...args, '-m', 'venv', target])) {
+    return { ok: false, reason: 'Could not create the virtual environment.' };
+  }
+
+  const pip = venvBin(version, 'python');
+  // Upgrade pip inside the venv first: an old pip on the system Python is a
+  // common cause of a wheel resolving wrongly, and this keeps that out of the
+  // failure surface. Failure here is not fatal; the install may still work.
+  run(pip, ['-m', 'pip', 'install', '--upgrade', 'pip'], { stdio: 'ignore' });
+
+  if (!run(pip, ['-m', 'pip', 'install', spec])) {
+    return {
+      ok: false,
+      reason: [
+        `Could not install ${spec} from PyPI.`,
+        '',
+        'Common causes: no network, a proxy that needs configuring, or this',
+        'version not being published yet. The environment was left at',
+        `  ${target}`,
+        'so you can look, or delete it and try again.',
+      ].join('\n'),
+    };
+  }
+  return { ok: true };
+}
+
+function splitPython(candidate) {
+  const parts = candidate.split(' ');
+  return { command: parts[0], args: parts.slice(1) };
+}
+
+module.exports = { envRoot, venvPath, venvBin, isReady, install, splitPython, PYPI_PACKAGE };

package/lib/python.js

@@ -0,0 +1,108 @@
+'use strict';
+
+/**
+ * Finding a Python this product can actually run on, and saying something
+ * useful when there isn't one.
+ *
+ * SecureVector is a Python application. This package exists so that people
+ * whose toolchain is Node do not have to know that before they can try it, but
+ * "do not have to know" is not the same as "we will install a language runtime
+ * behind your back". A security tool that silently provisions an interpreter is
+ * doing the thing it warns other software about. So: detect, explain, stop.
+ */
+
+const { execFileSync } = require('node:child_process');
+const os = require('node:os');
+
+// The app extras need 3.10. The base SDK claims 3.9, but nothing this launcher
+// starts is the base SDK, so 3.10 is the honest floor to check against.
+const MIN_MAJOR = 3;
+const MIN_MINOR = 10;
+
+// Ordered by how likely each is to be the one the user means. A bare `python`
+// is last: on a machine with both, `python` is as likely to be a 2.x relic as
+// anything, and picking it would produce a syntax error rather than a message.
+const CANDIDATES =
+  os.platform() === 'win32'
+    ? ['py -3', 'python3', 'python']
+    : ['python3.13', 'python3.12', 'python3.11', 'python3.10', 'python3', 'python'];
+
+function splitCommand(candidate) {
+  const parts = candidate.split(' ');
+  return { command: parts[0], args: parts.slice(1) };
+}
+
+/** `[major, minor]` for an interpreter, or null if it cannot be asked. */
+function versionOf(candidate) {
+  const { command, args } = splitCommand(candidate);
+  try {
+    const out = execFileSync(
+      command,
+      [...args, '-c', 'import sys; print("%d.%d" % sys.version_info[:2])'],
+      { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 10000 }
+    ).trim();
+    const [major, minor] = out.split('.').map(Number);
+    if (!Number.isInteger(major) || !Number.isInteger(minor)) return null;
+    return [major, minor];
+  } catch {
+    return null;
+  }
+}
+
+function isNewEnough([major, minor]) {
+  return major > MIN_MAJOR || (major === MIN_MAJOR && minor >= MIN_MINOR);
+}
+
+/**
+ * The best interpreter on this machine, as `{ candidate, version }`.
+ *
+ * Returns the highest usable version rather than the first found: a machine
+ * with 3.9 on PATH and 3.12 beside it should use 3.12, and "first match wins"
+ * would hand back the one that cannot run the app.
+ */
+function findPython() {
+  const seen = [];
+  let best = null;
+  for (const candidate of CANDIDATES) {
+    const version = versionOf(candidate);
+    if (!version) continue;
+    seen.push({ candidate, version });
+    if (!isNewEnough(version)) continue;
+    if (!best || version[0] > best.version[0] || (version[0] === best.version[0] && version[1] > best.version[1])) {
+      best = { candidate, version };
+    }
+  }
+  return { best, seen };
+}
+
+/** What to tell someone who has no usable Python. Never a stack trace. */
+function explainMissing(seen) {
+  const floor = `${MIN_MAJOR}.${MIN_MINOR}`;
+  if (seen.length === 0) {
+    return [
+      `SecureVector needs Python ${floor} or newer, and no Python was found on PATH.`,
+      '',
+      'Install one, then run this again:',
+      os.platform() === 'darwin'
+        ? '  brew install python@3.12        (or python.org/downloads)'
+        : os.platform() === 'win32'
+          ? '  winget install Python.Python.3.12   (or python.org/downloads)'
+          : '  sudo apt install python3.12     (or your distribution equivalent)',
+      '',
+      'This package will not install a Python runtime for you. Provisioning a',
+      'language runtime without being asked is the behaviour this product exists',
+      'to flag in other software.',
+    ].join('\n');
+  }
+  const found = seen.map((s) => `  ${s.candidate}: ${s.version.join('.')}`).join('\n');
+  return [
+    `SecureVector needs Python ${floor} or newer. The interpreters found are older:`,
+    '',
+    found,
+    '',
+    `Install Python ${floor}+ and run this again. If you already have one, make sure`,
+    'it is on PATH ahead of the versions above.',
+  ].join('\n');
+}
+
+module.exports = { findPython, explainMissing, versionOf, isNewEnough, MIN_MAJOR, MIN_MINOR, CANDIDATES };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@securevector/cli",
+  "version": "5.3.0",
+  "description": "Security and observability for AI agents. Launcher for npm and Node users; the product itself is published on PyPI and this installs the matching version.",
+  "keywords": [
+    "securevector",
+    "ai-security",
+    "llm-security",
+    "prompt-injection",
+    "agent-security",
+    "observability",
+    "threat-detection"
+  ],
+  "homepage": "https://securevector.io",
+  "bugs": "https://github.com/Secure-Vector/securevector-ai-threat-monitor/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Secure-Vector/securevector-ai-threat-monitor.git",
+    "directory": "npm"
+  },
+  "license": "Apache-2.0",
+  "author": "SecureVector",
+  "type": "commonjs",
+  "bin": {
+    "securevector": "bin/securevector.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.js'"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}