ukma-cli 0.1.0 → 0.1.1

package/README.md

@@ -1,71 +1,76 @@
-# `npx ukma-cli`
-
-The npm entry point for UKMA. It is a **launcher, not a second implementation**:
-`bin/ukma.js` finds the platform binary for this machine (downloading it from the
-GitHub release and verifying its published SHA-256 the first time) and then
-execs it, forwarding the exit code. All code-graph behaviour lives in the Rust
-binary.
-
-```shell
-npx ukma-cli                 # download + run `ukma install` (wire your agents)
-npx ukma-cli install --dry-run
-npx ukma-cli init            # inside a project
-npx ukma-cli --version
-```
-
-## Where it puts the binary
-
-- `$UKMA_BIN` — use this executable and do not download anything.
-- `$UKMA_BIN_DIR` (default `~/.ukma/bin`) — where a downloaded binary is cached.
-  The cache is per version: a downloaded `ukma` stays until you delete it, so
-  `npx ukma-cli@<version>` and a locally installed CLI can coexist.
-
-## What it does not do
-
-- It does not implement any CLI command; every argument is forwarded.
-- It does not modify your PATH: `npx` resolves it per invocation. For a
-  permanent install use `scripts/install.ps1` / `scripts/install.sh` or
-  `cargo install --path crates/ukma-cli`.
-- It does not run on Node < 18.
-
-## Publishing
-
-Publishing must happen **inside this directory** (`npm/`): `npm publish` reads
-`package.json` from the current directory, and the repository root deliberately
-has none. Running it there fails with:
-
-```
-npm error code ENOENT
-npm error path .../package.json
-npm error enoent Could not read package.json
-```
-
-`--prefix npm` does **not** help for `publish`; use the helper, which `cd`s for
-you, shows the tarball first, and stays a dry run unless you ask it to upload:
-
-```powershell
-.\scripts\publish_npm.ps1                                  # dry run
-.\scripts\publish_npm.ps1 -Tag v0.1.0 -Publish             # upload
-.\scripts\publish_npm.ps1 -Publish -Otp 123456             # account without a bypass-2FA token
-```
-
-```shell
-sh scripts/publish_npm.sh                                  # dry run
-sh scripts/publish_npm.sh --tag v0.1.0 --publish           # upload
-sh scripts/publish_npm.sh --publish --otp 123456
-```
-
-### Common failures
-
-| Error | Cause | Fix |
-| --- | --- | --- |
-| `ENOENT … package.json` | ran outside `npm/` | `cd npm` first, or use the helper |
-| `E403 … Two-factor authentication or granular access token with bypass 2fa enabled is required` | the credential cannot satisfy npm's 2FA check. **A Granular Access Token needs "Bypass 2FA" even when the account has 2FA disabled** (`npm profile get` → `two-factor auth: disabled`), and then there is no code to type | recreate the token with **Bypass 2FA** checked (Automation tokens always bypass), or `npm logout` + `npm login` and publish with the web-session credential. If the account really has 2FA on, pass `--otp <code>` |
-| `E402 Payment Required` | npm treated the package as private | keep `--access public` |
-| `E403 Forbidden - PUT … you do not have permission` | the name belongs to someone else, or the scope is not yours | pick another name in `package.json` (e.g. `@<your-scope>/ukma`) |
-| `npx ukma-cli` downloads and gets HTTP 404 | the GitHub release (with the bare `ukma-<triple>` assets) does not exist yet | publish the release first: `git tag v<version> && git push origin v<version>` |
-
-`.github/workflows/release.yml` publishes this package from `npm/` on every `v*`
-tag when the repository has an `NPM_TOKEN` secret; without the secret the release
-still produces the installers and `ukma upgrade` assets, and the npm step is
-skipped with a notice.
+# `npx ukma-cli`
+
+The npm entry point for UKMA. It is a **launcher, not a second implementation**:
+`bin/ukma.js` finds the platform binary for this machine (downloading it from the
+GitHub release and verifying its published SHA-256 the first time) and then
+execs it, forwarding the exit code. All code-graph behaviour lives in the Rust
+binary.
+
+```shell
+npx ukma-cli                 # download + run `ukma install` (wire your agents)
+npx ukma-cli install --dry-run
+npx ukma-cli init            # inside a project
+npx ukma-cli --version
+```
+
+## Where it puts the binary
+
+- `$UKMA_BIN` — use this executable and do not download anything.
+- `$UKMA_BIN_DIR` (default `~/.ukma/bin`) — where a downloaded binary is cached.
+  The cache is per version: a downloaded `ukma` stays until you delete it, so
+  `npx ukma-cli@<version>` and a locally installed CLI can coexist.
+
+## What it does not do
+
+- It does not implement any CLI command; every argument is forwarded.
+- It does not modify your PATH: `npx` resolves it per invocation. For a
+  permanent install use `scripts/install.ps1` / `scripts/install.sh` or
+  `cargo install --path crates/ukma-cli`.
+- It does not run on Node < 18.
+
+## Publishing
+
+Publishing must happen **inside this directory** (`npm/`): `npm publish` reads
+`package.json` from the current directory, and the repository root deliberately
+has none. Running it there fails with:
+
+```
+npm error code ENOENT
+npm error path .../package.json
+npm error enoent Could not read package.json
+```
+
+`--prefix npm` does **not** help for `publish`; use the helper, which `cd`s for
+you, shows the tarball first, and stays a dry run unless you ask it to upload:
+
+```powershell
+.\scripts\publish_npm.ps1                                  # dry run
+.\scripts\publish_npm.ps1 -Tag v0.1.0 -Publish             # upload
+.\scripts\publish_npm.ps1 -Publish -Otp 123456             # account without a bypass-2FA token
+```
+
+```shell
+sh scripts/publish_npm.sh                                  # dry run
+sh scripts/publish_npm.sh --tag v0.1.0 --publish           # upload
+sh scripts/publish_npm.sh --publish --otp 123456
+```
+
+### Common failures
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| `ENOENT … package.json` | ran outside `npm/` | `cd npm` first, or use the helper |
+| `E403 … Two-factor authentication or granular access token with bypass 2fa enabled is required` | the credential cannot satisfy npm's 2FA check. **A Granular Access Token needs "Bypass 2FA" even when the account has 2FA disabled** (`npm profile get` → `two-factor auth: disabled`), and then there is no code to type | recreate the token with **Bypass 2FA** checked (Automation tokens always bypass), or `npm logout` + `npm login` and publish with the web-session credential. If the account really has 2FA on, pass `--otp <code>` |
+| `E402 Payment Required` | npm treated the package as private | keep `--access public` |
+| `E403 Forbidden - PUT … you do not have permission` | the name belongs to someone else, or the scope is not yours | pick another name in `package.json` (e.g. `@<your-scope>/ukma`) |
+| `npx ukma-cli` downloads and gets HTTP 404 | the GitHub release (with the bare `ukma-<triple>` assets) does not exist yet, **or the repository is still private** — a private repo 404s every asset for anonymous users | publish the release first (`git tag v<version> && git push origin v<version>`), and make the repository public |
+| `npm view` still shows `0.0.0-stage` | that is npm's placeholder while the real version propagates; it takes ~2 minutes | wait and re-check instead of re-publishing |
+
+`.github/workflows/release.yml` publishes this package from `npm/` on every `v*`
+tag. It prefers **trusted publishing (OIDC)** — no secret, provenance attached —
+and falls back to an `NPM_TOKEN` secret (granular token with **Bypass 2FA**) when
+one is configured. Configure the trusted publisher on the package's npm page:
+owner `jacoblight-chen`, repository `UKMA`, workflow filename `release.yml`.
+
+Full runbook, including the setup for trusted publishing and the rollback rules:
+[`docs/publishing.md`](../docs/publishing.md).

package/bin/ukma.js

@@ -1,188 +1,188 @@
 #!/usr/bin/env node
-// The npx/npm launcher for UKMA.
-//
-// This file contains no code-graph logic: it locates the platform binary
-// (downloading it from the GitHub release and verifying its SHA-256 on first
-// use) and then replaces itself with it, forwarding the exit code. Everything
-// that decides what UKMA does lives in the Rust binary.
-//
-// `npx ukma-cli` with no arguments runs `ukma install`, matching CodeGraph's
-// "downloads and runs the installer in one go".
-
-const { spawnSync } = require('node:child_process');
-const { createHash } = require('node:crypto');
-const fs = require('node:fs');
-const https = require('node:https');
-const os = require('node:os');
-const path = require('node:path');
-
-const REPO = 'jacoblight-chen/UKMA';
-const TRIPLES = {
-  'win32-x64': 'x86_64-pc-windows-msvc',
-  'win32-arm64': 'aarch64-pc-windows-msvc',
-  'linux-x64': 'x86_64-unknown-linux-gnu',
-  'linux-arm64': 'aarch64-unknown-linux-gnu',
-  'darwin-x64': 'x86_64-apple-darwin',
-  'darwin-arm64': 'aarch64-apple-darwin',
-};
-
-function fail(message) {
-  process.stderr.write(`ukma: ${message}\n`);
-  process.exit(1);
-}
-
-function targetTriple() {
-  const triple = TRIPLES[`${process.platform}-${process.arch}`];
-  if (!triple) {
-    fail(
-      `no UKMA build is published for ${process.platform}/${process.arch}; ` +
-        'build it from source (cargo build -p ukma-cli) or set UKMA_BIN',
-    );
-  }
-  return triple;
-}
-
-function packageVersion() {
-  return require(path.join(__dirname, '..', 'package.json')).version;
-}
-
-function binaryDir() {
-  return process.env.UKMA_BIN_DIR || path.join(os.homedir(), '.ukma', 'bin');
-}
-
-function binaryPath() {
-  const name = process.platform === 'win32' ? 'ukma.exe' : 'ukma';
-  return path.join(binaryDir(), name);
-}
-
-function assetUrl(triple) {
-  const version = packageVersion();
-  const name = process.platform === 'win32' ? `ukma-${triple}.exe` : `ukma-${triple}`;
-  // A dev version is not published, so fall back to the rolling `latest` tag.
-  const base = /^\d+\.\d+\.\d+$/.test(version)
-    ? `https://github.com/${REPO}/releases/download/v${version}`
-    : `https://github.com/${REPO}/releases/latest/download`;
-  return { url: `${base}/${name}`, name };
-}
-
-function download(url, destination, redirects = 5) {
-  return new Promise((resolve, reject) => {
-    const request = https.get(url, { headers: { 'user-agent': 'ukma-cli-npm' } }, (response) => {
-      const status = response.statusCode || 0;
-      if (status >= 300 && status < 400 && response.headers.location) {
-        response.resume();
-        if (redirects <= 0) {
-          reject(new Error(`too many redirects for ${url}`));
-          return;
-        }
-        download(new URL(response.headers.location, url).toString(), destination, redirects - 1)
-          .then(resolve, reject);
-        return;
-      }
-      if (status !== 200) {
-        response.resume();
-        reject(new Error(`${url} returned HTTP ${status}`));
-        return;
-      }
-      const file = fs.createWriteStream(destination);
-      response.pipe(file);
-      file.on('finish', () => file.close(() => resolve()));
-      file.on('error', reject);
-    });
-    request.on('error', reject);
-    request.setTimeout(300000, () => request.destroy(new Error(`timeout downloading ${url}`)));
-  });
-}
-
-async function sha256(file) {
-  const hash = createHash('sha256');
-  await new Promise((resolve, reject) => {
-    const stream = fs.createReadStream(file);
-    stream.on('data', (chunk) => hash.update(chunk));
-    stream.on('end', resolve);
-    stream.on('error', reject);
-  });
-  return hash.digest('hex');
-}
-
-async function ensureBinary() {
-  if (process.env.UKMA_BIN) {
-    return process.env.UKMA_BIN;
-  }
-  const destination = binaryPath();
-  if (fs.existsSync(destination)) {
-    return destination;
-  }
-  const triple = targetTriple();
-  const { url, name } = assetUrl(triple);
-  const directory = path.dirname(destination);
-  const rootDirectory = path.dirname(directory);
-  const created = !fs.existsSync(directory);
-  const createdRoot = !fs.existsSync(rootDirectory);
-  fs.mkdirSync(directory, { recursive: true });
-  const temporary = `${destination}.download`;
-  const cleanup = () => {
-    // A failed download must not leave a partial binary (or the directories this
-    // run created) behind for the next attempt to trip over.
-    for (const leftover of [temporary, `${temporary}.sha256`]) {
-      fs.rmSync(leftover, { force: true });
-    }
-    for (const [ours, target] of [
-      [created, directory],
-      [createdRoot, rootDirectory],
-    ]) {
-      if (!ours) continue;
-      try {
-        if (fs.readdirSync(target).length === 0) {
-          fs.rmdirSync(target);
-        }
-      } catch {
-        /* the directory is in use; leaving it is harmless */
-      }
-    }
-  };
-  process.stderr.write(`ukma: downloading ${name} for ${triple}\n`);
-
-  let expected = null;
-  try {
-    const digestFile = `${temporary}.sha256`;
-    await download(`${url}.sha256`, digestFile);
-    expected = fs.readFileSync(digestFile, 'utf8').trim().split(/\s+/)[0].toLowerCase();
-    fs.rmSync(digestFile, { force: true });
-  } catch (error) {
-    process.stderr.write(`ukma: no published SHA-256 (${error.message}); continuing\n`);
-  }
-
-  try {
-    await download(url, temporary);
-    if (expected) {
-      const actual = await sha256(temporary);
-      if (actual !== expected) {
-        cleanup();
-        fail(`SHA-256 mismatch for ${name}: expected ${expected}, got ${actual}`);
-      }
-    }
-    if (process.platform !== 'win32') {
-      fs.chmodSync(temporary, 0o755);
-    }
-    fs.renameSync(temporary, destination);
-  } catch (error) {
-    cleanup();
-    throw error;
-  }
-  return destination;
-}
-
-async function main() {
-  const binary = await ensureBinary();
-  const args = process.argv.slice(2);
-  // CodeGraph parity: `npx <package>` with no arguments runs the install step.
-  const forwarded = args.length === 0 ? ['install'] : args;
-  const result = spawnSync(binary, forwarded, { stdio: 'inherit' });
-  if (result.error) {
-    fail(`cannot run ${binary} (${result.error.message})`);
-  }
-  process.exit(result.status === null ? 1 : result.status);
-}
-
-main().catch((error) => fail(error.message));
+// The npx/npm launcher for UKMA.
+//
+// This file contains no code-graph logic: it locates the platform binary
+// (downloading it from the GitHub release and verifying its SHA-256 on first
+// use) and then replaces itself with it, forwarding the exit code. Everything
+// that decides what UKMA does lives in the Rust binary.
+//
+// `npx ukma-cli` with no arguments runs `ukma install`, matching CodeGraph's
+// "downloads and runs the installer in one go".
+
+const { spawnSync } = require('node:child_process');
+const { createHash } = require('node:crypto');
+const fs = require('node:fs');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO = 'jacoblight-chen/UKMA';
+const TRIPLES = {
+  'win32-x64': 'x86_64-pc-windows-msvc',
+  'win32-arm64': 'aarch64-pc-windows-msvc',
+  'linux-x64': 'x86_64-unknown-linux-gnu',
+  'linux-arm64': 'aarch64-unknown-linux-gnu',
+  'darwin-x64': 'x86_64-apple-darwin',
+  'darwin-arm64': 'aarch64-apple-darwin',
+};
+
+function fail(message) {
+  process.stderr.write(`ukma: ${message}\n`);
+  process.exit(1);
+}
+
+function targetTriple() {
+  const triple = TRIPLES[`${process.platform}-${process.arch}`];
+  if (!triple) {
+    fail(
+      `no UKMA build is published for ${process.platform}/${process.arch}; ` +
+        'build it from source (cargo build -p ukma-cli) or set UKMA_BIN',
+    );
+  }
+  return triple;
+}
+
+function packageVersion() {
+  return require(path.join(__dirname, '..', 'package.json')).version;
+}
+
+function binaryDir() {
+  return process.env.UKMA_BIN_DIR || path.join(os.homedir(), '.ukma', 'bin');
+}
+
+function binaryPath() {
+  const name = process.platform === 'win32' ? 'ukma.exe' : 'ukma';
+  return path.join(binaryDir(), name);
+}
+
+function assetUrl(triple) {
+  const version = packageVersion();
+  const name = process.platform === 'win32' ? `ukma-${triple}.exe` : `ukma-${triple}`;
+  // A dev version is not published, so fall back to the rolling `latest` tag.
+  const base = /^\d+\.\d+\.\d+$/.test(version)
+    ? `https://github.com/${REPO}/releases/download/v${version}`
+    : `https://github.com/${REPO}/releases/latest/download`;
+  return { url: `${base}/${name}`, name };
+}
+
+function download(url, destination, redirects = 5) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(url, { headers: { 'user-agent': 'ukma-cli-npm' } }, (response) => {
+      const status = response.statusCode || 0;
+      if (status >= 300 && status < 400 && response.headers.location) {
+        response.resume();
+        if (redirects <= 0) {
+          reject(new Error(`too many redirects for ${url}`));
+          return;
+        }
+        download(new URL(response.headers.location, url).toString(), destination, redirects - 1)
+          .then(resolve, reject);
+        return;
+      }
+      if (status !== 200) {
+        response.resume();
+        reject(new Error(`${url} returned HTTP ${status}`));
+        return;
+      }
+      const file = fs.createWriteStream(destination);
+      response.pipe(file);
+      file.on('finish', () => file.close(() => resolve()));
+      file.on('error', reject);
+    });
+    request.on('error', reject);
+    request.setTimeout(300000, () => request.destroy(new Error(`timeout downloading ${url}`)));
+  });
+}
+
+async function sha256(file) {
+  const hash = createHash('sha256');
+  await new Promise((resolve, reject) => {
+    const stream = fs.createReadStream(file);
+    stream.on('data', (chunk) => hash.update(chunk));
+    stream.on('end', resolve);
+    stream.on('error', reject);
+  });
+  return hash.digest('hex');
+}
+
+async function ensureBinary() {
+  if (process.env.UKMA_BIN) {
+    return process.env.UKMA_BIN;
+  }
+  const destination = binaryPath();
+  if (fs.existsSync(destination)) {
+    return destination;
+  }
+  const triple = targetTriple();
+  const { url, name } = assetUrl(triple);
+  const directory = path.dirname(destination);
+  const rootDirectory = path.dirname(directory);
+  const created = !fs.existsSync(directory);
+  const createdRoot = !fs.existsSync(rootDirectory);
+  fs.mkdirSync(directory, { recursive: true });
+  const temporary = `${destination}.download`;
+  const cleanup = () => {
+    // A failed download must not leave a partial binary (or the directories this
+    // run created) behind for the next attempt to trip over.
+    for (const leftover of [temporary, `${temporary}.sha256`]) {
+      fs.rmSync(leftover, { force: true });
+    }
+    for (const [ours, target] of [
+      [created, directory],
+      [createdRoot, rootDirectory],
+    ]) {
+      if (!ours) continue;
+      try {
+        if (fs.readdirSync(target).length === 0) {
+          fs.rmdirSync(target);
+        }
+      } catch {
+        /* the directory is in use; leaving it is harmless */
+      }
+    }
+  };
+  process.stderr.write(`ukma: downloading ${name} for ${triple}\n`);
+
+  let expected = null;
+  try {
+    const digestFile = `${temporary}.sha256`;
+    await download(`${url}.sha256`, digestFile);
+    expected = fs.readFileSync(digestFile, 'utf8').trim().split(/\s+/)[0].toLowerCase();
+    fs.rmSync(digestFile, { force: true });
+  } catch (error) {
+    process.stderr.write(`ukma: no published SHA-256 (${error.message}); continuing\n`);
+  }
+
+  try {
+    await download(url, temporary);
+    if (expected) {
+      const actual = await sha256(temporary);
+      if (actual !== expected) {
+        cleanup();
+        fail(`SHA-256 mismatch for ${name}: expected ${expected}, got ${actual}`);
+      }
+    }
+    if (process.platform !== 'win32') {
+      fs.chmodSync(temporary, 0o755);
+    }
+    fs.renameSync(temporary, destination);
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+  return destination;
+}
+
+async function main() {
+  const binary = await ensureBinary();
+  const args = process.argv.slice(2);
+  // CodeGraph parity: `npx <package>` with no arguments runs the install step.
+  const forwarded = args.length === 0 ? ['install'] : args;
+  const result = spawnSync(binary, forwarded, { stdio: 'inherit' });
+  if (result.error) {
+    fail(`cannot run ${binary} (${result.error.message})`);
+  }
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+main().catch((error) => fail(error.message));

package/package.json

@@ -1,30 +1,30 @@
-{
-  "name": "ukma-cli",
-  "version": "0.1.0",
-  "description": "UKMA launcher for npm/npx: downloads the platform binary and runs it (no code-graph logic here)",
-  "bin": {
-    "ukma": "bin/ukma.js"
-  },
-  "files": [
-    "bin/ukma.js",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jacoblight-chen/UKMA.git"
-  },
-  "homepage": "https://github.com/jacoblight-chen/UKMA#readme",
-  "keywords": [
-    "code-graph",
-    "mcp",
-    "codegraph",
-    "ukma"
-  ],
-  "publishConfig": {
-    "access": "public"
-  }
-}
+{
+  "name": "ukma-cli",
+  "version": "0.1.1",
+  "description": "UKMA launcher for npm/npx: downloads the platform binary and runs it (no code-graph logic here)",
+  "bin": {
+    "ukma": "bin/ukma.js"
+  },
+  "files": [
+    "bin/ukma.js",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jacoblight-chen/UKMA.git"
+  },
+  "homepage": "https://github.com/jacoblight-chen/UKMA#readme",
+  "keywords": [
+    "code-graph",
+    "mcp",
+    "codegraph",
+    "ukma"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}