@symbols-cli/cli 0.0.1

package/dist/sync/watcher.js

@@ -0,0 +1,206 @@
+// 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.
+// The filesystem watcher.
+//
+// ## It decides NOTHING. That is the whole design.
+//
+// `reconcile` is the guarantee; events are the optimisation
+// (`odin_notebook_writeback.rs` header, and the plan's port list). This file
+// therefore emits ONE kind of fact — *"this path may have changed"* — and never
+// an interpretation of it. There is no "delete" event here, no "rename" event,
+// no content, no hash. The sweep re-STATS every dirty path and runs the same
+// `decide()` table a full sweep runs.
+//
+// ⚠ THAT IS WHAT MAKES THE VIM DANCE PASS STRUCTURALLY RATHER THAN BY LUCK.
+//
+// A vim `:w` on `strategy.py` produces, in order:
+//
+//     create 4913 · delete 4913        (the writability probe)
+//     create strategy.py~              (the backup)
+//     delete strategy.py               (the rename away)
+//     create strategy.py               (the rename in)
+//
+// A watcher that maps events to operations sends DELETE then POST — two writes,
+// a window where the file does not exist server-side, and a new row id that
+// invalidates every ledger `file_id`. If the DELETE lands and the POST does not,
+// the file is gone.
+//
+// Here: `4913` and `strategy.py~` are dropped by `isEditorTemp`; the remaining
+// two events collapse into one dirty entry for `strategy.py`; the debounce
+// expires; the sweep stats the path, finds it present with new content, and
+// issues exactly **one PATCH and zero DELETE**. No special case, no rename
+// pairing heuristic, no cookie matching. The path that produced a delete
+// server-side is the one where the sweep gets an affirmative ENOENT — which is
+// the ported rule (`settle_vanish`, :513-519) stated as an architecture instead
+// of a check.
+//
+// ## Started BEFORE the initial materialize
+//
+// Ported from `start()` (:1746-1780): the watcher is spawned first and the
+// materialize runs after. On the server that ordering closed a ~90s window in
+// which terminal writes produced no event and nothing replayed the gap. Locally
+// the pull is faster but the window is the same shape, and the loop-breaker
+// (`S === L` -> `none`) is what makes it safe: the sweep's own writes come back
+// as dirty paths, hash equal, and stop there.
+import { watch } from "chokidar";
+import { relative, sep } from "node:path";
+import { shouldIgnore, isCliManaged } from "./paths.js";
+import { eprint } from "../util/log.js";
+export class Watcher {
+    opts;
+    fsw = null;
+    dirty = new Set();
+    timer = null;
+    firstDirtyAt = 0;
+    debounceMs;
+    maxWaitMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.debounceMs = opts.debounceMs ?? 300;
+        this.maxWaitMs = opts.maxWaitMs ?? 3_000;
+    }
+    /** Resolves once the initial scan has completed and events are flowing. */
+    async start() {
+        const w = watch(this.opts.root, {
+            // The sweep enumerates the tree itself; replaying it as events would
+            // duplicate the whole project into the dirty set on every start.
+            ignoreInitial: true,
+            persistent: true,
+            followSymlinks: false,
+            // `add` for a large file can fire while it is still being written. This
+            // only delays the EVENT — a partially-observed file is still re-hashed by
+            // the sweep, so the worst case is a redundant pass, never a truncated push.
+            awaitWriteFinish: { stabilityThreshold: 150, pollInterval: 50 },
+            ignored: (p) => {
+                const rel = this.rel(p);
+                // The root itself, and anything above it, are not ignorable.
+                if (rel === "" || rel === null)
+                    return false;
+                return this.skip(rel);
+            },
+        });
+        // Every event maps to the SAME fact. Listing them separately is deliberate:
+        // it documents that we know which events exist and chose to erase the
+        // distinction, rather than having missed one.
+        for (const ev of ["add", "change", "unlink"]) {
+            w.on(ev, (p) => this.mark(p));
+        }
+        // Directory events matter only because a directory delete removes files
+        // whose own `unlink` events chokidar may not emit. Marking the directory
+        // path lets the sweep notice; the sweep enumerates, so it finds the children.
+        for (const ev of ["addDir", "unlinkDir"]) {
+            w.on(ev, (p) => this.mark(p, true));
+        }
+        // An error must never be silent, and must never be read as "nothing
+        // changed". The engine keeps its 60s sweep either way, which is the reason
+        // this can be a log rather than a fatal.
+        w.on("error", (err) => {
+            eprint(`symbols watch: filesystem watcher error (the 60s sweep still covers you): ${err instanceof Error ? err.message : String(err)}\n`);
+        });
+        this.fsw = w;
+        await new Promise((resolve) => w.on("ready", () => resolve()));
+    }
+    async stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        // Hand over whatever is buffered — dropping it would mean a `watch` that is
+        // stopped mid-batch silently loses the edits it had already seen.
+        this.flush();
+        await this.fsw?.close();
+        this.fsw = null;
+    }
+    /** Project-relative POSIX path, or null if the path is outside the root. */
+    rel(abs) {
+        const r = relative(this.opts.root, abs);
+        if (r === "")
+            return "";
+        if (r.startsWith("..") || r.startsWith(sep + ".."))
+            return null;
+        return r.split(sep).join("/");
+    }
+    /**
+     * Paths the watcher must not raise events for.
+     *
+     * ⚠ `isCliManaged` sits beside `shouldIgnore` here and it is load-bearing.
+     * `ensureProjects` writes `<root>/.symbols/project.json` on every run, INSIDE
+     * the watched tree — so without this the CLI's own bookkeeping wakes a sweep
+     * every time it runs, and the only thing stopping the loop is that the sweep
+     * then skips the path. Caught by the end-to-end vim-dance test, which saw
+     * `.symbols/project.json` in a batch that should have held exactly one entry.
+     *
+     * Both predicates come from `paths.ts`. Nothing is re-derived here.
+     */
+    skip(rel) {
+        return shouldIgnore(rel) || isCliManaged(rel);
+    }
+    mark(abs, isDir = false) {
+        const rel = this.rel(abs);
+        if (rel === null || rel === "")
+            return;
+        // ⚠ THE IGNORE FILTER RUNS HERE TOO, not only in chokidar's `ignored`.
+        //
+        // `ignored` prunes what is WATCHED; it does not guarantee no event for a
+        // path created after the watch was established on its parent. `isEditorTemp`
+        // is the load-bearing half (`4913`, `~`, `.swp`) and it must be applied to
+        // every event, or the vim dance leaks two junk paths into the sweep — which
+        // would create and delete a `4913` row server-side on every single save.
+        if (this.skip(rel))
+            return;
+        if (isDir) {
+            // A directory is not a file row. Mark its subtree by marking the prefix;
+            // the sweep expands it. Recorded with a trailing marker so a consumer can
+            // tell "this exact path" from "everything under here".
+            this.dirty.add(`${rel}/`);
+        }
+        else {
+            this.dirty.add(rel);
+        }
+        if (this.firstDirtyAt === 0)
+            this.firstDirtyAt = Date.now();
+        if (this.timer)
+            clearTimeout(this.timer);
+        // The starvation ceiling. If the batch has been open longer than maxWait,
+        // flush now rather than extending it again.
+        if (Date.now() - this.firstDirtyAt >= this.maxWaitMs) {
+            this.flush();
+            return;
+        }
+        this.timer = setTimeout(() => this.flush(), this.debounceMs);
+    }
+    flush() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.firstDirtyAt = 0;
+        if (this.dirty.size === 0)
+            return;
+        const batch = [...this.dirty];
+        this.dirty = new Set();
+        this.opts.onDirty(batch);
+    }
+}
+/**
+ * Expand a dirty batch into concrete paths to examine.
+ *
+ * Directory marks (`"src/"`) become "every tracked path under `src/`" — the
+ * caller supplies the tracked set, because the watcher deliberately holds no
+ * state about what exists.
+ */
+export function expandDirty(batch, tracked) {
+    const out = new Set();
+    for (const entry of batch) {
+        if (entry.endsWith("/")) {
+            for (const t of tracked) {
+                if (t.startsWith(entry))
+                    out.add(t);
+            }
+        }
+        else {
+            out.add(entry);
+        }
+    }
+    return [...out];
+}

package/dist/util/log.js

@@ -0,0 +1,58 @@
+// 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.
+// The CLI's output chokepoint.
+//
+// # Why this is a module and not 89 calls to `process.stderr.write`
+//
+// `symbols mcp` speaks JSON-RPC over **stdout**. One stray byte on that stream
+// corrupts the protocol and surfaces to the user as a client bug, miles from
+// whatever printed it. `mcp/server.ts` is careful about this today, but the
+// care lives in a comment — and a comment does not survive someone adding a
+// `console.log` to a helper three imports down.
+//
+// So stdout is claimed here. `enterProtocolMode()` latches, and after it every
+// `out()` is redirected to stderr rather than corrupting the stream. The
+// failure mode becomes a misplaced diagnostic instead of a dead session.
+//
+// ⚠ This is a chokepoint, not a logging framework. No levels, no timestamps, no
+// JSON. The CLI's output IS its user interface — `symbols status` prints a
+// report a human reads — so formatting stays at the call site where the author
+// can see it.
+/** Set once `stdout` belongs to a wire protocol. Never unset. */
+let protocolMode = false;
+/**
+ * Claim stdout for a machine-readable protocol (today: MCP's JSON-RPC).
+ *
+ * Call this BEFORE any transport is constructed. It is one-way on purpose:
+ * a mode that can be turned off is a mode that gets turned off in a `finally`.
+ */
+export function enterProtocolMode() {
+    protocolMode = true;
+}
+export function inProtocolMode() {
+    return protocolMode;
+}
+/**
+ * Human-facing output — the thing the user asked to see.
+ *
+ * Goes to stdout so it can be piped (`symbols project ls | grep foo`), EXCEPT
+ * in protocol mode, where stdout is not ours to write to.
+ */
+export function print(text) {
+    if (protocolMode) {
+        process.stderr.write(text);
+        return;
+    }
+    process.stdout.write(text);
+}
+/**
+ * Diagnostics, prompts, progress and errors.
+ *
+ * Always stderr: it must not pollute a pipe, and it must remain visible when
+ * the user is redirecting stdout to a file.
+ */
+export function eprint(text) {
+    process.stderr.write(text);
+}

package/dist/util/platform.js

@@ -0,0 +1,79 @@
+// 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.
+// Where `symbols` is allowed to write, and nothing else.
+//
+// ⚠ THE OWNERSHIP RULE — the one line every path in this CLI answers to:
+//
+//     `symbols` owns `~/Symbols/**` and its own `~/.symbols/`. IT OWNS NOTHING
+//     ELSE. It never writes `~/.claude/CLAUDE.md`, `~/.claude/settings.json`,
+//     `~/.claude.json`, or any shell rc.
+//
+// The container earned that right by owning the filesystem; the CLI has not. A
+// user's `~/.claude/` is THEIR configuration, shared with every other project
+// they work on, and a tool that edits it to make its own skills load has decided
+// on their behalf that its needs outrank a stranger's repo.
+//
+// The mechanism that makes this affordable is `claude plugin install --scope
+// project` plus a plugin-shipped `.mcp.json` — both verified real in P0's spike,
+// which is why "never write ~/.claude.json" is a rule and not an aspiration.
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * `~/.symbols` — CLI-owned state: the credential, the sync ledger, the skills
+ * bundle, the anti-rollback counter.
+ *
+ * `SYMBOLS_HOME` redirects it, which the tests and the conformance harness rely
+ * on. It is deliberately NOT a way to point the CLI at someone else's config:
+ * everything under it is written by this CLI and read by nothing else.
+ */
+export function symbolsHome() {
+    return process.env["SYMBOLS_HOME"] ?? join(homedir(), ".symbols");
+}
+/** `~/Symbols` — where projects materialise as real directories. */
+export function workspaceRoot() {
+    return process.env["SYMBOLS_WORKSPACE"] ?? join(homedir(), "Symbols");
+}
+/**
+ * The unpacked skills bundle, and the marketplace root `claude plugin
+ * marketplace add` is pointed at.
+ *
+ * Under `~/.symbols/`, never under `~/.claude/`: the plugin CACHE is Claude
+ * Code's to manage, and writing into it directly is how you get a cache whose
+ * contents disagree with `installed_plugins.json` — which is exactly the failure
+ * `symbols doctor` exists to catch.
+ */
+export function bundleRoot() {
+    return join(symbolsHome(), "plugins");
+}
+/** The manifest of the bundle currently unpacked at `bundleRoot()`. */
+export function installedManifestPath() {
+    return join(symbolsHome(), "manifest.json");
+}
+/**
+ * Open a URL in the user's default browser.
+ *
+ * ⚠ `spawn` with an ARGV ARRAY, never a shell string, so a URL can never become
+ * a command. Callers must pass a URL built from an allowlisted origin — this
+ * function does not validate, because the only safe place to decide that is
+ * where the origin is resolved (`auth/hosts.ts`).
+ *
+ * Failure is deliberately not fatal: a headless box, a missing `xdg-open`, or a
+ * locked-down desktop should print the URL rather than abort a sign-in. Every
+ * caller also prints it.
+ */
+export function openBrowser(url) {
+    const [cmd, args] = platform() === "darwin"
+        ? ["open", [url]]
+        : platform() === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+        /* printed by the caller; see above */
+    });
+    child.unref();
+}

package/dist/util/version.js

@@ -0,0 +1,24 @@
+// 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.
+// The single source of the CLI's version.
+//
+// Read from the shipped package.json rather than duplicated as a literal — a
+// version constant that drifts from the manifest is exactly the class of bug
+// this project opened with (repo 0.7.7, installed 0.7.4). One value, one place.
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+function read() {
+    try {
+        // dist/util/version.js → dist/util → dist → package root
+        const here = dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(join(here, "..", "..", "package.json"), "utf8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+export const CLI_VERSION = read();

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@symbols-cli/cli",
+  "version": "0.0.1",
+  "description": "Symbols CLI \u2014 run the Symbols agent on your own machine",
+  "type": "module",
+  "bin": {
+    "symbols": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"test/*.test.mjs\"",
+    "prepack": "rm -rf dist && tsc -p tsconfig.json --sourceMap false"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "~1.30.0",
+    "better-sqlite3": "^13.0.0",
+    "chokidar": "^4.0.0",
+    "undici": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammedraqeebb/symbols-terminal.git",
+    "directory": "apps/cli"
+  }
+}