@zocomputer/cli 0.3.0 → 0.4.1

package/dist/suggest.js

@@ -0,0 +1,42 @@
+/** Edits that turn one word into another: insert, delete, replace, or swap two neighbors. */
+function editDistance(left, right) {
+    let previous = [];
+    let current = Array.from({ length: right.length + 1 }, (_, index) => index);
+    for (let row = 1; row <= left.length; row++) {
+        const next = [row];
+        for (let column = 1; column <= right.length; column++) {
+            const same = left[row - 1] === right[column - 1];
+            let cost = Math.min((current[column] ?? 0) + 1, (next[column - 1] ?? 0) + 1, (current[column - 1] ?? 0) + (same ? 0 : 1));
+            if (row > 1 &&
+                column > 1 &&
+                left[row - 1] === right[column - 2] &&
+                left[row - 2] === right[column - 1])
+                cost = Math.min(cost, (previous[column - 2] ?? 0) + 1);
+            next.push(cost);
+        }
+        previous = current;
+        current = next;
+    }
+    return current[right.length] ?? 0;
+}
+/**
+ * The candidate a mistyped word most likely meant: the nearest within one
+ * edit per three letters, else the shortest one the word begins.
+ */
+export function closest(word, candidates) {
+    const typed = word.toLowerCase();
+    let best;
+    let bestDistance = Math.max(1, Math.floor(typed.length / 3)) + 1;
+    for (const candidate of candidates) {
+        const distance = editDistance(typed, candidate);
+        if (distance < bestDistance) {
+            best = candidate;
+            bestDistance = distance;
+        }
+    }
+    if (best !== undefined || typed.length < 3)
+        return best;
+    return candidates
+        .filter((candidate) => candidate.startsWith(typed))
+        .sort((left, right) => left.length - right.length)[0];
+}

package/dist/update.d.ts

@@ -0,0 +1,21 @@
+import type { FetchLike } from "@zocomputer/system-api";
+export interface UpdateOptions {
+    /** The standalone executable's version. npm installations have none. */
+    version?: string;
+    execPath?: string;
+    env?: NodeJS.ProcessEnv;
+    fetch?: FetchLike;
+    signal?: AbortSignal;
+    stderr?: {
+        write(text: string): unknown;
+    };
+    /** Runs the release installer and resolves with its exit status. */
+    runInstaller?: (script: Buffer, args: string[]) => Promise<number>;
+}
+export interface UpdateResult {
+    /** The version the zo command runs after this update. */
+    version: string;
+    latest_version: string;
+    updated: boolean;
+}
+export declare function update(options?: UpdateOptions): Promise<UpdateResult>;

package/dist/update.js

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { readFile, readlink, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { delimiter, dirname, isAbsolute, join } from "node:path";
+import { CliError, record, safeText, throwIfInterrupted } from "./errors.js";
+const releases = "https://github.com/zocomputer/zo-cli/releases";
+const installCommand = "curl -fsSL https://zo.computer/install.sh | sh";
+const versionPattern = /^(\d+)\.(\d+)\.(\d+)(-[A-Za-z0-9][A-Za-z0-9.-]*)?$/;
+// The installer links <data home>/zo/cli/releases/<version>/<target>/zo.
+const managedPath = /^(\/.*\/zo\/cli)\/releases\/[^/]+\/[^/]+\/zo$/;
+function unreachable() {
+    return new CliError("Could not download the latest Zo CLI release. Check your connection and try again.", 5, "transport_error");
+}
+/** Follows redirects by hand so a release can never be fetched over plain HTTP. */
+async function download(url, fetcher, signal) {
+    const timeout = AbortSignal.timeout(60_000);
+    const combined = signal ? AbortSignal.any([signal, timeout]) : timeout;
+    try {
+        let target = url;
+        for (let hop = 0; hop < 5; hop++) {
+            const response = await fetcher(target, {
+                redirect: "manual",
+                signal: combined,
+            });
+            const location = response.headers.get("location");
+            if (response.status >= 300 && response.status < 400 && location) {
+                await response.body?.cancel();
+                target = new URL(location, target).href;
+                if (!target.startsWith("https://"))
+                    break;
+                continue;
+            }
+            if (!response.ok || !response.body)
+                break;
+            // The manifest and installer are a few kilobytes; refuse anything else.
+            const reader = response.body.getReader();
+            const chunks = [];
+            for (let size = 0;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    return Buffer.concat(chunks);
+                size += value.length;
+                if (size > 1_048_576) {
+                    await reader.cancel().catch(() => { });
+                    break;
+                }
+                chunks.push(value);
+            }
+            break;
+        }
+    }
+    catch {
+        throwIfInterrupted(signal);
+    }
+    throw unreachable();
+}
+function isNewer(candidate, current) {
+    const next = versionPattern.exec(candidate);
+    const now = versionPattern.exec(current);
+    if (!next || !now)
+        return false;
+    for (const index of [1, 2, 3]) {
+        const difference = Number(next[index]) - Number(now[index]);
+        if (difference !== 0)
+            return difference > 0;
+    }
+    // 0.4.0 follows 0.4.0-rc.1; the latest release is never a prerelease.
+    return now[4] !== undefined && next[4] === undefined;
+}
+/** Finds the installer's link on PATH, else in the installer's default directory. */
+async function managedCommand(executable, env) {
+    const directories = (env.PATH ?? "").split(delimiter);
+    directories.push(join(env.HOME ?? homedir(), ".local/bin"));
+    let shadowedBy;
+    for (const directory of directories) {
+        if (!isAbsolute(directory))
+            continue;
+        const command = join(directory, "zo");
+        const resolved = await realpath(command).catch(() => undefined);
+        if (resolved === undefined)
+            continue;
+        if (resolved !== executable) {
+            shadowedBy ??= command;
+            continue;
+        }
+        // The installer replaces only a link it wrote, so an alias that points at
+        // that link is passed over for the link itself.
+        const root = managedPath.exec(await readlink(command).catch(() => ""))?.[1];
+        if (root)
+            return { directory, root, shadowedBy };
+    }
+    return undefined;
+}
+function shell(env, signal, stderr) {
+    return (script, args) => new Promise((resolve, reject) => {
+        // The installer reads itself from stdin, as it does under `curl | sh`.
+        // It gets its own process group so an interrupt also stops its download;
+        // a shell alone would wait for curl before running its trap.
+        const child = spawn("/bin/sh", ["-s", "--", ...args], {
+            env,
+            detached: true,
+            stdio: ["pipe", "ignore", "pipe"],
+        });
+        const stop = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGTERM");
+            }
+            catch {
+                /* The installer already exited. */
+            }
+        };
+        signal?.addEventListener("abort", stop, { once: true });
+        if (signal?.aborted)
+            stop();
+        child.on("error", reject);
+        child.on("close", (code) => {
+            signal?.removeEventListener("abort", stop);
+            resolve(code ?? 1);
+        });
+        child.stderr.on("data", (chunk) => stderr.write(String(chunk)));
+        // A shell that exits early closes the pipe; its status reports why.
+        child.stdin.on("error", () => { });
+        child.stdin.end(script);
+    });
+}
+export async function update(options = {}) {
+    const env = options.env ?? process.env;
+    const stderr = options.stderr ?? process.stderr;
+    const current = options.version;
+    if (current === undefined)
+        throw new CliError("zo update replaces the standalone executable. This zo was installed with npm; run npm install --global @zocomputer/cli@latest instead.", 2, "unsupported_installation");
+    const unmanaged = (reason) => new CliError(`${reason} Install the latest release with: ${installCommand}`, 2, "unsupported_installation");
+    const executable = await realpath(options.execPath ?? process.execPath);
+    const command = await managedCommand(executable, env);
+    if (managedPath.test(executable) && !command)
+        throw unmanaged("No zo command on your PATH links to this executable.");
+    const marker = command
+        ? await readFile(join(command.root, ".installer-v1"), "utf8").catch(() => "")
+        : "";
+    if (!command || marker.trim() !== "zo-cli-installer-v1")
+        throw unmanaged("This zo was not installed by the standalone installer, so it cannot update itself.");
+    const fetcher = options.fetch ?? fetch;
+    let manifest;
+    try {
+        manifest = JSON.parse((await download(`${releases}/latest/download/release.json`, fetcher, options.signal)).toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+    }
+    const invalid = new CliError("The latest Zo CLI release could not be verified. Nothing was changed.", 5, "invalid_response");
+    if (!record(manifest) ||
+        manifest.schema_version !== 1 ||
+        typeof manifest.cli_version !== "string" ||
+        !versionPattern.test(manifest.cli_version) ||
+        typeof manifest.installer_sha256 !== "string")
+        throw invalid;
+    const latest = manifest.cli_version;
+    if (!isNewer(latest, current)) {
+        stderr.write(latest === current
+            ? `zo ${current} is the latest version.\n`
+            : `zo ${current} is newer than the latest release, ${latest}. Nothing to update; to install ${latest}, run: ${installCommand}\n`);
+        return { version: current, latest_version: latest, updated: false };
+    }
+    // Each release publishes the installer pinned to its own version.
+    const installer = await download(`${releases}/download/v${latest}/install.sh`, fetcher, options.signal);
+    if (createHash("sha256").update(installer).digest("hex") !==
+        manifest.installer_sha256)
+        throw invalid;
+    stderr.write(`Updating zo ${current} to ${latest}…\n`);
+    // The installer derives its root from XDG_DATA_HOME, which may have changed
+    // since installation; the link records the root it must keep using.
+    const run = options.runInstaller ??
+        shell({ ...env, XDG_DATA_HOME: dirname(dirname(command.root)) }, options.signal, stderr);
+    let status;
+    try {
+        status = await run(installer, [
+            "--bin-dir",
+            command.directory,
+            "--no-modify-path",
+        ]);
+    }
+    catch {
+        status = 1;
+    }
+    throwIfInterrupted(options.signal);
+    if (status !== 0)
+        throw new CliError(`The update did not finish. zo ${current} is still installed.`, 5, "update_failed");
+    stderr.write(`Updated zo to ${latest}. Sign-ins are unchanged.\n`);
+    if (command.shadowedBy)
+        stderr.write(`Another zo at ${safeText(command.shadowedBy)} comes first on your PATH and was not updated.\n`);
+    return { version: latest, latest_version: latest, updated: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zocomputer/cli",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Public Zo command line client",
   "bin": {
@@ -14,7 +14,7 @@
     "node": "^22.23.4 || ^24.22.1 || ^26.13.0"
   },
   "dependencies": {
-    "@zocomputer/system-api": "0.2.0"
+    "@zocomputer/system-api": "0.3.1"
   },
   "publishConfig": {
     "access": "public",