@symbols-cli/cli 0.0.1

package/dist/commands/update.js

@@ -0,0 +1,120 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols update` — refresh the skills bundle, and say whether the CLI itself
+// is behind.
+//
+// # This command does NOT update the CLI binary
+//
+// It would be one `npm i -g` away, and that is exactly why it is not here. The
+// agent runs as the same uid as this process: a self-update path is a
+// `spawn(npm, ["i", "-g", …])` that an injected instruction can aim at any
+// package name it likes, and the CLI is the thing holding the device
+// credential. So the version is REPORTED and the user runs one line.
+//
+// The skills bundle is different, and the difference is the signature. Bundle
+// content is verified against `PINNED_KEYS` compiled into this binary, with a
+// monotonic sequence floor stored outside the agent's reach — so a compromised
+// server cannot push instructions to it, and cannot roll it back to a version
+// whose defects were fixed. That is what makes automatic refresh acceptable
+// here and not for the binary.
+//
+// ⚠ THE FAILURE THIS EXISTS FOR: the repo shipped odin 0.7.7 while laptops ran
+// 0.7.4, because `plugin install` on an already-installed plugin exits 0
+// WITHOUT upgrading. A stale skill is not a cosmetic problem — it teaches the
+// agent a workflow that no longer exists.
+import { installBundle, readInstalledManifest, BundleVerificationError } from "../skills/bundle.js";
+import { installPlugins, ClaudeCliMissingError } from "../skills/install.js";
+import { workspaceRoot } from "../util/platform.js";
+import { load } from "../auth/credentials.js";
+import { print, eprint } from "../util/log.js";
+function usage() {
+    eprint(`usage: symbols update [--check]\n\n` +
+        `Refreshes the Symbols skills bundle and reports whether the CLI is behind.\n\n` +
+        `  --check   report only; write nothing\n\n` +
+        `The CLI binary is NOT self-updating: run \`npm i -g @symbols-cli/cli\`.\n`);
+    return 2;
+}
+/** `1.2.10` > `1.2.9`. Compares numerically, segment by segment. */
+export function isOlder(a, b) {
+    const pa = a.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    const pb = b.split(".").map((n) => Number.parseInt(n, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y)
+            return x < y;
+    }
+    return false;
+}
+export async function run(argv) {
+    if (argv.includes("-h") || argv.includes("--help"))
+        return usage();
+    const checkOnly = argv.includes("--check");
+    const cred = await load();
+    if (!cred) {
+        eprint("Not signed in. Run `symbols login` first.\n");
+        return 1;
+    }
+    // ⚠ THE VERSION CHECK IS GONE, NOT DISABLED. It called `/api/cli/version`,
+    // which is **not registered on the server** — grep `apps/server/routes` for
+    // `cli/version` and you get nothing. So it 404'd on every run, was swallowed
+    // by a bare `catch`, and reported nothing while looking like a feature.
+    //
+    // A check that cannot succeed is worse than no check: it makes the next
+    // reader believe staleness is being detected. `isOlder` is kept and tested —
+    // it is correct, and it is what this needs the day the route exists.
+    // ── the skills bundle ──────────────────────────────────────────────────────
+    const before = await readInstalledManifest();
+    if (checkOnly) {
+        print(before
+            ? `Skills bundle: sequence ${before.sequence}, stamp ${before.stamp.slice(0, 12)}\n` +
+                `Run \`symbols update\` to fetch the current one.\n`
+            : "No skills bundle is installed yet. Run `symbols update`.\n");
+        return 0;
+    }
+    let installed;
+    try {
+        installed = await installBundle();
+    }
+    catch (err) {
+        if (err instanceof BundleVerificationError) {
+            // ⚠ A verification failure is NOT a transient error and must never be
+            // retried into submission. Refusing leaves the previous, verified bundle
+            // in place, which is the safe state.
+            eprint(`Refused the skills bundle: ${err.message}\n\n` +
+                `The bundle already on this machine is unchanged and still in use.\n`);
+            return 1;
+        }
+        eprint(`Could not update the skills bundle: ${err.message}\n`);
+        return 1;
+    }
+    if (!installed.changed && before) {
+        print(`Skills already current (sequence ${installed.manifest.sequence}).\n`);
+        return 0;
+    }
+    print(`Skills updated to sequence ${installed.manifest.sequence} ` +
+        `(${installed.manifest.plugins.length} plugin(s)).\n`);
+    // Re-point Claude Code at the refreshed cache. `plugin install` alone is the
+    // no-op that caused the 0.7.4/0.7.7 split; `installPlugins` runs the update
+    // path, which is why this is not simply "unpack and stop".
+    try {
+        const results = await installPlugins(workspaceRoot(), installed.manifest);
+        for (const r of results) {
+            const what = r.updated ? "updated" : r.installed ? "installed" : "unchanged";
+            print(`  ${r.plugin} ${what} — ${r.detail}\n`);
+        }
+    }
+    catch (err) {
+        if (err instanceof ClaudeCliMissingError) {
+            eprint(`\nThe bundle is installed, but the \`claude\` CLI was not found, so the\n` +
+                `plugins were not registered. Install Claude Code, then run\n` +
+                `\`symbols update\` again.\n`);
+            return 1;
+        }
+        throw err;
+    }
+    print(`\nRun \`symbols doctor\` to confirm.\n`);
+    return 0;
+}

package/dist/commands/watch.js

@@ -0,0 +1,155 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols watch` — the long-running sync.
+//
+// ## The ordering this file exists to get right
+//
+//   1. bind the projects (directories, `project.json`, the inode binding)
+//   2. **start the watchers**
+//   3. run the first full sweep
+//   4. sweep again every 60s, and on every watcher batch
+//
+// Steps 2 and 3 are in that order, ported from `start()`
+// (`odin_notebook_writeback.rs:1746-1780`). On the server, spawning the watcher
+// after the materialize left a ~90s window in which a write produced no event
+// and nothing replayed the gap — there is no startup dirwalk to recover it.
+// Locally the first sweep is faster but the window is the same shape, and a file
+// the user saves during it would wait a full 60s for the timer.
+//
+// It is SAFE in that order for exactly the reason the Rust comment gives: our own
+// writes come back as events, hash-equal, and stop at the loop breaker. The cost
+// is that each pulled file pays one extra stat before short-circuiting.
+//
+// ## Why the 60s sweep is not optional
+//
+// Reconcile is the guarantee. The watcher misses things by construction — the
+// server side has no event stream to us at all (REST `create/update/delete_file`
+// emit no `fs_event`; the plan's "known gaps" table says so), so **a web tile
+// edit is invisible until the next sweep**. Anything the CLI learns about the
+// server, it learns by asking.
+import { Ledger } from "../sync/ledger.js";
+import { ensureProjects, syncProject } from "../sync/reconcile.js";
+import { listProjects, RateLimitedError } from "../sync/api.js";
+import { Watcher, expandDirty } from "../sync/watcher.js";
+import { workspaceRoot } from "../util/platform.js";
+import { renderResult } from "./sync.js";
+import { eprint, print } from "../util/log.js";
+const SWEEP_MS = 60_000;
+/** After a 429, wait this long before the next sweep. */
+const BACKOFF_MS = 60_000;
+export async function run(argv) {
+    const confirmDeletes = argv.includes("--confirm-deletes");
+    const once = argv.includes("--once");
+    const intervalArg = argv.find((a) => a.startsWith("--interval="));
+    const sweepMs = intervalArg ? Number(intervalArg.slice("--interval=".length)) * 1000 : SWEEP_MS;
+    const ledger = await Ledger.open();
+    const watchers = [];
+    let stopping = false;
+    const projects = await listProjects();
+    const ensured = await ensureProjects(ledger, projects, workspaceRoot());
+    const live = [];
+    for (const e of ensured) {
+        if (e.dirnameDrift)
+            eprint(`symbols: ${e.name}: ${e.dirnameDrift}\n`);
+        if (e.problem || !e.project) {
+            eprint(`symbols: ${e.name}: ${e.problem ?? "could not be bound"}\n`);
+            continue;
+        }
+        live.push(e.project);
+    }
+    // One in-flight sweep at a time, per project. Two concurrent sweeps of one
+    // project would each read a snapshot, then each act on it — the second acting
+    // on state the first has already changed. Serialising is not a performance
+    // choice; overlapping sweeps re-introduce exactly the mid-flight class
+    // `baseAfter` exists to catch, one level up.
+    const busy = new Set();
+    const pendingDirty = new Map();
+    const sweep = async (project, only) => {
+        if (stopping)
+            return;
+        if (busy.has(project.id)) {
+            // Remember the hint rather than dropping it — the running sweep may have
+            // already read the file it names.
+            const set = pendingDirty.get(project.id) ?? new Set();
+            for (const p of only ?? [])
+                set.add(p);
+            pendingDirty.set(project.id, set);
+            return;
+        }
+        busy.add(project.id);
+        try {
+            const fresh = ledger.project(project.notebookId) ?? project;
+            const res = await syncProject({
+                ledger,
+                project: fresh,
+                confirmDeletes,
+                ...(only ? { only } : {}),
+                log: (l) => print(`${l}\n`),
+            });
+            const moved = res.pulled + res.pushed + res.localDeletes + res.serverDeletes + res.conflicts;
+            if (moved > 0 || res.frozen.length > 0 || res.offline) {
+                print(`${renderResult(res)}\n`);
+            }
+        }
+        catch (err) {
+            if (err instanceof RateLimitedError) {
+                eprint(`symbols: ${err.message}; pausing ${BACKOFF_MS / 1000}s\n`);
+                await new Promise((r) => setTimeout(r, BACKOFF_MS));
+            }
+            else {
+                eprint(`symbols: sweep failed for ${project.name}: ${err.message}\n`);
+            }
+        }
+        finally {
+            busy.delete(project.id);
+            const queued = pendingDirty.get(project.id);
+            if (queued && queued.size > 0 && !stopping) {
+                pendingDirty.delete(project.id);
+                void sweep(project, [...queued]);
+            }
+        }
+    };
+    // ── 2. WATCHERS FIRST ──────────────────────────────────────────────────────
+    for (const project of live) {
+        const w = new Watcher({
+            root: project.root,
+            onDirty: (batch) => {
+                const tracked = ledger.files(project.id).map((f) => f.path);
+                void sweep(project, expandDirty(batch, tracked));
+            },
+        });
+        await w.start();
+        watchers.push(w);
+    }
+    print(`watching ${live.length} project(s) under ${workspaceRoot()}\n`);
+    // ── 3. …then the first full sweep ──────────────────────────────────────────
+    for (const project of live)
+        await sweep(project);
+    if (once) {
+        for (const w of watchers)
+            await w.stop();
+        ledger.close();
+        return 0;
+    }
+    // ── 4. the guarantee ───────────────────────────────────────────────────────
+    const timer = setInterval(() => {
+        for (const project of live)
+            void sweep(project);
+    }, sweepMs);
+    await new Promise((resolve) => {
+        const shutdown = () => {
+            stopping = true;
+            clearInterval(timer);
+            resolve();
+        };
+        process.on("SIGINT", shutdown);
+        process.on("SIGTERM", shutdown);
+    });
+    print("\nstopping…\n");
+    for (const w of watchers)
+        await w.stop();
+    ledger.close();
+    return 0;
+}

package/dist/commands/whoami.js

@@ -0,0 +1,103 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// `symbols whoami` — who this device is signed in as, and what it may do.
+//
+// Two properties this command must have:
+//
+//   * It REPORTS THE STORE, never assumes it. `credentials.ts` falls back from
+//     keychain to file when the keychain is locked or absent, and a user told
+//     "your token is in the keychain" when it is on disk has been misinformed
+//     about their own exposure.
+//   * It PRINTS SCOPES. The whole safety argument for putting a credential on a
+//     laptop is that it carries no money scope; that claim should be checkable by
+//     the person holding it, not just by a test in the server repo.
+//
+// It never prints the token, in any form — not truncated, not hashed. A
+// "harmless" prefix is exactly what ends up pasted into a bug report.
+import { load, storeKind, credentialsPath } from "../auth/credentials.js";
+import { request, NotLoggedInError } from "../auth/client.js";
+import { apiOrigin } from "../auth/hosts.js";
+import { CLI_VERSION } from "../util/version.js";
+import { eprint, print } from "../util/log.js";
+export async function run(argv) {
+    const asJson = argv.includes("--json");
+    const cred = await load();
+    if (!cred) {
+        if (asJson) {
+            print(`${JSON.stringify({ signed_in: false })}\n`);
+        }
+        else {
+            eprint("Not signed in. Run `symbols login`.\n");
+        }
+        return 1;
+    }
+    // Ask the server rather than trusting the local file: the device may have been
+    // revoked from another machine, and the local copy would not know.
+    let session = null;
+    let error = null;
+    try {
+        ({ body: session } = await request("/api/auth/cli/session"));
+    }
+    catch (err) {
+        if (err instanceof NotLoggedInError)
+            throw err;
+        error = err instanceof Error ? err.message : String(err);
+    }
+    const store = storeKind();
+    const storeDesc = store === "keychain" ? "macOS keychain" : `${credentialsPath()} (0600)`;
+    if (asJson) {
+        print(`${JSON.stringify({
+            signed_in: true,
+            user_id: session?.user_id ?? cred.userId,
+            email: session?.email ?? cred.email ?? null,
+            device_id: cred.deviceId,
+            origin: cred.origin,
+            credential_store: store,
+            cli_version: CLI_VERSION,
+            scopes: session?.scopes ?? null,
+            server_reachable: session !== null,
+            error,
+        }, null, 2)}\n`);
+        return session ? 0 : 1;
+    }
+    const lines = [
+        `Signed in as   ${session?.email ?? cred.email ?? cred.userId}`,
+        `User           ${session?.user_id ?? cred.userId}`,
+        `Device         ${session?.device_label ?? cred.deviceId}`,
+        `API            ${apiOrigin()}`,
+        `Credential     ${storeDesc}`,
+        `CLI            ${CLI_VERSION}`,
+    ];
+    if (session) {
+        lines.push(`Access expires in ${Math.round(session.expires_in / 60)} min`);
+        lines.push("");
+        // ⚠ "CANNOT place orders" is true and INCOMPLETE, which is the dangerous
+        // shape for a safety claim. This credential CAN permanently delete a
+        // notebook — `DELETE /api/notebooks/{id}` is in its scope list on purpose,
+        // because `symbols project rm` needs it. A P6 agent wrote "the device
+        // credential is read-only, so a DELETE is refused" into a skill, verified
+        // it, and found it false. Printing the destructive scopes separately means
+        // nobody has to take anyone's word for it.
+        const destructive = session.scopes.filter((s) => s.startsWith("DELETE "));
+        const rest = session.scopes.filter((s) => !s.startsWith("DELETE "));
+        lines.push(`Scopes (${session.scopes.length}) — this credential CANNOT place orders.`);
+        if (destructive.length > 0) {
+            lines.push("");
+            lines.push(`  ⚠ It CAN permanently delete (${destructive.length}):`);
+            for (const s of destructive)
+                lines.push(`      ${s}`);
+        }
+        lines.push("");
+        for (const s of rest)
+            lines.push(`  ${s}`);
+    }
+    else {
+        lines.push("");
+        lines.push(`⚠ Could not reach the server: ${error}`);
+        lines.push("  The details above are from the local credential and may be stale.");
+    }
+    print(`${lines.join("\n")}\n`);
+    return session ? 0 : 1;
+}

package/dist/index.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// Symbols CLI — entry point and the ONLY place commands are registered.
+//
+// ⚠ APPEND-ONLY REGISTRY. Four phases (P0/P2/P3/P4) add commands to this file in
+// parallel worktrees. Each command lives in its own `commands/<name>.ts`; this
+// file only maps a name to a lazy import. Keeping the bodies out means a merge
+// here is a one-line addition, not a conflict — which is what makes the parallel
+// phases actually parallel rather than nominally so.
+//
+// Add a row. Do not restructure.
+import { eprint, print } from "./util/log.js";
+import { CLI_VERSION } from "./util/version.js";
+const COMMANDS = {
+    // ── P0 ─────────────────────────────────────────────────────────────────────
+    login: {
+        summary: "Sign in via your browser and store a device credential",
+        phase: "P0",
+        load: () => import("./commands/login.js"),
+    },
+    logout: {
+        summary: "Revoke this device's credential",
+        phase: "P0",
+        load: () => import("./commands/logout.js"),
+    },
+    whoami: {
+        summary: "Show who this device is signed in as",
+        phase: "P0",
+        load: () => import("./commands/whoami.js"),
+    },
+    curl: {
+        summary: "Call the Symbols API by path (never a full URL)",
+        phase: "P0",
+        load: () => import("./commands/curl.js"),
+    },
+    // ── P2 ─────────────────────────────────────────────────────────────────────
+    doctor: {
+        summary: "Verify the Symbols skills install (machine-readable; non-zero on any problem)",
+        phase: "P2",
+        load: () => import("./commands/doctor.js"),
+    },
+    // ── P3 ─────────────────────────────────────────────────────────────────────
+    mcp: {
+        summary: "Run the Symbols MCP server on stdio (launched by Claude Code)",
+        phase: "P3",
+        load: () => import("./commands/mcp.js"),
+    },
+    // ── P5 ─────────────────────────────────────────────────────────────────────
+    arm: {
+        summary: "Open a bounded window in which the agent may spend money (browser consent)",
+        phase: "P5",
+        load: () => import("./commands/arm.js"),
+    },
+    // ── P4 appends below. One row each; bodies in commands/. ───────────────────
+    up: {
+        summary: "Materialise your notebooks as directories under ~/Symbols and sync them",
+        phase: "P4b",
+        load: () => import("./commands/up.js"),
+    },
+    sync: {
+        summary: "Reconcile every project once (--confirm-deletes, --dry-run, --project=NAME)",
+        phase: "P4b",
+        load: () => import("./commands/sync.js"),
+    },
+    watch: {
+        summary: "Keep projects in sync: filesystem events plus a 60s reconcile sweep",
+        phase: "P4b",
+        load: () => import("./commands/watch.js"),
+    },
+    status: {
+        summary: "Show what sync is holding and why (--json)",
+        phase: "P4b",
+        load: () => import("./commands/status.js"),
+    },
+    project: {
+        summary: "Manage projects: ls | new <name> | rm <name> | detach <name>",
+        phase: "P4b",
+        load: () => import("./commands/project.js"),
+    },
+    update: {
+        summary: "Refresh the skills bundle; report if the CLI is behind",
+        phase: "P2",
+        load: () => import("./commands/update.js"),
+    },
+    uninstall: {
+        summary: "Remove skills, ledger and credential (never your projects)",
+        phase: "P2",
+        load: () => import("./commands/uninstall.js"),
+    },
+};
+/**
+ * @param asked true when the user typed `--help`; false when we are correcting
+ *   a mistake (no command, unknown command).
+ *
+ * ⚠ THE EXIT CODE IS PART OF THE INTERFACE. Both cases used to return 2, so
+ * `symbols --help` — a request that SUCCEEDED — reported failure, which breaks
+ * `symbols --help && echo ok` and any CI step that checks the binary runs.
+ * Asked-for help goes to stdout and exits 0; a usage error stays on stderr at 2.
+ */
+function usage(asked = false) {
+    const width = Math.max(...Object.keys(COMMANDS).map((k) => k.length));
+    const lines = Object.entries(COMMANDS)
+        .map(([name, c]) => `  ${name.padEnd(width)}  ${c.summary}`)
+        .join("\n");
+    const text = `symbols — run the Symbols agent on your own machine\n\nusage: symbols <command> [args]\n\n${lines}\n`;
+    if (asked) {
+        print(text);
+        return 0;
+    }
+    eprint(text);
+    return 2;
+}
+async function main() {
+    const [name, ...rest] = process.argv.slice(2);
+    if (name === "-h" || name === "--help")
+        return usage(true);
+    if (name === "-v" || name === "--version") {
+        print(`${CLI_VERSION}\n`);
+        return 0;
+    }
+    if (!name)
+        return usage();
+    const command = COMMANDS[name];
+    if (!command) {
+        eprint(`symbols: unknown command '${name}'\n`);
+        return usage();
+    }
+    const mod = await command.load();
+    const code = await mod.run(rest);
+    return typeof code === "number" ? code : 0;
+}
+main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    // One place that decides how a failure looks. Never print a stack to a user
+    // unless they asked — and never print a credential, which is why this
+    // formats the message rather than dumping the error object.
+    const msg = err instanceof Error ? err.message : String(err);
+    eprint(`symbols: ${msg}\n`);
+    if (process.env["SYMBOLS_DEBUG"] === "1" && err instanceof Error && err.stack) {
+        eprint(`${err.stack}\n`);
+    }
+    process.exit(1);
+});