waterplane 0.0.1 → 0.1.6

package/packages/host/dist/rootchoice.js

@@ -0,0 +1,101 @@
+/**
+ * The code root a person chose themselves — in the phone's one-time "which folder holds your
+ * repos?" dialog, or later in Settings — kept in `<config dir>/root.json`.
+ *
+ *  - **Precedence: the knob, then this file, then the automatic pick.** `WATERPLANE_ROOT` in
+ *    the environment (shell, service `--env`, Docker) always wins: whoever set it there meant it,
+ *    and the dialog never appears for a named root. The file only replaces the GUESS.
+ *  - **In the per-user config dir, not the state dir and not a `.env`.** It is read at boot,
+ *    before any `.env` loads and before the legacy `<ROOT>/.waterplane` state move — both of
+ *    which need the root first. `configDir()` depends on nothing but the environment, so
+ *    reading it here is not circular. And NOT a key in the host `.env` that `POST /api/secret`
+ *    writes: that route has no tier gate, and the root decides what the phone can reach.
+ *  - **Read once at boot.** `ROOT` is a module-level constant handed to ~30 constructors, so a
+ *    change takes a restart. Under launchd/systemd the route exits and the supervisor brings the
+ *    host back with the new root; started by hand, the person is told to restart it.
+ *  - **Only the trusted path writes it** (`AuthManager.canManage`: loopback + Tailscale, never
+ *    LAN) — the same rule as the LAN password.
+ *
+ * Imported by `env.ts` before anything else runs, so this module stays env-free: node, `branddirs`
+ * and `jsonstore` only. Counting repos (which reads knobs) is the route's job.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { BRAND, LEGACY } from "@waterplane/shared";
+import { CODE_FOLDERS, configDir } from "./branddirs.js";
+import { readJsonGuarded, writeJsonAtomic } from "./jsonstore.js";
+export const ROOT_CHOICE_FILE = "root.json";
+/** `<config dir>/root.json`. */
+export function rootChoicePath() {
+    return join(configDir(), ROOT_CHOICE_FILE);
+}
+/** The stored root, or undefined when there is none (absent, corrupt, or not absolute). Never throws. */
+export function readChosenRoot(path = rootChoicePath()) {
+    const doc = readJsonGuarded(path, {}, (v) => !!v && typeof v === "object" && !Array.isArray(v));
+    const r = typeof doc.root === "string" ? doc.root.trim() : "";
+    return r && isAbsolute(r) ? r : undefined;
+}
+export function writeChosenRoot(root, path = rootChoicePath()) {
+    writeJsonAtomic(path, { root, chosenAt: new Date().toISOString() });
+}
+const isDir = (p) => { try {
+    return statSync(p).isDirectory();
+}
+catch {
+    return false;
+} };
+/**
+ * A typed folder, made absolute (`~` and `~/x` expand to the home) and checked: a directory that
+ * exists, and not the top of a disk. The error is a sentence the phone shows as is.
+ */
+export function cleanRootInput(input, home = homedir()) {
+    let p = typeof input === "string" ? input.trim() : "";
+    if (!p)
+        return { ok: false, error: "Type the folder that holds your repos." };
+    if (p === "~")
+        p = home;
+    else if (p.startsWith("~/") || p.startsWith("~\\"))
+        p = join(home, p.slice(2));
+    if (!isAbsolute(p))
+        return { ok: false, error: `Use a full path, e.g. ${join(home, "dev")}.` };
+    p = resolve(p);
+    if (dirname(p) === p)
+        return { ok: false, error: "Not the whole disk — pick the folder your repos are in." };
+    if (!isDir(p))
+        return { ok: false, error: `${p} is not a folder on this desktop.` };
+    return { ok: true, root: p };
+}
+/** The usual code folders that exist under the home — what the dialog offers before anyone types. */
+export function rootCandidates(home = homedir(), platform = process.platform) {
+    // Same macOS exception as `pickCodeRoot`: touching ~/Documents raises a privacy prompt.
+    const rels = platform === "darwin" ? CODE_FOLDERS.filter((r) => !r.startsWith("Documents/")) : CODE_FOLDERS;
+    return rels.map((r) => resolve(home, r)).filter(isDir);
+}
+/**
+ * Which supervisor brings this process back after a clean exit, or null when nothing will.
+ * Asked narrowly on purpose — a false yes means the host exits and stays down:
+ * launchd names the job in `XPC_SERVICE_NAME`; a systemd unit's cgroup ends in the unit name.
+ * (`INVOCATION_ID` alone is not enough: a shell in a terminal that runs as a user service has it.)
+ */
+export function hostSupervisor(e = process.env, readCgroup = defaultCgroup) {
+    const labels = [BRAND.launchdLabel, ...LEGACY.map((l) => l.launchdLabel)];
+    if (e.XPC_SERVICE_NAME && labels.includes(e.XPC_SERVICE_NAME))
+        return "launchd";
+    const units = [BRAND.slug, ...LEGACY.map((l) => l.slug)].map((s) => `/${s}.service`);
+    const cg = readCgroup();
+    if (cg && cg.split("\n").some((line) => units.some((u) => line.trimEnd().endsWith(u))))
+        return "systemd";
+    return null;
+}
+function defaultCgroup() {
+    if (process.platform !== "linux")
+        return "";
+    try {
+        return readFileSync("/proc/self/cgroup", "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=rootchoice.js.map

package/packages/host/dist/rootchoice.js.map

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

package/packages/host/dist/routes/apihost.d.ts

@@ -0,0 +1,2 @@
+import { type ApiEntry } from "./apitable.js";
+export declare const HOST_ROUTES: readonly ApiEntry[];

package/packages/host/dist/routes/apihost.js

@@ -0,0 +1,532 @@
+/**
+ * HTTP routes about the desktop and every repo at once: the repo listing,
+ * what the desktop is holding (storage), the cross-repo artifact search,
+ * `/api/host/*` (setup preferences, machine stats, screenshot, clipboard, the
+ * highlighter's text reader, dictation), scaffolding and the write-only
+ * secrets. Moved out of `api.ts` (host-architecture.md, "api.ts — the HTTP
+ * routes as tables").
+ */
+import { statSync } from "node:fs";
+import { ASK_RULE_BACKENDS, ASK_RULES_STALE, SUGGESTED_ASK_RULES, DICTATE_MAX_BYTES, DICTATE_MAX_SECONDS, envName } from "@waterplane/shared";
+import { discoverTargets, findTarget, listTargets } from "../repos.js";
+import { countOutbox, outboxSeenAt, discoverArtifactsAsync, newOutboxPath } from "../files.js";
+import { hostStat, takeScreenshot, setHostClipboard } from "../host.js";
+import { dictateStatusLive, transcribe } from "../dictate.js";
+import { ocrStatus, readImageLocal } from "../ocrlocal.js";
+import { cloneRepo, newFolder, newRepo, newWorktree } from "../scaffold.js";
+import { changedCountsWithin, gitRunningIn } from "../git.js";
+import { listWriteTargets, setSecret } from "../secrets.js";
+import { setupPrefsStore } from "../setupprefs.js";
+import { askRulesStore } from "../askrules.js";
+import { ASK_RULES_SCOPE, browserOriginRefusal, confirmGate } from "../confirmgate.js";
+import { hostChecks, hostFixes } from "../plugins/setupcontrib.js";
+import { canReadRepoHealth } from "../repohealth.js";
+import { surveyTransport } from "../transportsurvey.js";
+import { clearHostStore, hostStoreReport } from "../hoststore.js";
+import { worktreeOwners } from "../worktreeowner.js";
+import { ROOT_PICKED } from "../env.js";
+import { requestPeerKind } from "../net.js";
+import { restartSelf } from "../updates/restart.js";
+import { cleanRootInput, hostSupervisor, readChosenRoot, rootCandidates, rootChoicePath, writeChosenRoot } from "../rootchoice.js";
+import { json, readBody, readJson } from "./apiio.js";
+import { route } from "./apitable.js";
+/** How long the repo listing waits for its git counts before answering with the last ones. */
+const CHANGED_BUDGET_MS = 2500;
+/** …and when every worktree already has a count: long enough for a local disk's fresh answer. */
+const CHANGED_REFRESH_MS = 400;
+/** A whole phone photo, sent once at the size the phone holds it. */
+const MAX_LOCAL_OCR_BYTES = 24 * 1024 * 1024;
+// One dictation, as 16 kHz mono PCM — exactly 32 kB per second of speech, so
+// this ceiling IS `DICTATE_MAX_SECONDS` expressed in the unit the transport
+// can refuse on before the body has been read. `shared/dictate.ts` owns the
+// number; this is the same fact, not a second opinion about it.
+const MAX_DICTATE_BYTES = DICTATE_MAX_BYTES;
+// ── Desktop host introspection ──────────────────────────────────────
+// The setup checklist's host-wide choices (today: the auto-compact window
+// its fix writes). Read by Settings; the POST refuses in words and stores
+// nothing for a value outside the range, `null` goes back to the default.
+const setupPrefs = async ({ req, res, method }) => {
+    const store = setupPrefsStore();
+    if (!store) {
+        json(res, { ok: false, error: "no setup-preferences store on this host" }, 503);
+        return true;
+    }
+    if (method === "POST") {
+        const body = await readJson(req);
+        const r = store.setAutoCompactDefault(body?.autoCompactDefault ?? null);
+        if (!r.ok) {
+            json(res, { ok: false, error: r.error }, 400);
+            return true;
+        }
+    }
+    const d = store.autoCompactDefault();
+    json(res, { ok: true, autoCompactDefault: d.value, chosen: d.chosen });
+    return true;
+};
+// ── Ask rules (`askrules.ts`, agent-authority §2) ──────────────────
+// The permission rules every claude launch is given as `permissions.ask`. GET reads and
+// mints a one-shot confirm bound to the list's `rev`; PUT replaces the whole list and
+// needs BOTH `confirmgate.ts` gates: (a) a browser `Origin` and (b) that confirm, for the
+// CURRENT rev. A forged Origin alone no longer deletes the rule that asks about the
+// forger, and a phone holding an older copy is refused instead of overwriting a list it
+// never saw. The token is consumed only by a save that landed; its reply carries a fresh one.
+const askRules = async ({ req, res, method }) => {
+    const store = askRulesStore();
+    if (!store) {
+        json(res, { ok: false, error: "no ask-rules store on this host" }, 503);
+        return true;
+    }
+    let dropped;
+    if (method === "PUT") {
+        const why = browserOriginRefusal(req);
+        if (why) {
+            json(res, { ok: false, error: `${why} — the ask rules were not changed` }, 403);
+            return true;
+        }
+        const body = await readJson(req);
+        const sent = body && typeof body === "object" && Array.isArray(body.rules) ? body.rules : null;
+        if (!sent) {
+            json(res, { ok: false, error: "send { rules: [...] } — the ask rules were not changed" }, 400);
+            return true;
+        }
+        if (typeof body.rev !== "string") {
+            json(res, { ok: false, error: "send the rev the list was read at — reopen the ask rules; nothing was changed" }, 400);
+            return true;
+        }
+        const rev = store.rev();
+        if (body.rev !== rev) {
+            json(res, { ok: false, error: ASK_RULES_STALE, stale: true }, 409);
+            return true;
+        }
+        const refused = confirmGate.check(body.confirm, ASK_RULES_SCOPE, rev);
+        if (refused) {
+            json(res, { ok: false, error: `${refused} — the ask rules were not changed` }, 403);
+            return true;
+        }
+        let kept;
+        try {
+            kept = store.set({ rules: sent });
+        }
+        catch (e) {
+            json(res, { ok: false, error: `the ask rules could not be saved (${e?.message ?? e}) — nothing was changed` }, 500);
+            return true;
+        }
+        confirmGate.consume(body.confirm);
+        dropped = sent.length - kept.rules.length;
+        // The confirm gate's promise: an accepted change leaves a line saying it happened.
+        console.log(`[askrules] list replaced from ${req.headers.origin}: ${kept.rules.length} rule(s)` +
+            (dropped ? `, ${dropped} dropped` : "") + ` (rev ${rev} → ${store.rev()})`);
+    }
+    const rev = store.rev();
+    const reply = {
+        ok: true, doc: store.get(), suggested: SUGGESTED_ASK_RULES, honouredBy: ASK_RULE_BACKENDS,
+        rev, confirm: confirmGate.mint(ASK_RULES_SCOPE, rev),
+        ...(dropped !== undefined ? { dropped } : {}),
+        ...(store.lost() ? { lost: store.lost() } : {}),
+    };
+    json(res, reply);
+    return true;
+};
+// ── The code folder (`rootchoice.ts`) ──────────────────────────────
+// What the running host scans, how it came about, and the usual folders that
+// exist — for the phone's one-time dialog and its Settings row. A POST checks
+// a folder (`save` absent) or keeps it in `<config dir>/root.json`; only the
+// trusted path may (loopback + Tailscale, the LAN-password rule), because the
+// root is what the phone can reach. Read once at boot, so a save restarts the
+// host when a supervisor will bring it back, and says "restart it" otherwise.
+const isDirNow = (p) => { try {
+    return statSync(p).isDirectory();
+}
+catch {
+    return false;
+} };
+const countRepos = async (dir) => {
+    try {
+        return (await discoverTargets(dir)).length;
+    }
+    catch {
+        return 0;
+    }
+};
+const rootInfo = async ({ req, res }, ctx) => {
+    const chosen = ROOT_PICKED === "named" ? undefined : readChosenRoot();
+    const candidates = await Promise.all(rootCandidates().map(async (path) => ({ path, repos: await countRepos(path) })));
+    const rootExists = isDirNow(ctx.root);
+    const info = {
+        ok: true,
+        root: ctx.root,
+        picked: ROOT_PICKED,
+        rootExists,
+        repos: rootExists ? await countRepos(ctx.root) : 0,
+        pending: chosen && chosen !== ctx.root ? chosen : null,
+        choicePath: rootChoicePath(),
+        envName: envName("ROOT"),
+        canChange: !!ctx.canManage?.(requestPeerKind(req.socket.remoteAddress, req.headers)),
+        restart: hostSupervisor() ? "auto" : "manual",
+        candidates,
+    };
+    json(res, info);
+    return true;
+};
+const rootPost = async ({ req, res }, ctx) => {
+    const reply = (r, status = 200) => (json(res, r, status), true);
+    if (!ctx.canManage?.(requestPeerKind(req.socket.remoteAddress, req.headers))) {
+        return reply({ ok: false, error: "The code folder can only be changed from this desktop or over Tailscale." }, 403);
+    }
+    const body = await readJson(req);
+    const c = cleanRootInput(body?.path);
+    if (!c.ok)
+        return reply({ ok: false, error: c.error }, 400);
+    const repos = await countRepos(c.root);
+    if (body?.save !== true)
+        return reply({ ok: true, root: c.root, repos });
+    if (ROOT_PICKED === "named") {
+        return reply({ ok: false, error: `${envName("ROOT")} is set where the host is started, and it wins over a choice made here — change it there.` }, 409);
+    }
+    try {
+        writeChosenRoot(c.root);
+    }
+    catch (e) {
+        return reply({ ok: false, error: `Could not save it: ${e.message}` }, 500);
+    }
+    console.log(`[root] code folder chosen: ${c.root} (${rootChoicePath()})`);
+    if (c.root === ctx.root)
+        return reply({ ok: true, root: c.root, repos, saved: true, restart: "none" });
+    // After the reply is out: the SIGTERM flush (`shutdown.ts`) runs as for any restart, and
+    // launchd/systemd start the host again, which reads the new folder at boot.
+    const sup = hostSupervisor();
+    if (sup)
+        console.log(`[root] restarting under ${sup} to scan it`);
+    return reply({ ok: true, root: c.root, repos, saved: true, restart: restartSelf(null) });
+};
+export const HOST_ROUTES = [
+    route("GET", "/api/repos", async ({ res }, ctx) => {
+        const targets = await listTargets(ctx.root);
+        for (const t of targets) {
+            t.outboxCount = countOutbox(t.worktreePath);
+            // The EDGE the count was taken at, so a tap on the badge can cut the
+            // gallery to exactly what it counted rather than to a guess at it.
+            if (t.outboxCount > 0)
+                t.outboxSeenAt = outboxSeenAt(t.worktreePath);
+        }
+        // Read the setup verdict from the sweep's store, never by inspecting here:
+        // a repo listing is fetched on every launcher open, and running six git
+        // subprocesses per repo per fetch would make the list slower than the thing
+        // it is listing. Unchecked worktrees carry no `setup` at all.
+        for (const t of targets)
+            t.setup = ctx.setup.stateFor(t.worktreePath);
+        // Whether ANY engine can read this worktree — the repo's own
+        // `tools/repohealth.mjs` if it carries one, else this desktop's bundled
+        // engine pointed at it with `--root=`. Still one `existsSync` per repo and
+        // deliberately not a run of it. This used to be "does this repo carry the
+        // tool", which was false for twelve of the thirteen repos here and hid the
+        // control on every one of them; `false` now means the DESKTOP has no
+        // engine, which is a real fault and says so in `repoHealthUnavailableText`.
+        for (const t of targets)
+            t.hasRepoHealth = canReadRepoHealth(t.worktreePath);
+        // The health index from the watcher's cache only — the engine never runs in this request.
+        for (const t of targets) {
+            const h = ctx.health?.summaryFor(t.worktreePath);
+            if (h)
+                t.healthIndex = h;
+        }
+        // Which live session spawned each agent worktree, so the launcher draws
+        // it under that session. Off the CLI's own subagent records.
+        const owners = worktreeOwners(ctx.sessions.list());
+        for (const t of targets) {
+            const o = !t.isPrimary && owners.get(t.worktreePath);
+            if (o)
+                t.ownerSessionId = o;
+        }
+        // Within a budget: a repo whose `git status` is still running (WSL on `/mnt/c` can take a
+        // minute) keeps its last count, or none yet — never holds the whole list (`changedCountsWithin`).
+        const counts = await changedCountsWithin(targets.map((t) => t.worktreePath), CHANGED_BUDGET_MS, CHANGED_REFRESH_MS);
+        for (const t of targets) {
+            const c = counts.get(t.worktreePath);
+            if (!c)
+                continue;
+            t.changedCount = c.changed;
+            if (c.ahead !== undefined) {
+                t.ahead = c.ahead;
+                t.behind = c.behind;
+            }
+            if (c.hasOrigin !== undefined)
+                t.hasOrigin = c.hasOrigin;
+        }
+        // A push or pull in flight, off the jobs' own maps — no subprocess.
+        for (const t of targets) {
+            const g = gitRunningIn(t.worktreePath);
+            if (g)
+                t.gitRunning = g;
+        }
+        // A build command in flight, off the intent rows that are its runs.
+        for (const t of targets) {
+            const b = ctx.builds?.runningIn(t.worktreePath);
+            if (b)
+                t.buildRunning = b;
+        }
+        json(res, { targets });
+        return true;
+    }),
+    // ── What the DESKTOP is holding ───────────────────────────────────────────
+    //
+    // Beside `/api/search` and deliberately NOT under `/api/repos/…`: the branch
+    // below treats the segment after `/api/repos/` as a repo id, and these three
+    // are about every repo at once and about the daemon's own store.
+    //
+    // The survey is a pure read, so GET is correct under the security model; the
+    // clear deletes, so it is POST — a side-effecting endpoint must not be a GET
+    // (CLAUDE.md), and `origin.ts` checks both on `Origin` and `Host` either way.
+    route("GET", "/api/storage/transport", async ({ res }, ctx) => {
+        json(res, await surveyTransport(ctx.root));
+        return true;
+    }),
+    // Every Android app's repo half of "installs itself", across every repo — the Apps
+    // screen's checklist joins it with the phone's half. A pure read, so GET.
+    route("GET", "/api/apps/readiness", async ({ res }, ctx) => {
+        if (!ctx.appReadiness)
+            return false;
+        json(res, await ctx.appReadiness());
+        return true;
+    }),
+    route("GET", "/api/storage/host", ({ res }, ctx) => {
+        json(res, hostStoreReport(ctx.root));
+        return true;
+    }),
+    // Takes a catalogue ID and an INSTANT — never a path. `hoststore.ts` states
+    // the whole guard; the short version is that no filename in this directory
+    // ever comes from a request, and `at` is what keeps the clear inside the
+    // reading the person actually looked at.
+    route("POST", "/api/storage/host/clear", async ({ req, res }, ctx) => {
+        const body = await readJson(req);
+        const store = typeof body?.store === "string" ? body.store : "";
+        const at = Number(body?.at);
+        if (!store || !Number.isFinite(at) || at <= 0) {
+            json(res, { error: "store (a catalogue id) and at (the instant the report was read) are both required" }, 400);
+            return true;
+        }
+        // 200 even when it refused: the body says what became of the request, and a
+        // non-2xx would collapse "this is never clearable" — a sentence a person
+        // should read — into the phone's generic error state.
+        json(res, clearHostStore(ctx.root, store, at));
+        return true;
+    }),
+    // Cross-repo artifact search. Walks every discovered repo (or a supplied
+    // subset via ?repos=id1,id2 — the phone passes its non-hidden repo ids) and
+    // aggregates matching images/documents, newest first.
+    route("GET", "/api/search", async ({ res, url }, ctx) => {
+        const query = url.searchParams.get("q") || undefined;
+        const fkind = url.searchParams.get("kind") || undefined;
+        const scope = url.searchParams.get("scope") || "repo";
+        const since = Number(url.searchParams.get("since") || 0) || undefined;
+        const limit = Math.min(Number(url.searchParams.get("limit") || 0) || 300, 1000);
+        const reposParam = url.searchParams.get("repos");
+        const allowed = reposParam ? new Set(reposParam.split(",").map((s) => s.trim()).filter(Boolean)) : null;
+        const targets = await discoverTargets(ctx.root);
+        const hits = [];
+        for (const t of targets) {
+            if (allowed && !allowed.has(t.id))
+                continue;
+            const { files } = await discoverArtifactsAsync(t.worktreePath, { scope, sinceSeconds: since, query, kind: fkind, limit, includeInbox: true });
+            for (const f of files)
+                hits.push({ repoId: t.id, repoName: t.repoName, branch: t.branch, ...f });
+        }
+        hits.sort((a, b) => b.mtime - a.mtime);
+        json(res, { hits: hits.slice(0, limit), truncated: hits.length > limit });
+        return true;
+    }),
+    route("GET", "/api/host/root", rootInfo),
+    route("POST", "/api/host/root", rootPost),
+    route("GET", "/api/host/setupprefs", setupPrefs),
+    route("POST", "/api/host/setupprefs", setupPrefs),
+    route("GET", "/api/askrules", askRules),
+    route("PUT", "/api/askrules", askRules),
+    // The desktop's own checklist: the rows about this machine (`scope: "host"`), which no repo's
+    // checklist lists. The fix answers with the re-read rows and the fix's own words.
+    route("GET", "/api/host/setup", ({ res }, ctx) => {
+        json(res, { checks: hostChecks(ctx.root) });
+        return true;
+    }),
+    route("POST", "/api/host/setup/fix", async ({ req, res }, ctx) => {
+        const { fixes } = await readJson(req);
+        const list = Array.isArray(fixes) ? fixes.map(String) : [];
+        const ran = hostFixes(list, ctx.root);
+        const reply = {
+            ok: true,
+            applied: ran.filter((r) => r.outcome.applied).map((r) => r.id),
+            notes: ran.length ? ran.map((r) => r.outcome.note) : ["Nothing to fix: no desktop row names that fix any more."],
+            checks: hostChecks(ctx.root),
+        };
+        json(res, reply);
+        return true;
+    }),
+    route("GET", "/api/host/stat", ({ res }) => {
+        json(res, hostStat());
+        return true;
+    }),
+    // Capture the desktop screen into the repo's outbox; return the artifact.
+    // POST, not GET, precisely because it has a side effect: a cross-origin GET
+    // (an `<img src>` on a malicious page) carries no `Origin` header, so the
+    // same-origin guard cannot see it coming. A POST always carries one.
+    route("POST", "/api/host/screenshot", async ({ res, url }, ctx) => {
+        const target = await findTarget(ctx.root, url.searchParams.get("repo") || "");
+        if (!target)
+            return json(res, { error: "unknown repo" }, 404), true;
+        let dest;
+        try {
+            dest = newOutboxPath(target.worktreePath, "screenshot", ".png");
+            await takeScreenshot(dest.full);
+        }
+        catch (e) {
+            return json(res, { error: String(e.message || e) }, 500), true;
+        }
+        let size = 0, mtime = Date.now(), ctime = mtime;
+        try {
+            const st = statSync(dest.full);
+            size = st.size;
+            mtime = st.mtimeMs;
+            ctime = st.birthtimeMs > 0 ? st.birthtimeMs : st.mtimeMs;
+        }
+        catch { /* keep defaults */ }
+        json(res, { file: { name: dest.name, relPath: dest.relPath, size, mtime, ctime } });
+        return true;
+    }),
+    // Push text from the phone onto the desktop host's system clipboard.
+    route("POST", "/api/host/clipboard", async ({ req, res }) => {
+        const { text } = await readJson(req);
+        const s = String(text ?? "");
+        if (!s)
+            return json(res, { ok: false, error: "empty" }, 400), true;
+        if (s.length > 1_000_000)
+            return json(res, { ok: false, error: "too large" }, 413), true;
+        try {
+            await setHostClipboard(s);
+        }
+        catch (e) {
+            return json(res, { ok: false, error: String(e.message || e) }, 500), true;
+        }
+        json(res, { ok: true, chars: s.length });
+        return true;
+    }),
+    // The whole picture's words, read ON THIS DESKTOP (`ocrlocal.ts`) — the
+    // annotator's "text only": a photo with a person in it goes no further than
+    // this machine, and only the text the person then edits is ever sent. The GET
+    // is asked before the verb is offered; the POST takes the bytes as the body
+    // because the picture may never be uploaded, writes nothing, and every reason is a 200.
+    route("GET", "/api/host/ocr", async ({ res }) => {
+        json(res, await ocrStatus());
+        return true;
+    }),
+    route("POST", "/api/host/ocr", async ({ req, res }) => {
+        const tooBig = "that picture is too large to read";
+        if (Number(req.headers["content-length"] || 0) > MAX_LOCAL_OCR_BYTES)
+            return json(res, { error: tooBig }, 413), true;
+        let body;
+        try {
+            body = await readBody(req, MAX_LOCAL_OCR_BYTES);
+        }
+        catch {
+            return json(res, { error: tooBig }, 413), true;
+        }
+        if (!body.length)
+            return json(res, { error: "empty image" }, 400), true;
+        const mime = String(req.headers["content-type"] || "image/jpeg").split(";")[0].trim();
+        if (!/^image\//.test(mime))
+            return json(res, { error: "not an image" }, 400), true;
+        json(res, await readImageLocal(body, mime));
+        return true;
+    }),
+    // Dictation: audio the phone recorded, words back — read on this desktop by
+    // whisper.cpp, which costs nothing and never leaves the machine.
+    //
+    // The GET says whether the desktop can do it at all, and is asked BEFORE the
+    // microphone is opened: a button offered for a thing that will fail is worse
+    // than no button, and the reason names what to install (`Unavailable.tsx`'s
+    // rule — a dimmed control explains nothing on a phone).
+    route("GET", "/api/host/dictate", async ({ res }) => {
+        json(res, await dictateStatusLive());
+        return true;
+    }),
+    // POST for the same reason `/api/host/ocr` is: the bytes exist NOWHERE
+    // but the phone's capture graph at this point, nothing is written anywhere,
+    // and there is no repo in this route at all. A reason comes back as a 200 —
+    // "install whisper-cpp" and "nothing was said" are answers the phone SHOWS.
+    route("POST", "/api/host/dictate", async ({ req, res, url }) => {
+        const tooLong = `that is longer than ${DICTATE_MAX_SECONDS}s of audio`;
+        if (Number(req.headers["content-length"] || 0) > MAX_DICTATE_BYTES) {
+            return json(res, { error: tooLong }, 413), true;
+        }
+        let body;
+        try {
+            body = await readBody(req, MAX_DICTATE_BYTES);
+        }
+        catch {
+            return json(res, { error: tooLong }, 413), true;
+        }
+        if (!body.length)
+            return json(res, { error: "nothing was said" }, 400), true;
+        const lang = (url.searchParams.get("lang") || "").trim() || undefined;
+        // The person's vocabulary (`shared/dictateterms.ts`), re-parsed and capped
+        // on this side too: the query string is the phone's claim, not a contract.
+        const terms = url.searchParams.get("terms") || undefined;
+        json(res, await transcribe(body, { lang, terms }));
+        return true;
+    }),
+    // ── Scaffolding ─────────────────────────────────────────────────────
+    route("POST", "/api/folder", async ({ req, res }, ctx) => {
+        const { parent, name } = await readJson(req);
+        const r = await newFolder(ctx.root, parent || ctx.root, String(name || ""));
+        json(res, r, "error" in r ? 400 : 200);
+        return true;
+    }),
+    route("POST", "/api/repo", async ({ req, res }, ctx) => {
+        // `setup` is the field; `usmc` is what a client built before the rename still sends.
+        const { parent, name, setup, usmc: legacySetup, description, template } = await readJson(req);
+        const r = await newRepo(ctx.root, parent || ctx.root, String(name || ""), {
+            setup: (setup ?? legacySetup) !== false,
+            description: description ? String(description) : undefined,
+            // A template id is checked against `TEMPLATES` inside `newRepo` (unknown = refused in words).
+            ...(typeof template === "string" && template ? { template: template } : {}),
+        });
+        json(res, r, "error" in r ? 400 : 200);
+        return true;
+    }),
+    route("POST", "/api/clone", async ({ req, res }, ctx) => {
+        // The URL is checked (and the transports pinned) inside `cloneRepo`; a refusal is a sentence.
+        const { parent, url, name } = await readJson(req);
+        const r = await cloneRepo(ctx.root, parent || ctx.root, String(url || ""), name ? String(name) : undefined);
+        json(res, r, "error" in r ? 400 : 200);
+        return true;
+    }),
+    route("POST", "/api/worktree", async ({ req, res }, ctx) => {
+        const { repoId, branch, basePath } = await readJson(req);
+        const target = await findTarget(ctx.root, String(repoId || ""));
+        if (!target)
+            return json(res, { error: "unknown repo" }, 404), true;
+        const r = await newWorktree(ctx.root, target.worktreePath, String(branch || ""), basePath ? String(basePath) : undefined);
+        json(res, r, "error" in r ? 400 : 200);
+        return true;
+    }),
+    // ── Secrets (write-only) ────────────────────────────────────────────
+    // No value GET counterpart exists by design — a value written here is never
+    // readable back out. Body is never logged. Response carries only a mask.
+    // The targets listing exposes only id/label/mode/path (where to write), never
+    // any written value.
+    route("GET", "/api/secret/targets", ({ res }) => {
+        json(res, { targets: listWriteTargets() });
+        return true;
+    }),
+    route("POST", "/api/secret", async ({ req, res }, ctx) => {
+        const { scope, repoId, file, key, value, targetId } = await readJson(req);
+        if (scope === "repo") {
+            const target = await findTarget(ctx.root, String(repoId || ""));
+            if (!target)
+                return json(res, { ok: false, error: "unknown repo" }, 404), true;
+            const r = setSecret({ root: ctx.root, scope: "repo", worktree: target.worktreePath, file: file ? String(file) : undefined, key: String(key || ""), value: String(value ?? "") });
+            return json(res, r, r.ok ? 200 : 400), true;
+        }
+        const r = setSecret({ root: ctx.root, scope: "host", targetId: targetId ? String(targetId) : undefined, key: key != null ? String(key) : undefined, value: String(value ?? "") });
+        return json(res, r, r.ok ? 200 : 400), true;
+    }),
+];
+//# sourceMappingURL=apihost.js.map