@vincentt-xr/cli 0.8.0 → 0.10.0

package/dist/cli/usage-text.js

@@ -0,0 +1,97 @@
+// The help text, in its own module so it can be rendered without importing the
+// CLI entrypoint — `cli/index.ts` calls `main()` at module scope, so importing it
+// runs the CLI, writes the dx journal and sets process.exitCode.
+export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
+    `Usage: vincentt <command> [options]\n\n` +
+    `Getting started (building a new app with a coding agent)\n` +
+    `  1. Confirm a project name with the developer first.\n` +
+    `  2. Create:  vincentt create <name>     (scaffolds if the folder is empty)\n` +
+    `  3. The scaffold writes the agent contract into the project root. Read it,\n` +
+    `     confirm the project is ready, and stop — do NOT invent an app.\n` +
+    `     Wait for the developer to describe what to build.\n` +
+    `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
+    `Auth\n` +
+    `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
+    `                       [--api <url>] [--console <url>] to target a non-prod env\n` +
+    `  logout             Remove the saved access token\n` +
+    `  whoami             Show the signed-in account\n\n` +
+    `Project\n` +
+    `  init [dir]         Scaffold a Vincentt XR app — no account needed, ever\n` +
+    `                       [--no-install] [--template <version>]\n` +
+    `                       [--from <owner>/<repo>@<tag>] Clone a gallery template\n` +
+    `                       and register it   [--name <s>] [--slug <s>]\n` +
+    `  create [name]      Register a project and reserve its address; scaffolds first\n` +
+    `                       if the folder is empty   [--name <s>] [--slug <s>]\n` +
+    `                       [--org <s>] [--preview] [--force] [--no-install]\n` +
+    `  link <project-id>  Link this folder to an existing project\n` +
+    `  unlink             Disconnect this folder from its project\n` +
+    `  projects           List the workspace's projects and their ids  [--json]\n` +
+    `                       [--org <s>] to list a workspace other than the active one\n\n` +
+    `Dev loop\n` +
+    `  publish            Upload the built dist; go live at <slug>.vincentt.app\n` +
+    `                       [--dist <path>] [--note <s>] [--yes]\n` +
+    `  preview            Serve the app at an https link a phone can open\n` +
+    `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n` +
+    `                       Re-running prints the live link; --restart mints a new one.\n\n` +
+    `Diagnostics (need a running preview)\n` +
+    `  logs [--errors]    Console logs from the device    [--json] [--tester <id>]\n` +
+    `  network            fetch/XHR requests              [--json] [--tester <id>]\n` +
+    `  trace              Performance samples             [--json] [--tester <id>]\n` +
+    `                       --tester t1 filters to one tester (one tab, across\n` +
+    `                       its refreshes). --viewer <label> filters to a single\n` +
+    `                       connection; one tab opens several.\n\n` +
+    `Asset library\n` +
+    `  assets search "<query>"   Find curated assets   [--kind prop|frame]\n` +
+    `                              [--render 3d-clay] [--palette sage] [--limit 20] [--json]\n` +
+    `  assets show <id> [<id>…]  Everything known about an asset            [--json]\n` +
+    `  assets add <id> [<id>…]   Print the URLs to reference from your source\n` +
+    `                              Writes nothing. [--download [--dir <path>] [--force]]\n` +
+    `                              [--json]\n` +
+    `                              Ids look like lib_7f3a2c67d4e5b6a7; search returns\n` +
+    `                              them. Reference only ids the tool returned.\n\n` +
+    // Help text is SOLICITED output, so an instruction would be permitted here —
+    // and it is still written as facts, because these exact words get quoted into
+    // a creator's own agent instructions, where they are unbidden by the time
+    // anything acts on them.
+    //
+    // Every line below is load-bearing. The exit codes are named HERE because a
+    // reader who has to look them up elsewhere guesses instead. "Blocking costs
+    // nothing while it waits" is the sentence that kills the poll-on-a-timer
+    // pattern — that pattern exists because a blocked command is assumed
+    // expensive and polling cheap, which is exactly backwards. "the same command
+    // may be run again immediately" teaches the re-park loop without naming a
+    // host, a shell, or any background mechanism, and "nothing is missed and
+    // nothing is re-read" forecloses an invented seen-set or a `--since` flag
+    // that does not exist.
+    //
+    // DELIBERATELY ABSENT: any product name; any shell idiom; any mention of a
+    // scheduled task EVEN TO FORBID ONE (naming a bad pattern is how a reader
+    // learns it exists); any "recommended for AI" framing.
+    `Reverse channel — feedback sent from the phone\n` +
+    `  feedback --wait     Block until feedback arrives, print every annotation\n` +
+    `                        waiting as one JSON object per line, then exit.\n` +
+    `                        [--timeout <seconds>, default 300]\n` +
+    `                        Exit 0  one or more annotations printed\n` +
+    `                        Exit 64 the window passed with nothing waiting\n` +
+    `                        Exit 65 the preview ended; nothing more can arrive\n` +
+    `                        Blocking costs nothing while it waits. On 64 the same\n` +
+    `                        command may be run again immediately; nothing is\n` +
+    `                        missed and nothing is re-read. On 65 a preview has to\n` +
+    `                        be running before there is anything to wait on.\n` +
+    `  feedback --watch    The same stream, printed as it arrives, without exiting.\n` +
+    `                        For a person watching a terminal.\n\n` +
+    `Servers\n` +
+    `  relay              Run the diagnostics/annotation relay\n\n` +
+    `Meta\n` +
+    `  version            CLI version, and the API this machine resolves to\n` +
+    `  dx                 Where this dev loop fought you  [--days <n>] [--json]\n` +
+    `                       Reads a local journal of your own runs. Local by default.\n` +
+    `                       --send reports the findings to the Vincentt team; it\n` +
+    `                       shows the exact payload and asks first. [--note <text>]\n` +
+    `  dx enable          Allow reports to be sent from this machine without asking.\n` +
+    `                       Asks you to confirm in your terminal. Stays on until you\n` +
+    `                       disable it, and is shown on \`vincentt dx\` and\n` +
+    `                       \`vincentt version\` while on.\n` +
+    `  dx disable         Turn that off again.\n\n` +
+    `Common options: --dir <path> (project dir, default cwd)\n` +
+    `                --allow-custom-api  honor a binding's apiUrl override\n`;

package/dist/cli/verb-surface.d.ts

@@ -0,0 +1,24 @@
+export declare const PINNED_VERBS: readonly ["version", "login", "logout", "whoami", "init", "create", "link", "unlink", "publish", "preview", "logs", "network", "trace", "feedback", "relay", "assets", "dx", "projects"];
+export type PinnedVerb = (typeof PINNED_VERBS)[number];
+export declare const VERB_HANDLERS: {
+    readonly version: true;
+    readonly login: true;
+    readonly logout: true;
+    readonly whoami: true;
+    readonly init: true;
+    readonly create: true;
+    readonly link: true;
+    readonly unlink: true;
+    readonly publish: true;
+    readonly preview: true;
+    readonly logs: true;
+    readonly network: true;
+    readonly trace: true;
+    readonly feedback: true;
+    readonly relay: true;
+    readonly assets: true;
+    readonly dx: true;
+    readonly projects: true;
+};
+export type DispatchVerb = keyof typeof VERB_HANDLERS;
+export declare function resolveVerb(cmd: string | undefined): DispatchVerb | undefined;

package/dist/cli/verb-surface.js

@@ -0,0 +1,49 @@
+// The accepted-verb surface, pinned. B-F3-8: a verb may be added or aliased,
+// never renamed or removed — grounding naming these verbs ships into creators'
+// repositories and is never read back, so a rename is unseeable, unwarnable and
+// unfixable. Append only; never edit or delete a line.
+// prettier-ignore
+export const PINNED_VERBS = [
+    "version", "login", "logout", "whoami",
+    "init", "create", "link", "unlink",
+    "publish", "preview",
+    "logs", "network", "trace",
+    "feedback", "relay", "assets", "dx",
+    // Appended: a read-only listing. Nothing above was renamed or removed, which
+    // is the whole of what B-F3-8 pins — an addition is always permitted.
+    "projects",
+];
+// The dispatch's verb set, as data. `main()` switches over this, so the two can
+// never disagree: a verb added to the CLI is a key added here, and QA-AHG-01
+// reads it as the converse arm of the pin.
+export const VERB_HANDLERS = {
+    version: true,
+    login: true,
+    logout: true,
+    whoami: true,
+    init: true,
+    create: true,
+    link: true,
+    unlink: true,
+    publish: true,
+    preview: true,
+    logs: true,
+    network: true,
+    trace: true,
+    feedback: true,
+    relay: true,
+    assets: true,
+    dx: true,
+    projects: true,
+};
+// Answers "is this a verb this CLI accepts" without running it. The
+// console-redirect strings are NOT accepted here: they reach their explanation
+// through the dispatch's default branch, and treating them as verbs would put
+// the console's vocabulary inside B-F3-8.
+export function resolveVerb(cmd) {
+    if (cmd === undefined)
+        return undefined;
+    return Object.prototype.hasOwnProperty.call(VERB_HANDLERS, cmd)
+        ? cmd
+        : undefined;
+}

package/dist/dx/clusters.d.ts

@@ -1,20 +1,3 @@
-/**
- * Friction detection over journal entries.
- *
- * Two cluster types, because the two halves of "DX" fail differently:
- *
- *  - `error` — the caller fought the tool and it pushed back. This is the
- *    classic retry loop (guessed a flag, got an error, tried again).
- *  - `repetition` — the caller ran the same thing repeatedly and it WORKED
- *    every time. No error is ever raised, so an error-keyed detector is blind
- *    to it, yet it is friction: the caller didn't know the first run had
- *    already given them what they needed. The reported case that motivated
- *    this file was exactly that shape — repeated `preview` runs, each one
- *    succeeding, each one minting a fresh link.
- *
- * Detection is deliberately loose. A false positive costs a line in a report a
- * human is already reading; a miss costs a DX gap nobody ever hears about.
- */
 import type { JournalEntry } from "./journal.js";
 export type ClusterKind = "error" | "repetition";
 export interface Cluster {

package/dist/dx/clusters.js

@@ -1,3 +1,47 @@
+/**
+ * Friction detection over journal entries.
+ *
+ * Two cluster types, because the two halves of "DX" fail differently:
+ *
+ *  - `error` — the caller fought the tool and it pushed back. This is the
+ *    classic retry loop (guessed a flag, got an error, tried again).
+ *  - `repetition` — the caller ran the same thing repeatedly and it WORKED
+ *    every time. No error is ever raised, so an error-keyed detector is blind
+ *    to it, yet it is friction: the caller didn't know the first run had
+ *    already given them what they needed. The reported case that motivated
+ *    this file was exactly that shape — repeated `preview` runs, each one
+ *    succeeding, each one minting a fresh link.
+ *
+ * Detection is deliberately loose. A false positive costs a line in a report a
+ * human is already reading; a miss costs a DX gap nobody ever hears about.
+ */
+import { verbOf } from "./skeleton.js";
+/**
+ * Non-zero exits a verb DEFINES as ordinary outcomes, not failures.
+ *
+ * `feedback --wait` exits 64 when its window elapsed with nothing waiting and 65
+ * when the preview ended. Both are facts about the channel, and the whole point
+ * of the verb is that it is re-run in a tight loop: a caller re-parks after every
+ * 64, hundreds of times a day. Counted as errors, those runs read as a
+ * fight-with-the-tool that never happened, and the nudge narrates the intended
+ * loop as friction — on stderr, which in this loop is a caller's own input.
+ *
+ * A verb's neutral exits are ITS OWN. Nothing here generalizes 64/65 across the
+ * CLI; another verb adding a non-zero-but-fine exit adds a row.
+ */
+const NEUTRAL_EXITS = {
+    feedback: new Set([64, 65]),
+};
+/**
+ * Verbs whose contract is "run it again". Repeating them is not a caller failing
+ * to get what they needed on the first try; it is the documented way to use them.
+ */
+const LOOPING_VERBS = new Set(["feedback"]);
+function isFailure(e) {
+    if (e.exit === 0)
+        return false;
+    return !NEUTRAL_EXITS[verbOf(e.skel.split(" "))]?.has(e.exit);
+}
 /** A repetition run must be at least this long to count as friction. */
 const REPETITION_MIN = 3;
 /**
@@ -23,8 +67,12 @@ export function findClusters(entries) {
         let j = i;
         while (j < entries.length && entries[j].skel === skel)
             run.push(entries[j++]);
-        const errors = run.filter((e) => e.exit !== 0).length;
+        const errors = run.filter(isFailure).length;
         const spanMs = span(run);
+        // A verb whose whole contract is "run it again" cannot be detected as
+        // friction by repetition — the repetition IS the design. Its error arm still
+        // applies: an exit 1 from it is a real fault and clusters normally.
+        const loops = LOOPING_VERBS.has(verbOf(skel.split(" ")));
         // A cluster needs at least two calls. A lone failure is usually the tool
         // working — a signed-out `whoami`, a typo'd verb — and reporting each one
         // buries the real findings under noise, which is the failure mode that
@@ -40,6 +88,7 @@ export function findClusters(entries) {
             });
         }
         else if (errors === 0 &&
+            !loops &&
             run.length >= REPETITION_MIN &&
             spanMs <= REPETITION_WINDOW_MS) {
             clusters.push({

package/dist/dx/skeleton.js

@@ -51,6 +51,7 @@ const KNOWN_FLAGS = new Set([
     "--editor",
     "--errors",
     "--force",
+    "--from",
     "--help",
     "--json",
     "--limit",

package/dist/lib/backend.d.ts

@@ -43,6 +43,17 @@ export declare class ProjectUnreachableError extends BackendError {
  * a creator's address is always a name they chose.
  */
 export declare function createProject(cfg: ResolvedConfig, orgSlug: string, name: string, slug?: string): Promise<CreatedProject>;
+/**
+ * List an org's projects. A READ, and the only new call `vincentt projects`
+ * makes — the same path `createProject` POSTs to, which is why the org is a slug
+ * here and not a bare id.
+ *
+ * The wire shape is `{projects: [...]}`, each member the same `projectView`
+ * `GET /projects/{id}` returns, so it goes through `parseProjectView` rather
+ * than a second reader: two parsers for one shape is how a contract break
+ * survives a green suite on one of them.
+ */
+export declare function listProjects(cfg: ResolvedConfig, orgSlug: string): Promise<ProjectView[]>;
 /** Read a project by id. Backs `link`; the org is derived server-side from the row. */
 export declare function getProject(cfg: ResolvedConfig, projectId: string): Promise<ProjectView>;
 export interface MintedTunnel {

package/dist/lib/backend.js

@@ -95,6 +95,29 @@ export async function createProject(cfg, orgSlug, name, slug) {
         liveUrl: p.liveUrl,
     };
 }
+/**
+ * List an org's projects. A READ, and the only new call `vincentt projects`
+ * makes — the same path `createProject` POSTs to, which is why the org is a slug
+ * here and not a bare id.
+ *
+ * The wire shape is `{projects: [...]}`, each member the same `projectView`
+ * `GET /projects/{id}` returns, so it goes through `parseProjectView` rather
+ * than a second reader: two parsers for one shape is how a contract break
+ * survives a green suite on one of them.
+ */
+export async function listProjects(cfg, orgSlug) {
+    const res = await authFetch(cfg, `/orgs/${encodeURIComponent(orgSlug)}/projects`);
+    if (!res.ok) {
+        const body = await errorBody(res);
+        throw new BackendError(res.status === 401
+            ? authFailureMessage("list projects failed", res.status, await safeText(res))
+            : (body.message ??
+                `list projects failed (${res.status}): ${await safeText(res)}`), res.status);
+    }
+    const raw = (await res.json());
+    const rows = Array.isArray(raw.projects) ? raw.projects : [];
+    return rows.map((p) => parseProjectView(p, "list projects"));
+}
 /** Read a project by id. Backs `link`; the org is derived server-side from the row. */
 export async function getProject(cfg, projectId) {
     const res = await authFetch(cfg, `/projects/${encodeURIComponent(projectId)}`);

package/dist/lib/classifyTarget.d.ts

@@ -0,0 +1,42 @@
+export type FolderCase = "vincentt-app" | "empty" | "occupied";
+/** Only the two fields the classifier reads, so a probe is trivial to fake. */
+export interface TargetStat {
+    isDirectory(): boolean;
+    isSymbolicLink(): boolean;
+}
+export interface ClassifyProbes {
+    looksLikeApp?: (dir: string) => Promise<boolean>;
+    /** lstat, NEVER stat — see rule 2. */
+    lstat?: (dir: string) => Promise<TargetStat>;
+    readdir?: (dir: string) => Promise<string[]>;
+}
+/**
+ * Which of the three cases the target directory is in.
+ *
+ * Four rules, each of which a caller depends on:
+ *
+ *  1. `ENOENT` is the ONLY error that means empty. `EACCES`, `EPERM`, `ENOTDIR`,
+ *     `ELOOP`, `ENAMETOOLONG` and anything unforeseen all return `occupied` —
+ *     "I could not establish that this is safe to write into" is a refusal.
+ *  2. `lstat`, never `stat`. A symlink is `occupied` whatever it points at;
+ *     `stat` follows it, which is how a scaffold writes outside the directory
+ *     the creator named.
+ *  3. A non-directory is `occupied`. A regular file at the path is not an empty
+ *     folder.
+ *  4. A `readdir` that throws after a successful `lstat` (a TOCTOU window, or a
+ *     permission change) is `occupied`. The unknown answer is never the writing
+ *     answer.
+ *
+ * `looksLikeApp` runs FIRST and unconditionally: order is the contract, because
+ * case 2 is defined by BEING a Vincentt app, not by what else is in the folder.
+ *
+ * Both IO probes are injected so every arm — including the error arms — is
+ * testable with no real filesystem. That matters for more than convenience: a
+ * mode-000 directory is a no-op as root, so a test staged on a real filesystem
+ * would pass for the wrong reason in CI.
+ *
+ * NOTE: the classifier answers a question at a MOMENT. The window between this
+ * answer and the write is closed by the writer's own guards (a non-recursive
+ * mkdir, and a realpath re-check), not here.
+ */
+export declare function classifyTarget(dir: string, probes?: ClassifyProbes): Promise<FolderCase>;

package/dist/lib/classifyTarget.js

@@ -0,0 +1,83 @@
+// The three-way folder classification `vincentt create` acts on, and it FAILS
+// CLOSED.
+//
+// `create` used to be a pure registration verb, so "is this a Vincentt app" was a
+// HINT: a wrong answer cost one advisory line. It now decides whether ~30 template
+// files get written, so a wrong answer is a silent write into a directory the
+// creator cares about. That is the hint-becomes-a-gate transition, and it is why
+// this is a security control with its own file rather than another export from
+// projects.ts.
+//
+// This deliberately does NOT call `isNonEmptyDir` (scaffold/index.ts). That
+// predicate catches EVERY error and returns false, which this design would read as
+// "empty". Four measured mis-answers it gives: a mode-000 directory holding files,
+// a symlink to an empty directory (the scaffold writes THROUGH the link, outside
+// the parent the creator named), a dangling symlink, and a regular file at the
+// path. Under `init` a false-empty reaches a confirm prompt a human sees; here it
+// reaches a silent write. `isNonEmptyDir` is left exactly as it is and keeps
+// serving `init`, where its error contract is correct: two predicates, two
+// contracts, each stated in terms of what its caller does with the answer.
+//
+// `needsScaffold` is not used either: it answers only "has a package.json", so a
+// stranger's non-Vincentt Node app lands in its scaffoldable arm.
+import { promises as fs } from "node:fs";
+import { looksLikeVincenttApp } from "./projects.js";
+/**
+ * Which of the three cases the target directory is in.
+ *
+ * Four rules, each of which a caller depends on:
+ *
+ *  1. `ENOENT` is the ONLY error that means empty. `EACCES`, `EPERM`, `ENOTDIR`,
+ *     `ELOOP`, `ENAMETOOLONG` and anything unforeseen all return `occupied` —
+ *     "I could not establish that this is safe to write into" is a refusal.
+ *  2. `lstat`, never `stat`. A symlink is `occupied` whatever it points at;
+ *     `stat` follows it, which is how a scaffold writes outside the directory
+ *     the creator named.
+ *  3. A non-directory is `occupied`. A regular file at the path is not an empty
+ *     folder.
+ *  4. A `readdir` that throws after a successful `lstat` (a TOCTOU window, or a
+ *     permission change) is `occupied`. The unknown answer is never the writing
+ *     answer.
+ *
+ * `looksLikeApp` runs FIRST and unconditionally: order is the contract, because
+ * case 2 is defined by BEING a Vincentt app, not by what else is in the folder.
+ *
+ * Both IO probes are injected so every arm — including the error arms — is
+ * testable with no real filesystem. That matters for more than convenience: a
+ * mode-000 directory is a no-op as root, so a test staged on a real filesystem
+ * would pass for the wrong reason in CI.
+ *
+ * NOTE: the classifier answers a question at a MOMENT. The window between this
+ * answer and the write is closed by the writer's own guards (a non-recursive
+ * mkdir, and a realpath re-check), not here.
+ */
+export async function classifyTarget(dir, probes = {}) {
+    const looksLikeApp = probes.looksLikeApp ?? looksLikeVincenttApp;
+    const lstat = probes.lstat ?? ((d) => fs.lstat(d));
+    const readdir = probes.readdir ?? ((d) => fs.readdir(d));
+    if (await looksLikeApp(dir))
+        return "vincentt-app";
+    try {
+        const st = await lstat(dir);
+        if (st.isSymbolicLink())
+            return "occupied";
+        if (!st.isDirectory())
+            return "occupied";
+    }
+    catch (err) {
+        // Read defensively rather than through a helper. `err.code` on a thrown
+        // string or null THROWS, and this catch sits inside a security control: an
+        // exception escaping here would propagate as an unhandled failure of the
+        // whole verb rather than as the refusal the contract promises.
+        const code = err?.code;
+        if (code === "ENOENT")
+            return "empty"; // `create <name>` creates it
+        return "occupied";
+    }
+    try {
+        return (await readdir(dir)).length === 0 ? "empty" : "occupied";
+    }
+    catch {
+        return "occupied";
+    }
+}

package/dist/lib/feedback.d.ts

@@ -2,14 +2,55 @@ import type { Annotation } from "@vincentt-xr/harness/events";
 export declare function cursorPath(cwd: string): string;
 /** Last-consumed annotation seq for this project (0 if none consumed yet). */
 export declare function readCursor(cwd: string): Promise<number>;
-/** Advance the cursor. Called ONLY after the annotation was handed off. */
+/**
+ * Advance the cursor. Called ONLY after the annotation was handed off.
+ *
+ * Temp file + same-directory rename, because `fs.writeFile` is not atomic and a
+ * kill mid-write is reachable on exactly the kill-mid-drain path this channel is
+ * designed around. A torn file reads as 0 under the strict parser, so the
+ * failure degrades to re-delivering the whole run — safe, but noisy and
+ * avoidable. Same directory keeps the rename on one filesystem, which is what
+ * makes it atomic.
+ */
 export declare function writeCursor(cwd: string, seq: number): Promise<void>;
 /**
- * Long-poll the relay for the next annotation after `after`. Resolves the
- * annotation, or null when the poll window elapsed with nothing new. Throws a
- * clear hint when no preview relay is running for this project.
+ * The three outcomes of a poll. `Annotation | null` could only express two, and
+ * a channel that has ENDED is not a channel that is merely quiet: a caller
+ * re-parks on `empty` and must not on `closed`.
+ */
+export type NextResult = {
+    kind: "annotation";
+    annotation: Annotation;
+}
+/** The window elapsed with nothing pending — re-parking is correct and free. */
+ | {
+    kind: "empty";
+}
+/** The preview session has ended; nothing more can arrive on this channel. */
+ | {
+    kind: "closed";
+    reason: ClosedReason;
+};
+/**
+ * Which of the two session-end routes fired. They are indistinguishable to the
+ * creator and print identically by default; the difference is triage detail
+ * surfaced under `--verbose`.
+ */
+export type ClosedReason = 
+/** The relay answered a parked long-poll 410 as it tore down. */
+"signalled"
+/** No relay is answering for this tree — a kill, a reboot, a stale marker. */
+ | "unreachable";
+/**
+ * Long-poll the relay for the next annotation after `after`.
+ *
+ * A missing marker and an unreachable relay both resolve `closed` rather than
+ * throwing: "no preview is running for this tree" is the same fact the graceful
+ * 410 carries, and the caller's correct response to both is identical. Throwing
+ * would reach the top-level catch and exit 1 — a fault code for an ordinary,
+ * expected end.
  */
 export declare function fetchNext(cwd: string, opts: {
     after: number;
     timeoutMs: number;
-}): Promise<Annotation | null>;
+}): Promise<NextResult>;

package/dist/lib/feedback.js

@@ -1,12 +1,29 @@
-// The agent-agnostic reverse-channel consumer behind `vincentt feedback --wait`.
-// Long-polls the running preview's relay for the next annotation after a locally
-// persisted cursor. Delivery is at-least-once: the caller advances the cursor only
-// after it has successfully handed the annotation off (printed it), so a crash
-// before that re-delivers on the next call.
+// The host-neutral reverse-channel consumer behind `vincentt feedback`. Long-polls
+// the running preview's relay for the next annotation after a locally persisted
+// cursor.
+//
+// Delivery is at-least-once, and every rule in this file exists to keep the error
+// on that side: the caller advances the cursor only after the annotation's write
+// has COMPLETED (see the drain in cli/index.ts), the cursor parser can only ever
+// read LOW, and the cursor write is atomic. A cursor that lags re-delivers; a
+// cursor that runs ahead skips silently, which is the one failure the channel
+// forbids.
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { readRelayInfo, relayInfoDir } from "./relayInfo.js";
+import { isProcessAlive, isRelayResponding, readRelayInfo, relayInfoDir, } from "./relayInfo.js";
 const CURSOR_FILE = ".vincentt/annotations/offset";
+/**
+ * A cursor that reads too LOW re-delivers, which is the accepted cost of
+ * at-least-once. A cursor that reads too HIGH silently SKIPS, which is the
+ * failure this channel forbids. So the parser is allowed to err only in one
+ * direction: anything that is not a bare non-negative integer is 0.
+ *
+ * `Number(raw.trim()) || 0` erred the forbidden way — `1e3` is 1000 (a thousand
+ * annotations skipped with no error anywhere), `-5` is -5, `0x10` is 16. And §9
+ * invites the creator to inspect and repair this file by hand, so a hand-edited
+ * value is foreseeable input rather than a hypothetical one.
+ */
+const CURSOR_RE = /^\d+$/;
 export function cursorPath(cwd) {
     return path.join(cwd, CURSOR_FILE);
 }
@@ -23,7 +40,12 @@ async function treeCursorPath(cwd) {
 export async function readCursor(cwd) {
     try {
         const raw = await fs.readFile(await treeCursorPath(cwd), "utf8");
-        return Number(raw.trim()) || 0;
+        const trimmed = raw.trim();
+        if (!CURSOR_RE.test(trimmed))
+            return 0;
+        const n = Number(trimmed);
+        // Beyond MAX_SAFE_INTEGER, Number() rounds — and rounding UP would skip.
+        return Number.isSafeInteger(n) ? n : 0;
     }
     catch (err) {
         if (err.code === "ENOENT")
@@ -31,22 +53,42 @@ export async function readCursor(cwd) {
         throw err;
     }
 }
-/** Advance the cursor. Called ONLY after the annotation was handed off. */
+/**
+ * Advance the cursor. Called ONLY after the annotation was handed off.
+ *
+ * Temp file + same-directory rename, because `fs.writeFile` is not atomic and a
+ * kill mid-write is reachable on exactly the kill-mid-drain path this channel is
+ * designed around. A torn file reads as 0 under the strict parser, so the
+ * failure degrades to re-delivering the whole run — safe, but noisy and
+ * avoidable. Same directory keeps the rename on one filesystem, which is what
+ * makes it atomic.
+ */
 export async function writeCursor(cwd, seq) {
     const p = await treeCursorPath(cwd);
     await fs.mkdir(path.dirname(p), { recursive: true });
-    await fs.writeFile(p, `${seq}\n`, "utf8");
+    const tmp = `${p}.${process.pid}.tmp`;
+    await fs.writeFile(tmp, `${seq}\n`, "utf8");
+    try {
+        await fs.rename(tmp, p);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true });
+        throw err;
+    }
 }
 /**
- * Long-poll the relay for the next annotation after `after`. Resolves the
- * annotation, or null when the poll window elapsed with nothing new. Throws a
- * clear hint when no preview relay is running for this project.
+ * Long-poll the relay for the next annotation after `after`.
+ *
+ * A missing marker and an unreachable relay both resolve `closed` rather than
+ * throwing: "no preview is running for this tree" is the same fact the graceful
+ * 410 carries, and the caller's correct response to both is identical. Throwing
+ * would reach the top-level catch and exit 1 — a fault code for an ordinary,
+ * expected end.
  */
 export async function fetchNext(cwd, opts) {
     const info = await readRelayInfo(cwd);
-    if (!info) {
-        throw new Error("No running preview for this project — run `vincentt preview` first.");
-    }
+    if (!info)
+        return { kind: "closed", reason: "unreachable" };
     const base = `http://localhost:${info.relayPort}`;
     const u = new URL(`${info.harnessPath}/feedback/next`, base);
     u.searchParams.set("project", cwd);
@@ -56,12 +98,27 @@ export async function fetchNext(cwd, opts) {
     try {
         res = await fetch(u);
     }
-    catch (err) {
-        throw new Error(`Could not reach the preview relay on :${info.relayPort} (${err.message}). Is the preview still running?`);
+    catch {
+        // The socket died under us. The pid gate + relay-identity probe is what
+        // separates "the preview ended" from "the request failed but a relay is
+        // still there" — only the latter is a fault worth an exit 1.
+        if (await relayGone(info.pid, info.relayPort)) {
+            return { kind: "closed", reason: "unreachable" };
+        }
+        throw new Error(`Could not reach the preview relay on :${info.relayPort}. The relay is answering, so this is not a session end.`);
     }
     if (res.status === 204)
-        return null;
+        return { kind: "empty" };
+    // BEFORE the not-ok throw: 410 is not ok, and a graceful session end must not
+    // become a fault.
+    if (res.status === 410)
+        return { kind: "closed", reason: "signalled" };
     if (!res.ok)
         throw new Error(`relay feedback/next returned ${res.status}`);
-    return (await res.json());
+    return { kind: "annotation", annotation: (await res.json()) };
+}
+async function relayGone(pid, port) {
+    if (pid !== undefined && !isProcessAlive(pid))
+        return true;
+    return !(await isRelayResponding(port));
 }