@symbols-cli/cli 0.0.1

package/dist/skills/install.js

@@ -0,0 +1,188 @@
+// 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.
+// Point Claude Code at the verified bundle — `marketplace add`, then install
+// AND UPDATE, at PROJECT scope.
+//
+// ## `install` is not enough, and that is the bug this whole plan opens with
+//
+// `claude plugin install odin@symbols` on an already-installed plugin answers
+//
+//     ✔ Plugin odin@symbols is already installed (scope: user)
+//
+// and EXITS 0 WITHOUT UPGRADING. Only `claude plugin update` moves the cache to
+// a new version directory, and only if `plugin.json`'s `version` changed. This
+// machine is the proof, measured before this file was written:
+//
+//     repo plugins/odin-code/.claude-plugin/plugin.json  -> 0.7.7
+//     claude plugin list --json | odin@symbols .version  -> 0.7.4
+//
+// Three releases of skills, none of them installed. So: install (for a machine
+// that has never had it) AND update (for every machine that has), every time.
+// The version half of the contract is enforced at build time by
+// `scripts/publish_plugin_bundle.sh`; this is the install half.
+//
+// ## Why project scope
+//
+// User scope would put Symbols' skills into every repo the user opens. Project
+// scope confines them to `~/Symbols/<Project>`, which is the ownership rule
+// (`util/platform.ts`) applied to Claude Code's own configuration: we bind our
+// plugins to our directories and touch nothing outside them.
+//
+// ⚠ Project scope records `projectPath` in `~/.claude/plugins/installed_plugins.json`
+// as A LITERAL STRING. Renaming or moving the project directory silently detaches
+// the install and skills stop loading, with no error anywhere. `doctor` detects
+// exactly that and calls back into `installPlugins` to repair it.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { bundleRoot } from "../util/platform.js";
+const exec = promisify(execFile);
+/** The marketplace name `stage_plugins.sh` writes into the staged catalog. */
+export const MARKETPLACE = "symbols";
+export class ClaudeCliMissingError extends Error {
+    constructor() {
+        super("the `claude` CLI is not on PATH, so Symbols skills cannot be installed. " +
+            "Install Claude Code first: https://claude.com/claude-code");
+        this.name = "ClaudeCliMissingError";
+    }
+}
+async function claude(args, cwd) {
+    try {
+        const { stdout, stderr } = await exec("claude", args, { cwd, maxBuffer: 8 * 1024 * 1024 });
+        return { code: 0, out: `${stdout}${stderr}` };
+    }
+    catch (err) {
+        const e = err;
+        if (e.code === "ENOENT")
+            throw new ClaudeCliMissingError();
+        return { code: typeof e.code === "number" ? e.code : 1, out: `${e.stdout ?? ""}${e.stderr ?? ""}` };
+    }
+}
+/**
+ * Refuse to `--yes` a marketplace that can run commands.
+ *
+ * `claude plugin install --yes` accepts "the displayed marketplace-declared
+ * command" without a prompt. Ours declares none — it is a path catalog written
+ * by `stage_plugins.sh` — and passing `--yes` is only needed because the CLI
+ * runs with no TTY. Asserting the catalog is command-free keeps `--yes` from
+ * quietly becoming "run whatever the server put in the marketplace file".
+ */
+async function assertMarketplaceIsInert(root) {
+    const path = join(root, ".claude-plugin", "marketplace.json");
+    const text = await fs.readFile(path, "utf8");
+    const catalog = JSON.parse(text);
+    const offenders = [];
+    const scan = (node, where) => {
+        if (!node || typeof node !== "object")
+            return;
+        for (const [k, v] of Object.entries(node)) {
+            if (k === "command" || k === "headersHelper" || k === "installCommand") {
+                offenders.push(`${where}.${k}`);
+            }
+            if (v && typeof v === "object")
+                scan(v, `${where}.${k}`);
+        }
+    };
+    scan(catalog, "marketplace");
+    for (const [i, p] of (catalog.plugins ?? []).entries())
+        scan(p, `plugins[${i}]`);
+    if (offenders.length > 0) {
+        throw new Error(`refusing to install: the bundle's marketplace.json declares executable fields ` +
+            `(${offenders.join(", ")}). A signed bundle is still not a licence to run commands.`);
+    }
+}
+/**
+ * Register the bundle as a marketplace, then install AND update every plugin the
+ * manifest names, at project scope, with `projectPath` = `projectDir`.
+ */
+export async function installPlugins(projectDir, manifest) {
+    const root = bundleRoot();
+    await assertMarketplaceIsInert(root);
+    // ⚠ `--scope project` IS THE OWNERSHIP RULE, NOT A PREFERENCE.
+    //
+    // Measured, not assumed: `claude plugin marketplace add <dir>` with no scope
+    // answers *"Successfully added marketplace: … (declared in user settings)"* and
+    // writes `extraKnownMarketplaces` into **`~/.claude/settings.json`** — the one
+    // file `util/platform.ts` says this CLI must never touch. It is the user's, it
+    // is shared with every other project they open, and `symbols` has not earned
+    // it. `--scope project` (verified present: `claude plugin marketplace add
+    // --help` documents `--scope <scope>` as user|project|local) declares it in
+    // `<project>/.claude/settings.json` instead, where the same file's merge rules
+    // apply and the user can delete it by deleting the project.
+    //
+    // `add` on an already-known marketplace errors; `update` refreshes it from the
+    // source. Try `add`, fall back to `update` — the same order
+    // `odin_skill_sync.rs` uses, and for the same reason.
+    //
+    // ⚠ `marketplace update` takes NO `--scope` (its `--help` lists only `-h`), so
+    // it can only refresh a declaration that already exists. That is fine: it runs
+    // only after `add` failed, which means one is already declared.
+    const added = await claude(["plugin", "marketplace", "add", root, "--scope", "project"], projectDir);
+    if (added.code !== 0) {
+        const updated = await claude(["plugin", "marketplace", "update", MARKETPLACE], projectDir);
+        if (updated.code !== 0) {
+            throw new Error(`could not register the Symbols plugin marketplace at ${root}:\n${added.out}\n${updated.out}`);
+        }
+    }
+    const results = [];
+    for (const plugin of manifest.plugins) {
+        const id = `${plugin.name}@${MARKETPLACE}`;
+        // 1. install — a no-op exiting 0 on every machine that already has it.
+        const ins = await claude(["plugin", "install", id, "--scope", "project", "--yes"], projectDir);
+        // 2. update — THE LOAD-BEARING HALF. This is what moves the cache to the new
+        //    version directory that Claude Code actually reads.
+        const upd = await claude(["plugin", "update", id, "--scope", "project", "--yes"], projectDir);
+        if (ins.code !== 0 && upd.code !== 0) {
+            // ⚠ NEVER `|| true` HERE. `odin_skill_sync.rs` swallows these failures
+            // because a broken claude CLI must not break a user's SHELL; here there is
+            // no shell to protect, and a swallowed failure is precisely how 0.7.4
+            // survived three releases.
+            throw new Error(`failed to install ${id}:\n${ins.out}\n${upd.out}`);
+        }
+        results.push({
+            plugin: id,
+            installed: ins.code === 0,
+            updated: upd.code === 0,
+            detail: `${ins.out.trim()} ${upd.out.trim()}`.trim(),
+        });
+    }
+    return results;
+}
+/**
+ * `claude plugin list --json`, parsed.
+ *
+ * ⚠ THE ONLY MACHINE-READABLE SOURCE. `claude plugin details` has NO `--json`
+ * (verified: `claude plugin details --help` lists no such flag), so asserting
+ * against its output would be the substring grep this project's own opening
+ * incident argues against — a check that passes on a rendering change and fails
+ * on a cosmetic one.
+ */
+export async function listPlugins(cwd) {
+    const res = await claude(["plugin", "list", "--json"], cwd);
+    if (res.code !== 0)
+        throw new Error(`\`claude plugin list --json\` failed:\n${res.out}`);
+    let parsed;
+    try {
+        parsed = JSON.parse(res.out);
+    }
+    catch {
+        throw new Error(`\`claude plugin list --json\` did not return JSON:\n${res.out.slice(0, 400)}`);
+    }
+    if (!Array.isArray(parsed))
+        throw new Error("`claude plugin list --json` did not return an array");
+    return parsed;
+}
+/**
+ * Count `skills/*` directories under an installed plugin's `installPath`.
+ *
+ * This is the check that catches a cache which is present, correctly versioned,
+ * and MISSING SKILLS — the shape the 0.7.4/0.7.7 incident actually had, where
+ * `Skills (22)` was reported against a repo carrying 23.
+ */
+export async function countInstalledSkills(installPath) {
+    const entries = await fs.readdir(join(installPath, "skills"), { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).length;
+}

package/dist/skills/settings-merge.js

@@ -0,0 +1,107 @@
+// 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.
+// `<project>/.claude/settings.json` — MERGED, NEVER OVERWRITTEN.
+//
+// ## The two rules, and why each exists
+//
+// 1. **Never overwrite.** This file is the user's. It can hold hooks, permission
+//    rules, model choices and env — none of which we wrote and none of which we
+//    can reconstruct. Writing our own document over it destroys work silently
+//    and is not recoverable from anything the CLI holds.
+//
+// 2. **If the user disabled a plugin, RESPECT IT.** `enabledPlugins["odin@symbols"]
+//    = false` is a decision, and re-enabling it on the next `symbols up` would
+//    make the setting untouchable — the user would toggle it off and watch it
+//    come back, with no way to win. We add keys that are ABSENT and never change
+//    a key that is present.
+//
+// ⚠ This file is inside `~/Symbols/<Project>`, which the CLI owns. It is NOT
+// `~/.claude/settings.json`, which the CLI must never touch — that one is shared
+// with every other project the user works on, and editing it to make our skills
+// load would decide on their behalf that our needs outrank a stranger's repo.
+//
+// ## Why the merge is shallow-by-key rather than deep
+//
+// Only two keys are ours: `extraKnownMarketplaces.symbols` and the
+// `enabledPlugins` entries for the plugins the manifest names. A deep merge
+// would let us reach into `permissions` or `hooks` by accident, and a bug that
+// widens `permissions.allow` is the S2 class arriving through the back door.
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+import { bundleRoot } from "../util/platform.js";
+import { MARKETPLACE } from "./install.js";
+export function projectSettingsPath(projectDir) {
+    return join(projectDir, ".claude", "settings.json");
+}
+export async function mergeProjectSettings(projectDir, manifest) {
+    const path = projectSettingsPath(projectDir);
+    let doc = {};
+    let existed = false;
+    try {
+        const raw = await fs.readFile(path, "utf8");
+        existed = true;
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            // ⚠ FREEZE, never repair. A settings.json we cannot parse is a file the
+            // user is mid-edit on, or one another tool owns. Replacing it with a
+            // document we can parse is exactly the overwrite this file exists to
+            // prevent.
+            throw new Error(`${path} is not a JSON object. Refusing to touch it — fix or move it, then re-run.`);
+        }
+        doc = parsed;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            if (err instanceof SyntaxError) {
+                throw new Error(`${path} is not valid JSON. Refusing to overwrite it: ${err.message}`);
+            }
+            throw err;
+        }
+    }
+    const added = [];
+    const respected = [];
+    // ── extraKnownMarketplaces.symbols ─────────────────────────────────────────
+    const marketplaces = asObject(doc["extraKnownMarketplaces"]);
+    if (marketplaces[MARKETPLACE] === undefined) {
+        marketplaces[MARKETPLACE] = { source: { source: "directory", path: bundleRoot() } };
+        added.push(`extraKnownMarketplaces.${MARKETPLACE}`);
+    }
+    else {
+        // A user (or this repo's own checkout) may point `symbols` at a git source.
+        // Ours is a local directory; theirs wins, and `doctor` reports the
+        // divergence rather than this silently retargeting their catalog.
+        respected.push(`extraKnownMarketplaces.${MARKETPLACE}`);
+    }
+    doc["extraKnownMarketplaces"] = marketplaces;
+    // ── enabledPlugins ─────────────────────────────────────────────────────────
+    const enabled = asObject(doc["enabledPlugins"]);
+    for (const plugin of manifest.plugins) {
+        const id = `${plugin.name}@${MARKETPLACE}`;
+        if (enabled[id] === undefined) {
+            enabled[id] = true;
+            added.push(`enabledPlugins.${id}`);
+        }
+        else {
+            respected.push(`enabledPlugins.${id}=${String(enabled[id])}`);
+        }
+    }
+    doc["enabledPlugins"] = enabled;
+    const changed = added.length > 0 || !existed;
+    if (changed)
+        await writeJsonAtomic(path, doc);
+    return { path, added, respected, changed };
+}
+function asObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+/** Write-then-rename: a crash never leaves the user holding half a settings file. */
+async function writeJsonAtomic(path, doc) {
+    await fs.mkdir(dirname(path), { recursive: true, mode: 0o755 });
+    const tmp = `${path}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, JSON.stringify(doc, null, 2) + "\n", { mode: 0o644 });
+    await fs.rename(tmp, path);
+}

package/dist/sync/api.js

@@ -0,0 +1,380 @@
+// 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 wire. Notebooks, project files, cells — typed, and with every refusal
+// classified BEFORE it reaches the sync engine.
+//
+// ## Why the error classes are the important part of this file
+//
+// The engine above decides what to transfer. It must never have to guess what a
+// status code MEANT, because two of them are ambiguous on the wire and guessing
+// either one wrong is data loss:
+//
+//   * **404 on a notebook-scoped route** is not "no files". `notebook_is_owned`
+//     returns 404 for *deleted*, *never existed*, and *belongs to someone else*
+//     (`routes/project_files.rs:165,183,204,233`). A client that reads that as an
+//     empty file list computes "every path deleted on the server" and deletes the
+//     user's whole project. The >20 circuit breaker does NOT save it — the plan
+//     says so explicitly, because the breaker sees a legitimate-looking mass
+//     delete. That is guard F4, and it starts HERE with `NotebookGoneError`.
+//
+//   * **409 has two meanings on this surface**, and they demand opposite
+//     responses: the CAS mismatch (re-diff and probably conflict) and the
+//     regime/widget protection refusal (restore the local file, freeze the path).
+//     They are NOT distinguished by message text — that would be a substring
+//     grep over prose. They are distinguished STRUCTURALLY:
+//
+//       - `PATCH /api/notebooks/files/{id}` runs the regime check ONLY when the
+//         request renames the file (`routes/project_files.rs:381-394`, gated on
+//         `file_data.name != existing.name`). The sync engine never sends `name`,
+//         so a 409 from a content PATCH can only be the CAS.
+//       - `DELETE /api/notebooks/files/{id}` has no CAS at all, so its 409 can
+//         only be the protection refusal (`:522-523`).
+//
+//     `updateFile` and `deleteFile` therefore raise different classes, and
+//     neither reads a message body to decide.
+//
+// ## The hash must be byte-identical to the server's
+//
+// `content_hash` is the whole basis of the three-way diff AND of the loop
+// breaker. The server computes `hex_sha256(content)` — sha256 over the UTF-8
+// bytes of the stored String, lowercase hex
+// (`odin_notebook_writeback.rs:1740-1744`). Anything else here — a different
+// encoding, a normalized newline, a trailing-newline fixup — makes `S === L`
+// never fire, and the engine push-pulls the same file forever. That is the
+// runaway-loop class the per-device rate limit now merely bounds.
+import { createHash } from "node:crypto";
+import { request, ApiError } from "../auth/client.js";
+import { eprint } from "../util/log.js";
+// ── the size cap ─────────────────────────────────────────────────────────────
+/**
+ * Mirrors `project_file_controller::MAX_FILE_BYTES` (1 MiB), the constant P1
+ * unified the three previous caps onto.
+ *
+ * Kept as a client-side number only to decide what to ATTEMPT and what to report
+ * as skipped; the server is the authority and will refuse regardless. A client
+ * that silently drops an over-cap file, rather than reporting it, reproduces the
+ * container's worst property — work that exists nowhere else and says nothing
+ * (`odin_notebook_writeback.rs:1563-1568`).
+ */
+export const MAX_FILE_BYTES = 1_000_000;
+// ⚠ 1,000,000 — DECIMAL, matching the server's
+// `utils/file_import_security.rs:32` exactly. It was `1024 * 1024` (1,048,576),
+// leaving a 48,576-byte band where this client believed a file was carryable and
+// the server refused it. That band is invisible in testing (you have to pick a
+// file between 1,000,000 and 1,048,576 bytes) and is precisely the "whether a
+// file syncs depends on which side you ask" class the server-side unification
+// existed to end — reintroduced on the client. Found by the P6 reviewer.
+// ── errors ───────────────────────────────────────────────────────────────────
+/**
+ * The notebook is gone, or is not ours. **Never a delete signal.**
+ *
+ * Mirrors `writeback_one:1585-1592`, which refuses on an unresolvable owner and
+ * keeps every row, while `settle_vanish:513-519` deletes only on an affirmative
+ * per-path `Missing`. The two are the same rule: absence of evidence is not
+ * evidence of absence.
+ */
+export class NotebookGoneError extends Error {
+    notebookId;
+    constructor(notebookId) {
+        super(`notebook ${notebookId} is not reachable (deleted, or not owned by this account) — ` +
+            `the project is frozen offline and no local file was touched`);
+        this.notebookId = notebookId;
+        this.name = "NotebookGoneError";
+    }
+}
+/** The CAS refused: the server's `content_hash` moved since we read it. */
+export class CasConflictError extends Error {
+    fileId;
+    detail;
+    constructor(fileId, detail) {
+        super(`the server copy changed since it was read (${detail})`);
+        this.fileId = fileId;
+        this.detail = detail;
+        this.name = "CasConflictError";
+    }
+}
+/** The file backs a live regime or widget. The local copy must be RESTORED. */
+export class ProtectedFileError extends Error {
+    fileId;
+    detail;
+    constructor(fileId, detail) {
+        super(detail);
+        this.fileId = fileId;
+        this.detail = detail;
+        this.name = "ProtectedFileError";
+    }
+}
+/** The per-device limit (600/min) fired. Back off; never spin. */
+export class RateLimitedError extends Error {
+    path;
+    constructor(path) {
+        super(`rate limited by the server on ${path} — backing off`);
+        this.path = path;
+        this.name = "RateLimitedError";
+    }
+}
+/** Anything else. Kept distinct so a caller cannot mistake it for "missing". */
+export class TransportError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "TransportError";
+    }
+}
+// ── hashing ──────────────────────────────────────────────────────────────────
+/**
+ * The server's hash, exactly.
+ *
+ * `hex_sha256(&content)` = sha256 over `content.as_bytes()`, lowercase hex.
+ * Node's `createHash("sha256").update(string)` defaults to utf8, which is the
+ * same bytes — but it is spelled out here so nobody "tidies" it into a Buffer
+ * with a different default.
+ */
+export function contentHash(text) {
+    return createHash("sha256").update(Buffer.from(text, "utf8")).digest("hex");
+}
+/**
+ * Strip the canonical leading slash.
+ *
+ * ⚠ `project_files.path` is stored EITHER canonical (`/a/b.py`) or legacy
+ * slashless (`a/b.py`) — `writeback_one:1594-1599` looks up both, in that order,
+ * precisely because both exist in production data. The container resolves it the
+ * same way we do: `pf.path.trim_start_matches('/')` (`materialize_all:1407`).
+ * Normalising on READ and preserving the row's own form on WRITE is what keeps a
+ * legacy row from being duplicated as a second, canonical row.
+ */
+function toRelative(serverPath) {
+    return serverPath.replace(/^\/+/, "");
+}
+/**
+ * The form to CREATE new rows with.
+ *
+ * Canonical (leading slash), matching what the container's `writeback_one`
+ * inserts (`:1672`, binding `&canonical`). A CLI that created slashless rows
+ * would produce a second row shape for the same project and defeat the
+ * dual-lookup above the day a container touches the same notebook.
+ */
+export function toServerPath(rel) {
+    return `/${rel.replace(/^\/+/, "")}`;
+}
+// ── calls ────────────────────────────────────────────────────────────────────
+function classify(err, notebookId, path) {
+    if (err instanceof ApiError) {
+        if (err.status === 429)
+            throw new RateLimitedError(path);
+        if (err.status === 404 && notebookId !== null)
+            throw new NotebookGoneError(notebookId);
+        // 403 on a notebook route is an ownership failure by another name — a Clerk
+        // duplicate-row account lands here rather than on 404. Same verdict: freeze.
+        if (err.status === 403 && notebookId !== null)
+            throw new NotebookGoneError(notebookId);
+        throw new TransportError(err.status, err.message);
+    }
+    throw err;
+}
+export async function listProjects() {
+    try {
+        const res = await request("/api/cli/projects");
+        const body = res.body;
+        // Tolerate both an array and a `{projects: []}` envelope — the route is new
+        // and this costs one line, where guessing wrong costs an empty project list
+        // that reads as "you have no notebooks".
+        const list = Array.isArray(body) ? body : (body?.projects ?? []);
+        return list.map((p) => ({ id: p.id, name: p.name, dirname: p.dirname }));
+    }
+    catch (err) {
+        return classify(err, null, "/api/cli/projects");
+    }
+}
+/**
+ * The whole server side of the diff, in one request.
+ *
+ * `combined` is the ONLY hash-bearing read on this surface
+ * (`shell_token.rs:349-351` says so in the scope list), which is why the engine
+ * uses it and not `bulk-content`.
+ *
+ * ⚠ The response's `files` array carries `{id, content, content_hash}` and **NO
+ * PATH** (`schemas/project_file.rs:210-214`). Paths live only in `tree`. The
+ * join below is therefore mandatory, not an optimisation — an implementation
+ * that assumed a `path` field would silently produce zero usable rows.
+ */
+export async function snapshot(notebookId) {
+    const path = `/api/notebooks/${encodeURIComponent(notebookId)}/files/combined`;
+    let body;
+    try {
+        ({ body } = await request(path));
+    }
+    catch (err) {
+        return classify(err, notebookId, path);
+    }
+    const pathById = new Map();
+    const typeById = new Map();
+    const folders = [];
+    const walk = (nodes) => {
+        for (const n of nodes ?? []) {
+            pathById.set(n.id, toRelative(n.path));
+            typeById.set(n.id, n.type);
+            if (n.type === "folder")
+                folders.push(toRelative(n.path));
+            walk(n.children);
+        }
+    };
+    walk(body.tree);
+    const files = [];
+    for (const f of body.files ?? []) {
+        const rel = pathById.get(f.id);
+        // A content row with no tree node cannot be placed on disk. Skipping it is
+        // right (there is nowhere to write it) but it must not be silent, because
+        // the same shape would appear if the tree were ever truncated.
+        if (rel === undefined) {
+            eprint(`symbols: server file ${f.id} has content but no tree entry — skipped (report this)\n`);
+            continue;
+        }
+        if (typeById.get(f.id) === "folder")
+            continue;
+        // ⚠ A ROW WITH CONTENT BUT NO HASH IS A DELETE WAITING TO HAPPEN.
+        //
+        // `content_hash` is `Option<String>` on the wire and NULL for any row
+        // written before hashing existed. Passing that `null` through would make the
+        // diff read `S = null` = "absent on the server" — and if the file is also
+        // absent locally with `B = null`, the table produces `push-delete` and the
+        // client deletes a server row holding real content.
+        //
+        // The server's hash is a pure function of the content
+        // (`models/project_file.rs:35-37`), so computing it here recovers the true
+        // `S` exactly rather than approximating it. A genuinely content-less row
+        // (`content = NULL`) keeps `S = null`, which is correct: `materialize_all`
+        // does not write those to disk either (`:1400-1401`).
+        const hash = f.content_hash ?? (f.content === null ? null : contentHash(f.content));
+        files.push({
+            id: f.id,
+            path: rel,
+            contentHash: hash,
+            content: f.content,
+            size: f.content === null ? null : Buffer.byteLength(f.content, "utf8"),
+            skipped: false,
+        });
+    }
+    // Files omitted for size. P1 added the hash and size here specifically so a
+    // sync engine can DIFF them rather than re-download or ignore them forever
+    // (`schemas/project_file.rs:231-242`).
+    for (const s of body.skipped ?? []) {
+        files.push({
+            id: s.id,
+            path: toRelative(s.path),
+            contentHash: s.content_hash,
+            content: null,
+            size: s.size,
+            skipped: true,
+        });
+    }
+    return { files, folders };
+}
+export async function artifacts(notebookId) {
+    const path = `/api/notebooks/${encodeURIComponent(notebookId)}/files/artifacts`;
+    try {
+        const { body } = await request(path);
+        return body ?? {};
+    }
+    catch (err) {
+        return classify(err, notebookId, path);
+    }
+}
+export async function createFile(notebookId, rel, content) {
+    const path = `/api/notebooks/${encodeURIComponent(notebookId)}/files`;
+    const name = rel.split("/").pop() ?? rel;
+    try {
+        const { body } = await request(path, {
+            method: "POST",
+            body: { name, path: toServerPath(rel), file_type: "file", content },
+        });
+        return { id: body.id };
+    }
+    catch (err) {
+        return classify(err, notebookId, path);
+    }
+}
+/**
+ * Push content with compare-and-swap.
+ *
+ * ⚠ `base_content_hash` IS NOT OPTIONAL FOR US, even though the server makes it
+ * optional (`schemas/project_file.rs:79-80`, kept optional so the web editor and
+ * the container writeback are unaffected). Omitting it restores the blind
+ * overwrite this whole design exists to eliminate — the client decides "the
+ * server has not moved", the tile saves in the gap, and that edit is gone with
+ * no trace. Every push from this client opts in.
+ *
+ * `null` means "we believe there is no server content yet"; the server compares
+ * against `""` in that case (`routes/project_files.rs:426`, `unwrap_or("")`), so
+ * the empty string is the correct wire value for it.
+ *
+ * ⚠ `name` is deliberately NOT sent. The regime-protection check on this route
+ * fires only when `name` changes, so leaving it out keeps a 409 unambiguous.
+ */
+export async function updateFile(fileId, content, baseContentHash) {
+    const path = `/api/notebooks/files/${encodeURIComponent(fileId)}`;
+    try {
+        await request(path, {
+            method: "PATCH",
+            body: { content, base_content_hash: baseContentHash ?? "" },
+        });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 409) {
+            throw new CasConflictError(fileId, err.message);
+        }
+        if (err instanceof ApiError && err.status === 404) {
+            // A FILE 404, not a notebook 404 — this route is keyed on file id. The row
+            // is gone; the caller re-diffs and will create it if the local copy stands.
+            throw new TransportError(404, `file ${fileId} no longer exists on the server`);
+        }
+        return classify(err, null, path);
+    }
+}
+/**
+ * Delete a row.
+ *
+ * A 409 here can ONLY be the regime/widget protection — this route has no CAS
+ * (`routes/project_files.rs:505-538`). A 404 means it is already gone, which is
+ * the outcome we wanted, so it succeeds.
+ */
+export async function deleteFile(fileId) {
+    const path = `/api/notebooks/files/${encodeURIComponent(fileId)}`;
+    try {
+        await request(path, { method: "DELETE" });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 409) {
+            throw new ProtectedFileError(fileId, err.message);
+        }
+        if (err instanceof ApiError && err.status === 404)
+            return; // already gone
+        return classify(err, null, path);
+    }
+}
+export async function createNotebook(name) {
+    try {
+        const { body } = await request("/api/notebooks", {
+            method: "POST",
+            body: { name },
+        });
+        return body;
+    }
+    catch (err) {
+        return classify(err, null, "/api/notebooks");
+    }
+}
+export async function deleteNotebook(notebookId) {
+    const path = `/api/notebooks/${encodeURIComponent(notebookId)}`;
+    try {
+        await request(path, { method: "DELETE" });
+    }
+    catch (err) {
+        if (err instanceof ApiError && err.status === 404)
+            return;
+        return classify(err, null, path);
+    }
+}