@oh-hai/cli 0.2.0 → 0.2.2

package/dist/commands/update-check.js

@@ -0,0 +1,203 @@
+// Update check + install-method detection for `oh-hai upgrade` and doctor's advisory
+// "update available" nudge (#343, the self-update piece of #277). Zero-dependency: a focused
+// semver comparator (the CLI stays dep-free beyond @oh-hai/ma2h-core) and a single
+// unauthenticated GET of the npm packument. `checkForUpdate` NEVER throws — both callers
+// (doctor's advisory check, the upgrade command) receive a structured result and apply their
+// own policy (doctor omits on error; upgrade turns error into a NETWORK exit).
+import { MAX_TIMER_MS } from "./messaging/shared.js";
+/** The published package name (matches cli/package.json "name"). */
+export const PACKAGE_NAME = "@oh-hai/cli";
+/** The npm packument URL — the scoped name is URL-encoded (`/` → `%2F`). The `/<name>/latest`
+ *  shortcut is unreliable for scoped packages, so we read `dist-tags.latest` off the packument.
+ *  `dist-tags.latest` is always a STABLE version (never a prerelease), which is exactly what a
+ *  running build should be compared against. */
+export const REGISTRY_PACKUMENT_URL = "https://registry.npmjs.org/@oh-hai%2Fcli";
+/** The "abbreviated" packument media type: npm's registry returns a much smaller document
+ *  (name + versions' minimal metadata + `dist-tags`) than the full packument, and `dist-tags.latest`
+ *  is present in both. We read only `dist-tags.latest`, so the abbreviated form is behavior-equivalent
+ *  and lighter — worth it since `doctor` fetches this on every run. */
+const ABBREVIATED_PACKUMENT_ACCEPT = "application/vnd.npm.install-v1+json";
+/** Default per-request bound for the registry probe; mirrors doctor's DEFAULT_PROBE_TIMEOUT_MS so
+ *  offline is an explicit state, never a silent hang. Module-private — no external consumer. */
+const DEFAULT_UPDATE_TIMEOUT_MS = 10_000;
+/** Parse `major.minor.patch[-prerelease]` (with an optional leading `v`). Returns undefined for
+ *  anything that doesn't match — the comparator treats an unparseable version as "no update" so a
+ *  garbage `latest` never triggers an upgrade nag. Trailing build metadata is ignored. */
+function parseVersion(value) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(value.trim());
+    if (m === null)
+        return undefined;
+    const major = Number(m[1]);
+    const minor = Number(m[2]);
+    const patch = Number(m[3]);
+    if (Number.isNaN(major) || Number.isNaN(minor) || Number.isNaN(patch))
+        return undefined;
+    const preRaw = m[4];
+    const pre = preRaw !== undefined && preRaw !== "" ? preRaw.split(".") : [];
+    return { core: [major, minor, patch], pre };
+}
+function compareTriple(a, b) {
+    if (a[0] !== b[0])
+        return a[0] > b[0] ? 1 : -1;
+    if (a[1] !== b[1])
+        return a[1] > b[1] ? 1 : -1;
+    if (a[2] !== b[2])
+        return a[2] > b[2] ? 1 : -1;
+    return 0;
+}
+/** Compare two prerelease identifiers per semver §11: numeric identifiers compare numerically and
+ *  have LOWER precedence than alphanumeric ones; alphanumeric compare lexically (ASCII). */
+function comparePreId(a, b) {
+    const aNum = /^\d+$/.test(a);
+    const bNum = /^\d+$/.test(b);
+    if (aNum && bNum) {
+        const x = Number(a);
+        const y = Number(b);
+        return x > y ? 1 : x < y ? -1 : 0;
+    }
+    if (aNum)
+        return -1; // numeric < alphanumeric
+    if (bNum)
+        return 1;
+    return a > b ? 1 : a < b ? -1 : 0;
+}
+/**
+ * Semver precedence for the shapes this package publishes (`major.minor.patch[-prerelease]`).
+ * Returns -1 (a < b), 0 (equal), or 1 (a > b). A version WITH a prerelease is lower than the same
+ * core WITHOUT one (`1.0.0-beta.0` < `1.0.0`). Unparseable input compares as equal (0) so a bad
+ * `latest` is never read as newer.
+ */
+export function compareSemver(a, b) {
+    const pa = parseVersion(a);
+    const pb = parseVersion(b);
+    if (pa === undefined || pb === undefined)
+        return 0;
+    const core = compareTriple(pa.core, pb.core);
+    if (core !== 0)
+        return core;
+    // Equal core: no-prerelease outranks any prerelease.
+    if (pa.pre.length === 0 && pb.pre.length === 0)
+        return 0;
+    if (pa.pre.length === 0)
+        return 1;
+    if (pb.pre.length === 0)
+        return -1;
+    const shared = Math.min(pa.pre.length, pb.pre.length);
+    for (let i = 0; i < shared; i++) {
+        const cmp = comparePreId(pa.pre[i] ?? "", pb.pre[i] ?? "");
+        if (cmp !== 0)
+            return cmp;
+    }
+    // All shared identifiers equal → the longer identifier set has higher precedence.
+    if (pa.pre.length > pb.pre.length)
+        return 1;
+    if (pa.pre.length < pb.pre.length)
+        return -1;
+    return 0;
+}
+/** Split a path on either separator so classification is OS-independent in tests (a Windows
+ *  execPath fixture still resolves its basename on a posix host). */
+function baseName(path) {
+    const parts = path.split(/[/\\]/);
+    return parts[parts.length - 1] ?? path;
+}
+/**
+ * True when `modulePath` sits under a GLOBAL npm prefix (safe to `npm i -g`). A project-local
+ * install, an `npx` / `npm exec` cache, or a Homebrew `libexec` prefix ALSO lives under
+ * `node_modules` but must NOT be treated as global — running `npm i -g` there would mutate an
+ * unrelated global prefix (or fight brew's symlink) instead of the actual invocation (#349 review).
+ * So match only the global-prefix layout: POSIX `<prefix>/lib/node_modules/…` (covers /usr/local,
+ * /opt/homebrew, nvm, ~/.npm-global) or Windows `%AppData%\npm\node_modules\…`; never under `libexec`.
+ */
+function isGlobalNpmPrefix(modulePath) {
+    if (/[/\\]libexec[/\\]/i.test(modulePath))
+        return false;
+    if (/[/\\]lib[/\\]node_modules[/\\]/i.test(modulePath))
+        return true;
+    return /\\npm\\node_modules\\/i.test(modulePath);
+}
+/**
+ * Classify how the CLI was installed, from injected facts (pure → fully unit-testable). Only a
+ * genuine compiled standalone classifies as `binary`, because that method now self-updates in place
+ * by replacing `process.execPath` — misclassifying a shared `node`/`bun` interpreter running our
+ * script as `binary` would let `oh-hai upgrade` overwrite the user's runtime (#358 review). So the
+ * order is deliberate:
+ *  1. a `.ts` module path → running from source via tsx (`dev`);
+ *  2. a module UNDER `node_modules` → an npm/script install, classified by prefix (GLOBAL prefix →
+ *     `npm-global`; project-local / npx / brew → `unknown` guidance, never a global mutation). This
+ *     is checked BEFORE the standalone fallback so a renamed interpreter (`nodejs`, `node24`, a
+ *     distro wrapper) running an npm dist can never fall through to the self-update path;
+ *  3. otherwise, a NON-interpreter executable means the compiled standalone IS the executable
+ *     (`binary`) — interpreter detection is a broad `node`/`bun`/`deno`-prefix match so renamed Node
+ *     runtimes are excluded;
+ *  4. an interpreter running a built dist outside `node_modules` → a local checkout (`dev`);
+ *  5. anything else → `unknown`.
+ */
+export function classifyInstall(facts) {
+    const { execPath, modulePath } = facts;
+    if (/\.[cm]?ts$/i.test(modulePath))
+        return "dev";
+    // An npm/script install lives under node_modules — classify it as such regardless of the
+    // interpreter's basename, so a distro `nodejs`/`node24`/wrapper never enters the binary path.
+    if (/[/\\]node_modules[/\\]/.test(modulePath)) {
+        return isGlobalNpmPrefix(modulePath) ? "npm-global" : "unknown";
+    }
+    // A compiled standalone runs AS its own executable (execPath is the CLI binary). Detect a script
+    // interpreter broadly — any `node`/`bun`/`deno`-prefixed basename, including renamed `nodejs` /
+    // `node24` — so only a true standalone executable reaches the in-place self-update.
+    const execBase = baseName(execPath).toLowerCase();
+    const execIsInterpreter = /^(node|bun|deno)/.test(execBase);
+    if (!execIsInterpreter)
+        return "binary";
+    if (modulePath !== "")
+        return "dev";
+    return "unknown";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function extractLatest(body) {
+    if (typeof body !== "object" || body === null)
+        return undefined;
+    const distTags = body["dist-tags"];
+    if (typeof distTags !== "object" || distTags === null)
+        return undefined;
+    const latest = distTags["latest"];
+    return typeof latest === "string" ? latest : undefined;
+}
+/**
+ * Fetch the latest published `@oh-hai/cli` version and compare it to `current`. Never throws: any
+ * transport failure, non-200, unparseable body, or missing `dist-tags.latest` returns a result
+ * with `error` set and `updateAvailable` false. `timeoutMs` bounds the request (defaulted on
+ * absent/0/negative, clamped to the timer ceiling).
+ */
+export async function checkForUpdate(current, fetchImpl, timeoutMs) {
+    const bound = Math.min(timeoutMs !== undefined && timeoutMs > 0 ? timeoutMs : DEFAULT_UPDATE_TIMEOUT_MS, MAX_TIMER_MS);
+    let response;
+    try {
+        response = await fetchImpl(REGISTRY_PACKUMENT_URL, {
+            method: "GET",
+            headers: { Accept: ABBREVIATED_PACKUMENT_ACCEPT },
+            signal: AbortSignal.timeout(bound),
+        });
+    }
+    catch (error) {
+        return { current, updateAvailable: false, error: `registry unreachable — ${errorMessage(error)}` };
+    }
+    if (response.status !== 200) {
+        return { current, updateAvailable: false, error: `registry returned HTTP ${response.status}` };
+    }
+    let body;
+    try {
+        body = response.json !== undefined ? await response.json() : undefined;
+    }
+    catch (error) {
+        return { current, updateAvailable: false, error: `could not parse registry response — ${errorMessage(error)}` };
+    }
+    const latest = extractLatest(body);
+    if (latest === undefined) {
+        return { current, updateAvailable: false, error: "registry response had no dist-tags.latest" };
+    }
+    return { current, latest, updateAvailable: compareSemver(latest, current) > 0 };
+}
+//# sourceMappingURL=update-check.js.map

package/dist/commands/update-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-check.js","sourceRoot":"","sources":["../../src/commands/update-check.ts"],"names":[],"mappings":"AAAA,qFAAqF;AACrF,6FAA6F;AAC7F,mFAAmF;AACnF,yFAAyF;AACzF,6FAA6F;AAC7F,+EAA+E;AAG/E,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAErD,oEAAoE;AACpE,MAAM,CAAC,MAAM,YAAY,GAAG,aAAa,CAAC;AAE1C;;;gDAGgD;AAChD,MAAM,CAAC,MAAM,sBAAsB,GAAG,0CAA0C,CAAC;AAEjF;;;uEAGuE;AACvE,MAAM,4BAA4B,GAAG,qCAAqC,CAAC;AAE3E;gGACgG;AAChG,MAAM,yBAAyB,GAAG,MAAM,CAAC;AAkBzC;;0FAE0F;AAC1F,SAAS,YAAY,CAAC,KAAa;IACjC,MAAM,CAAC,GAAG,8CAA8C,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxF,MAAM,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpB,MAAM,GAAG,GAAG,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC;AAC9C,CAAC;AAED,SAAS,aAAa,CAAC,CAA2B,EAAE,CAA2B;IAC7E,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,CAAC;AACX,CAAC;AAED;4FAC4F;AAC5F,SAAS,YAAY,CAAC,CAAS,EAAE,CAAS;IACxC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,IAAI,IAAI,IAAI,EAAE,CAAC;QACjB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;QACpB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,CAAC;IACD,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC,CAAC,CAAC,yBAAyB;IAC9C,IAAI,IAAI;QAAE,OAAO,CAAC,CAAC;IACnB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,CAAS,EAAE,CAAS;IAChD,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3B,MAAM,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,EAAE,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACnD,MAAM,IAAI,GAAG,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;IAC7C,IAAI,IAAI,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,qDAAqD;IACrD,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACzD,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAChC,MAAM,GAAG,GAAG,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QAC3D,IAAI,GAAG,KAAK,CAAC;YAAE,OAAO,GAAG,CAAC;IAC5B,CAAC;IACD,kFAAkF;IAClF,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,EAAE,CAAC,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM;QAAE,OAAO,CAAC,CAAC,CAAC;IAC7C,OAAO,CAAC,CAAC;AACX,CAAC;AAED;qEACqE;AACrE,SAAS,QAAQ,CAAC,IAAY;IAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC;AACzC,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,iBAAiB,CAAC,UAAkB;IAC3C,IAAI,oBAAoB,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IACxD,IAAI,iCAAiC,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACpE,OAAO,wBAAwB,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AACnD,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,KAAK,CAAC;IACvC,IAAI,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,KAAK,CAAC;IACjD,yFAAyF;IACzF,8FAA8F;IAC9F,IAAI,wBAAwB,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9C,OAAO,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,CAAC;IACD,iGAAiG;IACjG,gGAAgG;IAChG,oFAAoF;IACpF,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,MAAM,iBAAiB,GAAG,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5D,IAAI,CAAC,iBAAiB;QAAE,OAAO,QAAQ,CAAC;IACxC,IAAI,UAAU,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAChE,CAAC;AAED,SAAS,aAAa,CAAC,IAAa;IAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAChE,MAAM,QAAQ,GAAI,IAAgC,CAAC,WAAW,CAAC,CAAC;IAChE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACxE,MAAM,MAAM,GAAI,QAAoC,CAAC,QAAQ,CAAC,CAAC;IAC/D,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,SAAoB,EACpB,SAAkB;IAElB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CACpB,SAAS,KAAK,SAAS,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,yBAAyB,EAChF,YAAY,CACb,CAAC;IACF,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,SAAS,CAAC,sBAAsB,EAAE;YACjD,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,MAAM,EAAE,4BAA4B,EAAE;YACjD,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,KAAK,CAAC;SACnC,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,EAAE,0BAA0B,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IACrG,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;QAC5B,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,EAAE,0BAA0B,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;IACjG,CAAC;IACD,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACzE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,EAAE,uCAAuC,YAAY,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IAClH,CAAC;IACD,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,EAAE,2CAA2C,EAAE,CAAC;IACjG,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;AAClF,CAAC"}

package/dist/commands/upgrade.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./context.js";
+export declare function upgradeCommand(ctx: CommandContext): Promise<void | number>;

package/dist/commands/upgrade.js

@@ -0,0 +1,178 @@
+// `oh-hai upgrade` (docs/specs/cli.md §4 — self-update, #343, the "replaces brew upgrade" piece
+// of #277). Checks the npm registry for a newer `@oh-hai/cli`, then acts by install method:
+//   • npm-global  → run `npm i -g @oh-hai/cli@latest` (interactive human only; otherwise print it)
+//   • binary      → guidance to re-run the installer (in-place binary re-pull lands with #344/#345)
+//   • dev/unknown → honest guidance (pull+rebuild, or a generic update hint)
+// No fabricated success: a method that can't self-update yet PRINTS what to do, it never claims to
+// have upgraded. `--check` reports availability without acting. `--json` emits the uniform envelope
+// and never spawns a subprocess (machine mode must not mutate a global install).
+import { CliError, buildOk, serializeEnvelope } from "../envelope.js";
+import { sanitizeForTerminal } from "../terminal.js";
+import { cliVersion } from "../version.js";
+import { performBinaryUpdate } from "./binary-update.js";
+import { flagOnStrict, parseCommandArgs } from "./flags.js";
+import { PACKAGE_NAME, checkForUpdate, classifyInstall } from "./update-check.js";
+/** The headline installer (the binary `curl | sh` path, #345). */
+const INSTALL_SCRIPT = "curl -fsSL https://ohhai.app/install | sh";
+/** The npm self-upgrade command (the live secondary channel for node users, #270). */
+const NPM_UPGRADE_CMD = `npm i -g ${PACKAGE_NAME}@latest`;
+/** Emit a success outcome: the uniform --json envelope, else the human line. Registry-supplied
+ *  strings (`latest`, and any value woven into `line`) are terminal-sanitized on BOTH paths —
+ *  JSON.stringify does not escape C1/DEL (see doctor.ts), so --json is sanitized too (§5.4). */
+function emit(ctx, outcome) {
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("upgrade", {
+            current: sanitizeForTerminal(outcome.current),
+            latest: sanitizeForTerminal(outcome.latest),
+            update_available: outcome.updateAvailable,
+            method: outcome.method,
+            action: outcome.action,
+        })));
+        return;
+    }
+    ctx.io.log(sanitizeForTerminal(outcome.line));
+}
+/** The `binary` case of `upgrade` (#358): a `bun --compile` standalone can't `npm i -g` itself, so it
+ *  downloads the matching release asset, verifies its SHA-256 against the release `SHA256SUMS`, and
+ *  atomically swaps itself in place (mirroring packaging/install.sh). It self-updates ONLY when the
+ *  download/swap seam is wired AND it's a real interactive terminal (TTY stdin + TTY stdout) — the
+ *  SAME gate the npm-global branch uses: silently replacing the running binary under `--json`, a pipe
+ *  (`oh-hai upgrade | tee log`), or CI is as unsafe as a silent global npm mutation (#349's
+ *  principle). Anything else prints installer guidance without touching disk. Every
+ *  download/checksum/execute/install failure surfaces a clear CliError — never a fabricated success,
+ *  never an unverified binary written to disk. */
+async function binaryUpgrade(ctx, base, current, latest) {
+    // A real terminal session: a human at the TTY (stdin) AND a TTY stdout (not `| tee log`). Absent
+    // isStdoutTty (hermetic callers) is treated as a TTY; production wires process.stdout.isTTY.
+    const interactive = (ctx.runtime.isInteractive?.() ?? false) && (ctx.runtime.isStdoutTty?.() ?? true);
+    // Machine mode (--json), an unwired caller, or a non-interactive/piped session → guidance, no swap.
+    if (ctx.json || ctx.runtime.binaryUpdateIo === undefined || !interactive) {
+        emit(ctx, {
+            ...base,
+            updateAvailable: true,
+            action: "binary-guidance",
+            line: `update available: v${current} → v${latest}. Re-run the installer: ${INSTALL_SCRIPT}`,
+        });
+        return;
+    }
+    ctx.io.log(sanitizeForTerminal(`Downloading ${PACKAGE_NAME} v${latest} …`));
+    const result = await performBinaryUpdate(ctx.runtime.binaryUpdateIo, ctx.runtime.fetchImpl, latest, ctx.config.timeoutMs);
+    switch (result.status) {
+        case "updated":
+            emit(ctx, { ...base, updateAvailable: true, action: "binary-updated", line: `upgraded to v${latest}. Restart oh-hai to use the new version.` });
+            return;
+        case "unsupported":
+            // No prebuilt binary for this host (e.g. windows-arm64) — honest guidance, not a 404 crash.
+            emit(ctx, {
+                ...base,
+                updateAvailable: true,
+                action: "binary-guidance",
+                line: `update available: v${current} → v${latest}. No prebuilt binary for ${result.platform}-${result.arch}; install via \`${NPM_UPGRADE_CMD}\`.`,
+            });
+            return;
+        case "release-pending":
+            // npm has v${latest} but its binary release is still building (the npm publish and the binary
+            // matrix fire on the same tag; the matrix is slower). Not an error in the code — just early.
+            throw new CliError("error", sanitizeForTerminal(`the v${latest} binary release is still publishing — try again in a few minutes, or re-run the installer: ${INSTALL_SCRIPT}`));
+        case "checksum-mismatch":
+            // A tamper/corruption signal — hard-stop loudly rather than installing unverified bytes.
+            throw new CliError("error", sanitizeForTerminal(`checksum verification FAILED for the v${latest} binary — refusing to install (corrupted download or tampering). Re-run to retry.`));
+        case "unverified-binary":
+            throw new CliError("error", sanitizeForTerminal(`the downloaded v${latest} binary did not run on this host — keeping the current install. Re-run the installer: ${INSTALL_SCRIPT}`));
+        case "download-failed":
+            throw new CliError(result.network ? "network" : "error", sanitizeForTerminal(`could not download the v${latest} binary — ${result.detail}. Re-run the installer: ${INSTALL_SCRIPT}`));
+        case "install-failed":
+            throw new CliError("error", sanitizeForTerminal(`could not install the v${latest} binary — ${result.detail}.`));
+        default: {
+            // Exhaustive: BinaryUpdateResult is a closed union — a new status must add a case above.
+            const unreachable = result;
+            throw new CliError("error", `unhandled binary-update result: ${String(unreachable)}`);
+        }
+    }
+}
+export async function upgradeCommand(ctx) {
+    const { values } = parseCommandArgs(ctx.argv, { check: { type: "boolean" } });
+    // Strict parse: `--check` is the no-mutation safety mode, so a typo'd value (`--check=treu`) must
+    // fail loudly rather than silently fall through to the live `npm i -g` (#349 review).
+    const checkOnly = flagOnStrict(values.check, "check");
+    const current = cliVersion();
+    const method = ctx.runtime.installFacts !== undefined ? classifyInstall(ctx.runtime.installFacts) : "unknown";
+    const result = await checkForUpdate(current, ctx.runtime.fetchImpl, ctx.config.timeoutMs);
+    // Registry unreachable / unparseable → a clear NETWORK exit (the user asked explicitly, so a
+    // failed check is an error here, unlike doctor's advisory check which just omits the line). Throw
+    // a CliError like every other command; cli.ts translates it once into the exit code + --json
+    // envelope. The message is sanitized here (cli.ts renders CliError messages raw).
+    if (result.error !== undefined) {
+        throw new CliError("network", sanitizeForTerminal(`could not check for updates — ${result.error}`));
+    }
+    const latest = result.latest ?? current;
+    const base = { current, latest, method };
+    if (!result.updateAvailable) {
+        emit(ctx, { ...base, updateAvailable: false, action: "up-to-date", line: `already on the latest version (v${current}).` });
+        return;
+    }
+    // An update exists. `--check` only reports it.
+    if (checkOnly) {
+        emit(ctx, {
+            ...base,
+            updateAvailable: true,
+            action: "check",
+            line: `update available: v${current} → v${latest} — run \`oh-hai upgrade\`.`,
+        });
+        return;
+    }
+    switch (method) {
+        case "npm-global": {
+            // A real terminal session needs BOTH a TTY stdin (a human to react) AND a TTY stdout — a piped
+            // stdout (`oh-hai upgrade | tee log`) has a TTY stdin but must still PRINT the command, per the
+            // documented pipe/machine-safety behavior (#349 review). Absent isStdoutTty (hermetic callers)
+            // is treated as a TTY; production wires process.stdout.isTTY.
+            const interactive = (ctx.runtime.isInteractive?.() ?? false) && (ctx.runtime.isStdoutTty?.() ?? true);
+            // Machine mode / non-interactive / piped / no runner → PRINT the command; never silently mutate
+            // a global install in a pipe, in CI, or under --json.
+            if (ctx.json || !interactive || ctx.runtime.runCommand === undefined) {
+                emit(ctx, {
+                    ...base,
+                    updateAvailable: true,
+                    action: "print-command",
+                    line: `update available: v${current} → v${latest}. Run: ${NPM_UPGRADE_CMD}`,
+                });
+                return;
+            }
+            ctx.io.log(sanitizeForTerminal(`Upgrading ${PACKAGE_NAME}: v${current} → v${latest} …`));
+            const proc = await ctx.runtime.runCommand("npm", ["i", "-g", `${PACKAGE_NAME}@latest`]);
+            if (proc.spawnError !== undefined || (proc.code ?? 1) !== 0) {
+                const detail = proc.spawnError ?? (proc.stderr.trim() !== "" ? proc.stderr.trim() : `npm exited ${proc.code}`);
+                throw new CliError("error", sanitizeForTerminal(`npm upgrade failed — ${detail}`));
+            }
+            emit(ctx, { ...base, updateAvailable: true, action: "npm-upgrade", line: `upgraded to v${latest}.` });
+            return;
+        }
+        case "binary":
+            await binaryUpgrade(ctx, base, current, latest);
+            return;
+        case "dev":
+            emit(ctx, {
+                ...base,
+                updateAvailable: true,
+                action: "dev-guidance",
+                line: `update available: v${current} → v${latest}. You're on a source checkout — pull latest and rebuild.`,
+            });
+            return;
+        case "unknown":
+            emit(ctx, {
+                ...base,
+                updateAvailable: true,
+                action: "unknown-guidance",
+                line: `update available: v${current} → v${latest}. Update via \`${NPM_UPGRADE_CMD}\`, or re-run the installer: ${INSTALL_SCRIPT}`,
+            });
+            return;
+        default: {
+            // Exhaustive: InstallMethod is a closed union — a new value must add a case above rather than
+            // silently fall into generic guidance.
+            const unreachable = method;
+            throw new CliError("error", `unhandled install method: ${String(unreachable)}`);
+        }
+    }
+}
+//# sourceMappingURL=upgrade.js.map

package/dist/commands/upgrade.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.js","sourceRoot":"","sources":["../../src/commands/upgrade.ts"],"names":[],"mappings":"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"}

package/dist/commands/use.d.ts

@@ -0,0 +1,2 @@
+import type { CommandContext } from "./context.js";
+export declare function useCommand(ctx: CommandContext): Promise<void>;

package/dist/commands/use.js

@@ -0,0 +1,99 @@
+// `oh-hai use` (docs/specs/cli.md §4, #321 — part of #307). Bind the current directory to an agent so
+// sessions in that tree act as it with no `--account` juggling. Fully offline and side-effect-local:
+// it only reads/writes the USER-side bindings store (`~/.config/oh-hai/bindings.json`), never a repo
+// and never the network — so a binding can't be planted by a hostile checkout (credential-safety §6).
+//
+//   oh-hai use <agent>   bind cwd → <agent> for the resolved Hub origin
+//   oh-hai use --list     list all bindings
+//   oh-hai use --unset    remove cwd's binding for the resolved Hub origin
+//
+// Binding is offline and does NOT require the agent to have a stored token yet — you may `use` an
+// agent then `login` as it (like `logout`, no Hub call). Resolution + the normal token lookup handle
+// a not-yet-authenticated agent downstream (`whoami` then shows `token: absent`).
+import { isAbsolute } from "node:path";
+import { CliError, buildOk, serializeEnvelope } from "../envelope.js";
+import { originOf } from "../auth/resolve-token.js";
+import { bindingStoreStatus, loadBindings, setBinding, unsetBinding } from "../bindings.js";
+import { sanitizeForTerminal } from "../terminal.js";
+import { flagOn, parseCommandArgs } from "./flags.js";
+export async function useCommand(ctx) {
+    // `use` takes one optional operand (the agent id) plus --list / --unset booleans.
+    const { values, positionals } = parseCommandArgs(ctx.argv, { list: { type: "boolean" }, unset: { type: "boolean" } }, { maxOperands: 1 });
+    // A blank / whitespace-only operand (`use ""`, `use "  "`) is treated as ABSENT — otherwise it would
+    // report a successful bind while writing a dead record `asBinding` drops on read. Trim so a stray-space
+    // agent id is stored clean, matching the account-resolution presence semantics (config.ts).
+    const rawAgent = positionals[1];
+    const agent = rawAgent !== undefined && rawAgent.trim() !== "" ? rawAgent.trim() : undefined;
+    const list = flagOn(values.list);
+    const unset = flagOn(values.unset);
+    // Exactly one mode: bind (an agent operand), --list, or --unset.
+    const modes = (agent !== undefined ? 1 : 0) + (list ? 1 : 0) + (unset ? 1 : 0);
+    if (modes > 1) {
+        throw new CliError("usage", "choose one: `use <agent>`, `use --list`, or `use --unset`.");
+    }
+    if (modes === 0) {
+        throw new CliError("usage", "expected an <agent> id, or --list / --unset. Run 'oh-hai use --help'.");
+    }
+    const io = ctx.runtime.bindingsIo;
+    if (io === undefined) {
+        // Defensive: production always wires nodeBindingsIo(); this only fires if a caller omits it.
+        throw new CliError("error", "internal: the bindings store is unavailable.");
+    }
+    const origin = originOf(ctx.config.baseUrl);
+    const cwd = io.cwd;
+    if (list) {
+        const bindings = loadBindings(io);
+        if (ctx.json) {
+            ctx.io.log(serializeEnvelope(buildOk("use", { bindings })));
+        }
+        else if (bindings.length === 0) {
+            ctx.io.log("No directory bindings.");
+        }
+        else {
+            for (const b of bindings) {
+                // Every field here comes from the bindings FILE, so sanitize each before echoing — a hand-edited
+                // record could carry control chars in origin just as in path/account.
+                ctx.io.log(`${sanitizeForTerminal(b.path)} → ${sanitizeForTerminal(b.account)} (${sanitizeForTerminal(b.origin)})`);
+            }
+        }
+        return;
+    }
+    // Write-path preflight (bind + unset): fail LOUDLY rather than report a success that didn't persist.
+    //  - a non-absolute cwd (production records "" when `process.cwd()` failed; a relative cwd would write
+    //    a binding `resolveBinding` then ignores) has nothing meaningful to bind;
+    //  - an "unavailable" store (no trusted config dir) would silently no-op the write;
+    //  - an "unsupported-version" file was written by a newer CLI — overwriting it would erase its bindings.
+    if (!isAbsolute(cwd)) {
+        throw new CliError("error", "cannot bind: no absolute working directory (is the current directory gone?).");
+    }
+    const status = bindingStoreStatus(io);
+    if (status === "unavailable") {
+        throw new CliError("error", "cannot persist a binding: no writable user config directory (set $HOME or $XDG_CONFIG_HOME).");
+    }
+    if (status === "unsupported-version") {
+        throw new CliError("error", "refusing to modify a bindings.json written by a newer oh-hai — upgrade the CLI to change bindings.");
+    }
+    if (unset) {
+        const removed = unsetBinding(io, cwd, origin);
+        if (ctx.json) {
+            ctx.io.log(serializeEnvelope(buildOk("use", { path: cwd, origin, removed })));
+        }
+        else {
+            ctx.io.log(removed
+                ? `Unbound ${sanitizeForTerminal(cwd)} (${sanitizeForTerminal(origin)}).`
+                : `No binding for ${sanitizeForTerminal(cwd)} (${sanitizeForTerminal(origin)}).`);
+        }
+        return;
+    }
+    // Bind mode: reaching here, `agent` is defined (modes === 1 with --list/--unset both false), but the
+    // mode-count arithmetic doesn't narrow it for the type checker — assert the definedness we proved.
+    const agentId = agent;
+    const path = setBinding(io, cwd, origin, agentId);
+    if (ctx.json) {
+        ctx.io.log(serializeEnvelope(buildOk("use", { path, account: agentId, origin })));
+    }
+    else {
+        ctx.io.log(`Bound ${sanitizeForTerminal(path)} → ${sanitizeForTerminal(agentId)} (${sanitizeForTerminal(origin)}).`);
+    }
+}
+//# sourceMappingURL=use.js.map

package/dist/commands/use.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use.js","sourceRoot":"","sources":["../../src/commands/use.ts"],"names":[],"mappings":"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"}