utem-cli 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# utem-cli
+
+npm distribution channel for the **UTEM CLI** (`utem`) — the control-plane
+command-line interface for the [UTEM security platform](https://utem.innavoto.com).
+
+```bash
+# one-off
+npx utem-cli --help
+
+# global install
+npm i -g utem-cli
+utem --help
+```
+
+## What this package is (and isn't)
+
+The UTEM CLI itself is a **pure-Python** application published on PyPI as
+[`utem`](https://pypi.org/project/utem/) (the wheel is
+`utem-<version>-py3-none-any.whl` — architecture independent). It is also
+distributed via Homebrew (`Innavoto/utem-homebrew-tap`).
+
+This npm package is a **thin wrapper**, not a reimplementation. On install it:
+
+1. Locates a Python 3.10+ interpreter on your `PATH`.
+2. Creates an isolated virtualenv inside the installed package (`.venv/`).
+3. `pip install`s the pinned `utem` release from PyPI into that venv.
+
+The `utem` command shipped by this package then execs the CLI inside that
+venv, forwarding all arguments, stdio and exit codes. Your global Python
+environment is never modified.
+
+### Requirement: Python 3.10+
+
+Because the CLI is a Python program, this wrapper **requires Python 3.10 or
+newer on your `PATH`** (the same requirement the Homebrew formula declares via
+`depends_on "python3"`). If Python is missing, install fails soft with an
+actionable message and the CLI is provisioned lazily on first `utem` run.
+
+On Debian/Ubuntu you may also need `python3-venv` (`apt install python3-venv`).
+
+### Design tradeoff
+
+Two common patterns exist for shipping a CLI on npm:
+
+| Approach | Used here? | Why / why not |
+|---|---|---|
+| **Prebuilt-binary downloader** (esbuild style: postinstall fetches a per-OS/arch native binary from GitHub Releases, checksum-verified) | No | The UTEM CLI has **no native binary** and **no per-platform GitHub release assets** — it is pure Python. There is nothing arch-specific to download. |
+| **`optionalDependencies` per-platform packages** | No | Same reason — there are no platform-specific artifacts to split into sub-packages. |
+| **PyPI-install shim** (provision the real package into an isolated venv) | **Yes** | The canonical artifact is a pure-Python wheel already on PyPI; installing it into an isolated venv is the simplest correct wrapper and requires no new binary build pipeline. |
+
+If the CLI is later shipped as self-contained native binaries (e.g. via
+PyInstaller) attached to versioned GitHub Releases, this wrapper can be
+switched to the checksum-verified downloader model without changing its public
+interface.
+
+## Environment variables
+
+| Variable | Effect |
+|---|---|
+| `UTEM_SKIP_POSTINSTALL=1` | Skip provisioning during `npm install` (CI / air-gapped). The CLI is provisioned lazily on first run. |
+
+CLI auth (`UTEM_API_URL`, `UTEM_TOKEN`, `UTEM_TENANT_ID`) is documented in the
+[main CLI README](https://github.com/Innavoto/utem-cli#readme).
+
+## Versioning
+
+This wrapper's version tracks the `utem` PyPI release it installs
+(currently **0.1.0**). Publishing a new wrapper version bumps the pinned CLI
+version in lockstep.
+
+## License
+
+Proprietary — © Innavoto India Pvt Ltd. See the
+[main repository](https://github.com/Innavoto/utem-cli).

package/bin/utem.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * `utem` launcher. Resolves the CLI provisioned into the package-local venv
+ * and execs it, forwarding argv, stdio, exit code and signals. If the venv
+ * isn't present yet (e.g. installed with --ignore-scripts), it provisions on
+ * first run.
+ */
+
+const { spawnSync } = require('child_process');
+const { ensureInstalled } = require('../lib/install');
+
+function fail(result) {
+  console.error('[utem] Unable to launch the UTEM CLI.');
+  console.error(`[utem] Reason: ${result.reason}`);
+  console.error(`[utem] ${result.detail}`);
+  process.exit(127);
+}
+
+const result = ensureInstalled({ silent: true });
+if (!result.ok) {
+  // Retry once, this time surfacing installer output for diagnostics.
+  const verbose = ensureInstalled({ silent: false, force: true });
+  if (!verbose.ok) fail(verbose);
+  result.utemExe = verbose.utemExe;
+}
+
+const child = spawnSync(result.utemExe, process.argv.slice(2), {
+  stdio: 'inherit',
+});
+
+if (child.error) {
+  console.error(`[utem] Failed to execute ${result.utemExe}: ${child.error.message}`);
+  process.exit(1);
+}
+
+// Propagate a terminating signal as the conventional 128+signal exit code.
+if (child.signal) {
+  process.exit(1);
+}
+
+process.exit(child.status === null ? 1 : child.status);

package/lib/install.js

@@ -0,0 +1,120 @@
+'use strict';
+
+/**
+ * Provision the UTEM CLI (`utem`) from PyPI into an isolated virtualenv that
+ * lives inside this installed npm package. Shared by the postinstall script
+ * and the lazy fallback in bin/utem.js (for `npm i --ignore-scripts`).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const {
+  PINNED_CLI_VERSION,
+  MIN_PYTHON,
+  pythonCandidates,
+  parsePythonVersion,
+  isSupportedPython,
+  venvLayout,
+} = require('./platform');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+
+function run(cmd, args, opts) {
+  return spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+}
+
+/**
+ * Find the first Python interpreter on PATH that satisfies the CLI's minimum
+ * version (3.10+).
+ * @returns {{exe:string, version:{major:number,minor:number,patch:number}}|null}
+ */
+function findSupportedPython() {
+  for (const exe of pythonCandidates()) {
+    const res = run(exe, ['--version']);
+    if (res.error || res.status !== 0) continue;
+    const version = parsePythonVersion((res.stdout || '') + (res.stderr || ''));
+    if (isSupportedPython(version)) return { exe, version };
+  }
+  return null;
+}
+
+/**
+ * Ensure the `utem` CLI is installed into the package-local venv.
+ * Never throws — always returns a result object so callers can decide how
+ * loudly to fail (postinstall warns; the bin shim errors hard).
+ *
+ * @param {{silent?:boolean, force?:boolean}} [opts]
+ * @returns {{ok:boolean, utemExe?:string, reason?:string, detail?:string}}
+ */
+function ensureInstalled(opts = {}) {
+  const { silent = false, force = false } = opts;
+  const layout = venvLayout(PKG_ROOT);
+
+  if (!force && fs.existsSync(layout.utemExe)) {
+    return { ok: true, utemExe: layout.utemExe };
+  }
+
+  const py = findSupportedPython();
+  if (!py) {
+    return {
+      ok: false,
+      reason: 'no-python',
+      detail:
+        `No Python >= ${MIN_PYTHON.major}.${MIN_PYTHON.minor} found on PATH. ` +
+        `The UTEM CLI is a Python application; install Python 3.10+ ` +
+        `(https://www.python.org/downloads/) and reinstall, or install the CLI ` +
+        `directly with: pipx install utem==${PINNED_CLI_VERSION}`,
+    };
+  }
+
+  const stdio = silent ? 'ignore' : 'inherit';
+
+  // 1. Create the isolated venv.
+  const mkvenv = run(py.exe, ['-m', 'venv', layout.venvDir], { stdio });
+  if (mkvenv.status !== 0) {
+    return {
+      ok: false,
+      reason: 'venv-failed',
+      detail:
+        `Failed to create a virtualenv with "${py.exe} -m venv". On Debian/Ubuntu ` +
+        `you may need the python3-venv package (apt install python3-venv).`,
+    };
+  }
+
+  // 2. Install the pinned CLI from PyPI into the venv.
+  //    --disable-pip-version-check keeps output clean; pin the exact version.
+  const pip = run(
+    layout.pythonExe,
+    [
+      '-m',
+      'pip',
+      'install',
+      '--disable-pip-version-check',
+      '--no-input',
+      `utem==${PINNED_CLI_VERSION}`,
+    ],
+    { stdio }
+  );
+  if (pip.status !== 0) {
+    return {
+      ok: false,
+      reason: 'pip-failed',
+      detail:
+        `pip failed to install utem==${PINNED_CLI_VERSION} from PyPI. Check network ` +
+        `access to pypi.org, then reinstall.`,
+    };
+  }
+
+  if (!fs.existsSync(layout.utemExe)) {
+    return {
+      ok: false,
+      reason: 'entrypoint-missing',
+      detail: `Install completed but the utem entry point was not found at ${layout.utemExe}.`,
+    };
+  }
+
+  return { ok: true, utemExe: layout.utemExe };
+}
+
+module.exports = { ensureInstalled, findSupportedPython, PKG_ROOT };

package/lib/platform.js

@@ -0,0 +1,114 @@
+'use strict';
+
+/**
+ * Platform / Python resolution for the UTEM CLI npm wrapper.
+ *
+ * The UTEM CLI (`utem`) is a *pure-Python* package published on PyPI as
+ * `utem` (wheel: utem-<version>-py3-none-any.whl — arch independent). This
+ * wrapper therefore does NOT download a per-arch native binary; instead it
+ * provisions the PyPI package into an isolated virtualenv co-located with the
+ * installed npm package, and shims the `utem` entry point to it.
+ *
+ * All functions here are pure and unit-testable with `node --test`.
+ */
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * The UTEM CLI release the wrapper pins to. Kept in lockstep with the
+ * `version` in this package.json and the `utem` PyPI release. There is no
+ * GitHub *binary* release for this CLI (it is pure Python), so "the latest
+ * release tag" is the PyPI version 0.1.0.
+ */
+const PINNED_CLI_VERSION = '0.1.0';
+
+/** Minimum Python the CLI supports (pyproject: requires-python >=3.10). */
+const MIN_PYTHON = Object.freeze({ major: 3, minor: 10 });
+
+/**
+ * Candidate Python interpreter executables to probe, most-specific first.
+ * @param {string} [platform] process.platform override (for testing)
+ * @returns {string[]}
+ */
+function pythonCandidates(platform) {
+  const plat = platform || process.platform;
+  if (plat === 'win32') {
+    // `py` is the Windows launcher; `python` is the usual PATH name.
+    return ['python3', 'python', 'py'];
+  }
+  return ['python3', 'python'];
+}
+
+/**
+ * Parse the output of `python --version` (e.g. "Python 3.10.4").
+ * @param {string} out
+ * @returns {{major:number,minor:number,patch:number}|null}
+ */
+function parsePythonVersion(out) {
+  if (typeof out !== 'string') return null;
+  const m = out.match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  if (!m) return null;
+  return {
+    major: Number(m[1]),
+    minor: Number(m[2]),
+    patch: m[3] ? Number(m[3]) : 0,
+  };
+}
+
+/**
+ * Is a parsed Python version >= the CLI's minimum (3.10)?
+ * @param {{major:number,minor:number}|null} v
+ * @returns {boolean}
+ */
+function isSupportedPython(v) {
+  if (!v) return false;
+  if (v.major !== MIN_PYTHON.major) return v.major > MIN_PYTHON.major;
+  return v.minor >= MIN_PYTHON.minor;
+}
+
+/**
+ * Compute the venv layout for a given package root + platform. Windows uses
+ * `Scripts\` and `.exe`; POSIX uses `bin/`.
+ * @param {string} pkgRoot absolute path to the installed npm package root
+ * @param {string} [platform] process.platform override (for testing)
+ * @returns {{venvDir:string,binDir:string,pythonExe:string,utemExe:string}}
+ */
+function venvLayout(pkgRoot, platform) {
+  const plat = platform || process.platform;
+  const venvDir = path.join(pkgRoot, '.venv');
+  if (plat === 'win32') {
+    const binDir = path.join(venvDir, 'Scripts');
+    return {
+      venvDir,
+      binDir,
+      pythonExe: path.join(binDir, 'python.exe'),
+      utemExe: path.join(binDir, 'utem.exe'),
+    };
+  }
+  const binDir = path.join(venvDir, 'bin');
+  return {
+    venvDir,
+    binDir,
+    pythonExe: path.join(binDir, 'python'),
+    utemExe: path.join(binDir, 'utem'),
+  };
+}
+
+/**
+ * Human-readable platform/arch label for diagnostics.
+ * @returns {string}
+ */
+function platformLabel() {
+  return `${process.platform}/${process.arch} (node ${process.version}, ${os.release()})`;
+}
+
+module.exports = {
+  PINNED_CLI_VERSION,
+  MIN_PYTHON,
+  pythonCandidates,
+  parsePythonVersion,
+  isSupportedPython,
+  venvLayout,
+  platformLabel,
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "utem-cli",
+  "version": "0.1.0",
+  "description": "npm wrapper for the UTEM CLI (utem) — control plane for the UTEM security platform. Installs the official PyPI package into an isolated environment.",
+  "keywords": [
+    "utem",
+    "security",
+    "cli",
+    "sast",
+    "sca",
+    "code-security",
+    "innavoto"
+  ],
+  "homepage": "https://github.com/Innavoto/utem-cli#readme",
+  "bugs": {
+    "url": "https://github.com/Innavoto/utem-cli/issues"
+  },
+  "license": "SEE LICENSE IN README.md",
+  "author": "Innavoto Technologies <engineering@innavoto.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Innavoto/utem-cli.git",
+    "directory": "npm"
+  },
+  "bin": {
+    "utem": "bin/utem.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "os": [
+    "darwin",
+    "linux",
+    "win32"
+  ],
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/",
+    "README.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test test/*.test.js",
+    "lint": "node scripts/lint.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/lint.js

@@ -0,0 +1,45 @@
+'use strict';
+
+/**
+ * Zero-dependency lint: syntax-checks every shipped/source .js file with
+ * `node --check`. Avoids pulling eslint (and a network install) into a thin
+ * wrapper package while still catching parse errors in CI and pre-publish.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const root = path.resolve(__dirname, '..');
+const dirs = ['bin', 'lib', 'scripts', 'test'];
+
+/** @returns {string[]} */
+function collect() {
+  const files = [];
+  for (const d of dirs) {
+    const abs = path.join(root, d);
+    if (!fs.existsSync(abs)) continue;
+    for (const name of fs.readdirSync(abs)) {
+      if (name.endsWith('.js')) files.push(path.join(abs, name));
+    }
+  }
+  return files;
+}
+
+let failed = 0;
+for (const file of collect()) {
+  const res = spawnSync(process.execPath, ['--check', file], { encoding: 'utf8' });
+  const rel = path.relative(root, file);
+  if (res.status === 0) {
+    console.log(`ok   ${rel}`);
+  } else {
+    failed += 1;
+    console.error(`FAIL ${rel}\n${res.stderr}`);
+  }
+}
+
+if (failed > 0) {
+  console.error(`\n${failed} file(s) failed lint.`);
+  process.exit(1);
+}
+console.log('\nAll files passed node --check.');

package/scripts/postinstall.js

@@ -0,0 +1,42 @@
+'use strict';
+
+/**
+ * postinstall: provision the UTEM CLI from PyPI into a package-local venv.
+ *
+ * Design choice: this NEVER hard-fails the enclosing `npm install`. A failed
+ * postinstall (e.g. no Python on PATH) exits 0 with a loud, actionable
+ * warning; the `utem` bin shim will retry the install lazily on first run and
+ * error clearly if it still can't provision. This keeps `npm i -g` from
+ * aborting a user's whole toolchain over an optional shim.
+ */
+
+const { PINNED_CLI_VERSION, platformLabel } = require('../lib/platform');
+const { ensureInstalled } = require('../lib/install');
+
+// Escape hatches for CI / air-gapped installs.
+if (process.env.UTEM_SKIP_POSTINSTALL === '1') {
+  console.log('[utem] UTEM_SKIP_POSTINSTALL=1 set — skipping CLI provisioning.');
+  process.exit(0);
+}
+
+console.log(
+  `[utem] Provisioning UTEM CLI ${PINNED_CLI_VERSION} from PyPI on ${platformLabel()} ...`
+);
+
+const result = ensureInstalled({ silent: false });
+
+if (result.ok) {
+  console.log(`[utem] Installed. Run "utem --help" to get started.`);
+  process.exit(0);
+}
+
+// Warn, but do not fail the install.
+console.warn('');
+console.warn('[utem] WARNING: could not provision the UTEM CLI during install.');
+console.warn(`[utem] Reason: ${result.reason}`);
+console.warn(`[utem] ${result.detail}`);
+console.warn(
+  '[utem] The first time you run `utem`, provisioning will be retried automatically.'
+);
+console.warn('');
+process.exit(0);