@vincentt-xr/cli 0.9.0 → 0.11.0

package/dist/lib/sourceRefCopy.js

@@ -60,6 +60,42 @@ export function printSourceRefFailure(print, failure, ctx) {
     print("");
     print("  Nothing was written.");
 }
+/**
+ * `--template` / `--from` on `create` — the parser refusal, and it is a security
+ * control rather than a scope note. The basis for installing dependencies on the
+ * unauthenticated scaffold path is that `create` can only ever clone our own
+ * hardcoded template at a release-gated ref; this screen is what makes that
+ * structurally true rather than conventional.
+ *
+ * "on `create`" is REQUIRED on line 1 and is not required by the shipped
+ * `printFlagConflict` precedent: `--template` really does exist, on `init`, and the
+ * remedy three lines below depends on that being true. An unqualified claim is one
+ * a creator disproves in one command.
+ *
+ * The creator's own typed arguments are carried through verbatim, so all three
+ * remedy lines are copy-pasteable with no placeholder to guess.
+ */
+export function printCreateSourceFlagRefusal(print, flagName, ctx) {
+    const dir = ctx.dir;
+    print(`✗ There's no \`${flagName}\` option on \`create\`.`);
+    print("");
+    if (flagName === "--from") {
+        print("  `create` scaffolds the standard starter and nothing else. To start from");
+        print("  a gallery template, scaffold first and register after:");
+        print("");
+        print(`  vincentt init ${dir} --from ${ctx.value ?? "owner/repo@tag"}`);
+    }
+    else {
+        print("  `create` scaffolds the standard starter and nothing else. To choose a");
+        print("  template or a version, scaffold first and register after:");
+        print("");
+        print(`  vincentt init ${dir} --template ${ctx.value ?? "<version>"}`);
+    }
+    print(`  cd ${dir}`);
+    print("  vincentt create");
+    print("");
+    print("  Nothing was written.");
+}
 /** `--from` with `--template`, or with an install-enabling flag. */
 export function printFlagConflict(print, conflict, ctx) {
     const [a, b] = conflict.flags;

package/dist/preview/command.d.ts

@@ -65,6 +65,17 @@ export declare class PreviewUi {
     events(evs: DiagEvent[], tags: EventTags, opts?: {
         attribute?: boolean;
     }): void;
+    /**
+     * An annotation arrived from the phone. One line per annotation — it is an
+     * event, not a condition, so the once-per-stretch rule that governs advisories
+     * does not apply.
+     *
+     * An un-attributed send is dropped from the terminal for the same reason an
+     * un-attributed event is: column one is the tester, and inventing a
+     * placeholder would read as a real one. The annotation itself is still stored
+     * and still handed over by `vincentt feedback`.
+     */
+    annotation(tags: EventTags): void;
     /**
      * L18. Recovery is announced by the 200 that follows and by NOTHING else — a
      * "recovered!" line would be a second interruption for a non-event.

package/dist/preview/command.js

@@ -12,7 +12,7 @@
 // file works, and an agent reading the transcript gets the same information a
 // human does.
 import * as copy from "./copy.js";
-import { PerfThrottle, palette, renderEvent, uaLabel } from "./stream.js";
+import { PerfThrottle, palette, renderAnnotation, renderEvent, uaLabel, } from "./stream.js";
 import { ViewerRoster } from "./viewers.js";
 import { MAX_TESTERS } from "../relay/testers.js";
 /**
@@ -151,6 +151,24 @@ export class PreviewUi {
                 this.line(`  ${rendered}`);
         }
     }
+    /**
+     * An annotation arrived from the phone. One line per annotation — it is an
+     * event, not a condition, so the once-per-stretch rule that governs advisories
+     * does not apply.
+     *
+     * An un-attributed send is dropped from the terminal for the same reason an
+     * un-attributed event is: column one is the tester, and inventing a
+     * placeholder would read as a real one. The annotation itself is still stored
+     * and still handed over by `vincentt feedback`.
+     */
+    annotation(tags) {
+        const { tester } = tags;
+        if (tester === undefined)
+            return;
+        if (this.deps.filterTester !== undefined && tester !== this.deps.filterTester)
+            return;
+        this.line(`  ${renderAnnotation(tester)}`);
+    }
     // ---- advisories -----------------------------------------------------------
     /**
      * L18. Recovery is announced by the 200 that follows and by NOTHING else — a

package/dist/preview/copy.d.ts

@@ -5,6 +5,13 @@ export interface StartBlockInput {
     /** The forward target, printed BEFORE the URL so the 502 advisory matches it. */
     targetUrl: string;
     url: string;
+    /**
+     * The project's console page, or undefined for a folder with no binding. An
+     * unlinked folder gets NO console line rather than a guessed one — the same rule
+     * `consoleVerbCommand` follows, and for the same reason: a link to the wrong
+     * project is worse than no link.
+     */
+    consoleUrl?: string;
     /** Pre-rendered QR rows, or undefined for non-TTY / piped / --no-qr. */
     qr?: string[];
     expiresInHours: number;
@@ -92,9 +99,18 @@ export declare function stopped(ranMs: number, totalConnections: number): string
  *
  * The claim is exactly what the wire supports: `stopped` is produced by one
  * route, authorized by the compound key {_id, userId}, so the actor is ALWAYS
- * the same account as the reader. Never a teammate, never an admin. It does not
- * say WHICH window, because another terminal, another machine and a future
- * console control are all the same 410.
+ * the same account as the reader. Never a teammate, never an admin.
+ *
+ * IT NAMES NO SURFACE, and that is the whole design of this screen. `endReason`
+ * carries ONE value for every actor on that route — this CLI's own stop, another
+ * terminal, another machine, the console's Stop control, and any surface added
+ * later. The API does not learn which one called and must not: deriving it would
+ * mean guessing a surface from a credential kind (a PAT-driven script is not "a
+ * terminal") and reporting the guess to the creator as fact. That is the
+ * over-claim class that produced the abandoned→hard_max defect.
+ *
+ * So the headline states only the event, and the second line describes the actor
+ * exactly as far as the compound key supports: the same account, not this window.
  *
  * `✓`, not `✗`: someone with the authority to stop it stopped it.
  */

package/dist/preview/copy.js

@@ -38,7 +38,14 @@ export function startBlock(i) {
     if (i.qr && i.qr.length > 0) {
         out.push(...i.qr.map((row) => `    ${row}`), "");
     }
-    out.push("    Scan it, or open the link on any phone. No sign-in needed on the phone.", `    Expires in ${i.expiresInHours}h · Ctrl-C to stop`, "", "  Waiting for a device…", "");
+    out.push("    Scan it, or open the link on any phone. No sign-in needed on the phone.", `    Expires in ${i.expiresInHours}h · Ctrl-C to stop`, "");
+    // BELOW the phone URL and its instruction, never above. The phone address is the
+    // line the creator is waiting on; a second URL printed first is a second thing to
+    // read before the one that matters. Dropped entirely when the folder is unlinked.
+    if (i.consoleUrl) {
+        out.push("  In the console:", "", `    ${i.consoleUrl}`, "");
+    }
+    out.push("  Waiting for a device…", "");
     return out;
 }
 /**
@@ -198,16 +205,25 @@ export function stopped(ranMs, totalConnections) {
  *
  * The claim is exactly what the wire supports: `stopped` is produced by one
  * route, authorized by the compound key {_id, userId}, so the actor is ALWAYS
- * the same account as the reader. Never a teammate, never an admin. It does not
- * say WHICH window, because another terminal, another machine and a future
- * console control are all the same 410.
+ * the same account as the reader. Never a teammate, never an admin.
+ *
+ * IT NAMES NO SURFACE, and that is the whole design of this screen. `endReason`
+ * carries ONE value for every actor on that route — this CLI's own stop, another
+ * terminal, another machine, the console's Stop control, and any surface added
+ * later. The API does not learn which one called and must not: deriving it would
+ * mean guessing a surface from a credential kind (a PAT-driven script is not "a
+ * terminal") and reporting the guess to the creator as fact. That is the
+ * over-claim class that produced the abandoned→hard_max defect.
+ *
+ * So the headline states only the event, and the second line describes the actor
+ * exactly as far as the compound key supports: the same account, not this window.
  *
  * `✓`, not `✗`: someone with the authority to stop it stopped it.
  */
 export function stoppedElsewhere() {
     return [
         "",
-        "✓ Preview stopped from another terminal. The link no longer works.",
+        "✓ Preview stopped. The link no longer works.",
         "",
         "  It was stopped on your account, not by this window. Nothing is wrong here.",
         "",

package/dist/preview/runner.d.ts

@@ -96,6 +96,12 @@ export interface StartPreviewOptions {
      * line; the connection's events are still stored, just un-attributed.
      */
     onCapReached?: () => void;
+    /**
+     * An annotation arrived from the phone, tagged with the tester that sent it.
+     * Carries nothing about its content — the terminal states arrival, and the
+     * record itself goes to whoever is consuming the reverse channel.
+     */
+    onAnnotation?: (tags: EventTags) => void;
     /** The tunnel's own state — what drives the L19 reconnect advisories. */
     onTunnelState?: (state: TunnelState) => void;
     /** The creator's dev server is not answering (L18). */

package/dist/preview/runner.js

@@ -83,6 +83,7 @@ export async function startPreview(opts) {
             onEvents: opts.onEvents,
             onAttribute: opts.onAttribute,
             onCapReached: opts.onCapReached,
+            onAnnotation: opts.onAnnotation,
         });
         front = createServer((req, res) => {
             const toRelay = req.url?.startsWith(harnessPath) === true;

package/dist/preview/stream.d.ts

@@ -34,6 +34,17 @@ export declare function renderNetworkWithSize(label: string, e: NetworkEvent, by
 export declare function displayPath(url: string): string;
 export declare function renderLog(label: string, e: LogEvent, p: Palette): string;
 export declare function renderTrace(label: string, e: TraceEvent): string;
+/**
+ * An annotation arrived from the phone. Same column grammar as every other
+ * stream line — tester in column one, kind in the status column, then the fact.
+ *
+ * It states THAT one arrived and nothing else: no message, no id, no screenshot
+ * path, no count, and no command to run. The message is viewer-authored and
+ * hostile, and this line lands in the creator's scrollback and, pasted, in their
+ * agent's context. It is an event and not a condition, so one line per
+ * annotation is correct here where an advisory would print once per stretch.
+ */
+export declare function renderAnnotation(label: string): string;
 /** The dispatcher. Returns null for an event kind the terminal does not print. */
 export declare function renderEvent(label: string, e: DiagEvent, p: Palette): string | null;
 /**

package/dist/preview/stream.js

@@ -134,6 +134,19 @@ export function renderTrace(label, e) {
     const fps = e.fps.toFixed(0);
     return `${labelCol(label)}${padEnd("perf", STATUS_COL)} ${fps} fps · ${e.longTaskCount} long tasks · ${e.longestTaskMs}ms peak`;
 }
+/**
+ * An annotation arrived from the phone. Same column grammar as every other
+ * stream line — tester in column one, kind in the status column, then the fact.
+ *
+ * It states THAT one arrived and nothing else: no message, no id, no screenshot
+ * path, no count, and no command to run. The message is viewer-authored and
+ * hostile, and this line lands in the creator's scrollback and, pasted, in their
+ * agent's context. It is an event and not a condition, so one line per
+ * annotation is correct here where an advisory would print once per stretch.
+ */
+export function renderAnnotation(label) {
+    return `${labelCol(label)}${padEnd("feedback", STATUS_COL)}  annotation received`;
+}
 /** The dispatcher. Returns null for an event kind the terminal does not print. */
 export function renderEvent(label, e, p) {
     if (e.kind === "network")

package/dist/relay/annotations.d.ts

@@ -1,6 +1,19 @@
 import type { Annotation, AnnotationInput } from "@vincentt-xr/harness/events";
 export declare const ANNOTATIONS_DIR = ".vincentt/annotations";
 export declare function annotationsDir(projectDir: string): string;
+/**
+ * What ended a long-poll. A timeout and a teardown used to be the same value
+ * (`null`), which made a dead session byte-identical to a quiet one on the wire
+ * — so a parked consumer waited forever on a channel that could never speak.
+ */
+export type NextOutcome = {
+    kind: "annotation";
+    annotation: Annotation;
+} | {
+    kind: "timeout";
+} | {
+    kind: "closed";
+};
 export declare class AnnotationStore {
     private readonly projectDir;
     private readonly dir;
@@ -8,6 +21,7 @@ export declare class AnnotationStore {
     private seq;
     private waiters;
     private loaded;
+    private closed;
     constructor(projectDir: string, dir?: string);
     /** Load persisted annotations so seq continues across preview restarts. */
     init(): Promise<void>;
@@ -18,13 +32,23 @@ export declare class AnnotationStore {
     }): Promise<Annotation>;
     /** The first annotation with seq greater than `after`, if one is already held. */
     peekAfter(after: number): Annotation | undefined;
+    /** Every held annotation with seq greater than `after`, in seq order. */
+    listAfter(after: number): Annotation[];
     /**
      * Long-poll: resolve with the first annotation whose seq is greater than
-     * `after`, either immediately (already held) or as soon as one arrives. Resolves
-     * null if none arrives within `timeoutMs`.
+     * `after`, either immediately (already held) or as soon as one arrives.
+     * Resolves `timeout` if none arrives within `timeoutMs`, and `closed` if the
+     * store tore down while the caller was parked.
+     *
+     * `timeoutMs` of 0 means "answer now": nothing held resolves `timeout` on the
+     * next tick rather than parking.
      */
-    nextAfter(after: number, timeoutMs: number): Promise<Annotation | null>;
+    nextAfter(after: number, timeoutMs: number): Promise<NextOutcome>;
     private wake;
-    /** Release any parked waiters on teardown so nothing hangs. */
+    /**
+     * Release any parked waiters on teardown, telling them the channel ENDED. A
+     * teardown that resolved them the same way a timeout does left a parked
+     * consumer unable to tell a dead session from a quiet one.
+     */
     close(): void;
 }

package/dist/relay/annotations.js

@@ -29,6 +29,7 @@ export class AnnotationStore {
     seq = 0;
     waiters = [];
     loaded = false;
+    closed = false;
     constructor(projectDir, dir = annotationsDir(projectDir)) {
         this.projectDir = projectDir;
         this.dir = dir;
@@ -80,22 +81,32 @@ export class AnnotationStore {
     peekAfter(after) {
         return this.items.find((a) => a.seq > after);
     }
+    /** Every held annotation with seq greater than `after`, in seq order. */
+    listAfter(after) {
+        return this.items.filter((a) => a.seq > after);
+    }
     /**
      * Long-poll: resolve with the first annotation whose seq is greater than
-     * `after`, either immediately (already held) or as soon as one arrives. Resolves
-     * null if none arrives within `timeoutMs`.
+     * `after`, either immediately (already held) or as soon as one arrives.
+     * Resolves `timeout` if none arrives within `timeoutMs`, and `closed` if the
+     * store tore down while the caller was parked.
+     *
+     * `timeoutMs` of 0 means "answer now": nothing held resolves `timeout` on the
+     * next tick rather than parking.
      */
     nextAfter(after, timeoutMs) {
         const held = this.peekAfter(after);
         if (held)
-            return Promise.resolve(held);
+            return Promise.resolve({ kind: "annotation", annotation: held });
+        if (this.closed)
+            return Promise.resolve({ kind: "closed" });
         return new Promise((resolve) => {
             const waiter = {
                 after,
                 resolve,
                 timer: setTimeout(() => {
                     this.waiters = this.waiters.filter((w) => w !== waiter);
-                    resolve(null);
+                    resolve({ kind: "timeout" });
                 }, timeoutMs),
             };
             waiter.timer.unref?.();
@@ -107,7 +118,7 @@ export class AnnotationStore {
         for (const w of this.waiters) {
             if (a.seq > w.after) {
                 clearTimeout(w.timer);
-                w.resolve(a);
+                w.resolve({ kind: "annotation", annotation: a });
             }
             else {
                 remaining.push(w);
@@ -115,11 +126,16 @@ export class AnnotationStore {
         }
         this.waiters = remaining;
     }
-    /** Release any parked waiters on teardown so nothing hangs. */
+    /**
+     * Release any parked waiters on teardown, telling them the channel ENDED. A
+     * teardown that resolved them the same way a timeout does left a parked
+     * consumer unable to tell a dead session from a quiet one.
+     */
     close() {
+        this.closed = true;
         for (const w of this.waiters) {
             clearTimeout(w.timer);
-            w.resolve(null);
+            w.resolve({ kind: "closed" });
         }
         this.waiters = [];
     }

package/dist/relay/qa.f12.fixtures.d.ts

@@ -0,0 +1,154 @@
+import { type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+import { AnnotationStore } from "./annotations.js";
+import { type RelayHandle } from "./server.js";
+/** src/relay → packages/cli. The built entry is the one a creator runs. */
+export declare const CLI_ENTRY: string;
+export interface F12Tree {
+    dir: string;
+    cleanup: () => Promise<void>;
+}
+/**
+ * A mkdtemp project root with `.vincentt/`, a written relay.json, and a project
+ * BINDING.
+ *
+ * The binding is what makes the tree a tree: `relayInfoDir` resolves through
+ * `locateProjectBinding`, which walks up from the cwd looking for
+ * `.vincentt/project.json`. Without it a subdirectory of the project is a
+ * DIFFERENT tree with its own cursor at 0 — which is precisely the
+ * re-deliver-everything bug feedback.ts's header comment describes, so a fixture
+ * that omitted the binding could not express the tree-anchoring case at all.
+ */
+export declare function F12_TREE(opts?: {
+    relayPort: number;
+    pid?: number;
+    harnessPath?: string;
+}): Promise<F12Tree>;
+/** A fresh store over the tree, nothing on disk. readCursor ⇒ 0. */
+export declare function F12_STORE_EMPTY(projectDir: string): AnnotationStore;
+/** A valid 1×1 PNG data URL — the real screenshot shape `add()` decodes. */
+export declare const PNG_1X1: string;
+/**
+ * F12_STORE_EMPTY plus three real `add()` calls ⇒ seq 1,2,3. `add()` is the same
+ * function the real POST path calls, so driving it exercises the real delivery
+ * path from one function inward.
+ */
+export declare function F12_STORE_BATCH_3(projectDir: string, messages?: readonly string[]): Promise<AnnotationStore>;
+export interface F12Relay {
+    handle: RelayHandle;
+    port: number;
+    /** Everything the relay wrote to its `onLog` seam. */
+    logs: string[];
+    /**
+     * The `onAnnotation` notifications, one per accepted POST, carrying only the
+     * resolved tester. This is the seam `preview/runner.ts` wires to the preview
+     * terminal's `annotation received` line (Flow C8) — it is NOT `onLog`, so a
+     * case that watched `logs` for arrivals would see none and wrongly conclude
+     * the line was never wired.
+     */
+    arrivals: Array<{
+        tester?: string;
+        viewer?: string;
+    }>;
+    /** The rendered Flow C8 stream lines, as the preview terminal would print them. */
+    streamLines: string[];
+    close: () => Promise<void>;
+}
+/**
+ * A real relay on a free port with an injectable store. Cases drive it through
+ * REAL HTTP rather than by calling handlers directly: the exit contract is
+ * defined in terms of status codes on a wire, and a handler-level call would not
+ * observe a 410 the socket never sent.
+ */
+export declare function F12_RELAY_LIVE(projectDir: string, store?: AnnotationStore): Promise<F12Relay>;
+/**
+ * A tree whose relay.json names a port nothing listens on and a pid that is NOT
+ * alive. The input to the liveness probe's dead arm.
+ */
+export declare function F12_RELAY_DEAD(): Promise<F12Tree>;
+/** Write `.vincentt/annotations/offset` = n. n===null writes nothing (absent). */
+export declare function F12_CURSOR_AT(tree: string, n: number | null): Promise<void>;
+/** Raw cursor bytes, or null when the file is absent. */
+export declare function readCursorRaw(tree: string): Promise<string | null>;
+export interface HostileRow {
+    row: string;
+    payload: string;
+    attacks: string;
+}
+export declare const F12_HOSTILE_MESSAGES: readonly HostileRow[];
+export interface F12TwoTrees {
+    a: {
+        tree: F12Tree;
+        relay: F12Relay;
+        store: AnnotationStore;
+    };
+    b: {
+        tree: F12Tree;
+        relay: F12Relay;
+        store: AnnotationStore;
+    };
+    cleanup: () => Promise<void>;
+}
+/**
+ * Two trees, two relays on two ports, two stores, two cursors. The
+ * PROJECT-isolation fixture (QA-F12-G7). Deliberately NOT a tenant fixture —
+ * these are one creator's two checkouts, the only multiplicity f12 has.
+ */
+export declare function F12_TWO_TREES(): Promise<F12TwoTrees>;
+/** stdin ignored, stdout + stderr on their own pipes. */
+type PipedChild = ChildProcessByStdio<null, Readable, Readable>;
+export interface CliRun {
+    child: PipedChild;
+    /** Raw stdout BYTES — never merged with stderr. */
+    stdout: () => Buffer;
+    /** Raw stderr BYTES — never merged with stdout. */
+    stderr: () => Buffer;
+    out: () => string;
+    err: () => string;
+    /** Resolves with the OS-reported exit status. */
+    exit: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    exited: () => boolean;
+    kill: (sig?: NodeJS.Signals) => void;
+}
+/**
+ * Spawn the BUILT CLI with stdout/stderr on SEPARATE pipes and expose the real
+ * exit status. `stdio: pipe` is load-bearing twice over: it keeps the two streams
+ * distinguishable (QA-F12-C1) and it makes stdout a PIPE, which is the
+ * asynchronous-write case the cursor invariant exists for (§3.1).
+ */
+export declare function runCli(args: readonly string[], opts?: {
+    cwd: string;
+    env?: Record<string, string | undefined>;
+}): CliRun;
+/** Spawn, wait for exit, return everything. */
+export declare function runCliToEnd(args: readonly string[], opts: {
+    cwd: string;
+    env?: Record<string, string | undefined>;
+}): Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: Buffer;
+    stderr: Buffer;
+    out: string;
+    err: string;
+}>;
+/**
+ * A throwaway HOME, so the dx journal (and therefore the dx nudge) starts empty.
+ *
+ * The nudge is journal-state-dependent and fires on the Nth recent run, so two
+ * otherwise-identical invocations differ in stderr purely because one came later.
+ * Any case comparing two runs byte-for-byte must isolate this or it is asserting
+ * on run order rather than on the property it names.
+ */
+export declare function freshHome(): Promise<string>;
+export declare function sleep(ms: number): Promise<void>;
+/** Wait until `cond()` or the deadline. Returns whether it became true. */
+export declare function until(cond: () => boolean, timeoutMs?: number, stepMs?: number): Promise<boolean>;
+/** Non-empty `\n`-split fragments of a raw stdout capture. */
+export declare function ndjsonLines(stdout: Buffer): string[];
+/** The Annotation key set §4.2 pins on stdout. */
+export declare const ANNOTATION_KEYS: readonly ["id", "seq", "createdAt", "projectDir", "message", "screenshotPath", "spec", "sessionId"];
+export {};