@vincentt-xr/cli 0.8.0 → 0.10.0

package/dist/relay/server.js

@@ -5,17 +5,17 @@
 // store.ts, the reverse-channel store in annotations.ts. One relay per preview run.
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
-import path from "node:path";
 import { WebSocketServer } from "ws";
 import { EventStore } from "./store.js";
 import { TesterRegistry, isTesterId } from "./testers.js";
-import { AnnotationStore, annotationsDir } from "./annotations.js";
-import { claudeCodeInjector, createDispatcher, pasteInjector, } from "./injectors.js";
+import { AnnotationStore } from "./annotations.js";
 import { VIEWER_LABEL_RE, VIEWER_STAMP_HEADER } from "@vincentt-xr/harness/tunnel";
 /** Cap an annotation POST body so a bad/huge upload can't exhaust memory. */
 const MAX_ANNOTATION_BYTES = 25 * 1024 * 1024;
 /** Clamp the long-poll hold so a request can't park forever. */
 const MAX_FEEDBACK_TIMEOUT_MS = 600_000;
+/** The hold a request that names no timeout gets. */
+const DEFAULT_FEEDBACK_TIMEOUT_MS = 300_000;
 export function startRelay(opts = {}) {
     const port = opts.port ?? 7331;
     const wsPath = opts.path ?? "/__harness";
@@ -24,27 +24,37 @@ export function startRelay(opts = {}) {
     const log = opts.onLog ?? (() => undefined);
     const makeId = opts.makeId ?? (() => randomBytes(3).toString("hex"));
     // Reverse channel is enabled when we know which project to bind annotations to.
-    let annotations;
-    let dispatcher;
-    if (opts.projectDir || opts.annotationStore) {
-        annotations = opts.annotationStore ?? new AnnotationStore(opts.projectDir);
-        const queuePath = path.join(opts.projectDir ? annotationsDir(opts.projectDir) : ".", "queue.ndjson");
-        dispatcher =
-            opts.dispatcher ??
-                createDispatcher([
-                    claudeCodeInjector(queuePath),
-                    pasteInjector((p) => log(`annotation ready to paste:\n${p}`)),
-                ], log);
-    }
+    const annotations = opts.annotationStore ??
+        (opts.projectDir === undefined ? undefined : new AnnotationStore(opts.projectDir));
+    // The tester a LIVE socket resolved to. A WeakMap and not a field on the
+    // store: this must not outlive the socket, which is the entire difference
+    // between it and `testersSeen`. Entries vanish with the connection.
+    const socketTester = new WeakMap();
+    const presence = () => {
+        const open = new Set();
+        let connections = 0;
+        for (const ws of wss.clients) {
+            // OPEN only. A socket mid-close is still in the set for a tick, and
+            // counting it would print a viewer who is already gone.
+            if (ws.readyState !== ws.OPEN)
+                continue;
+            connections += 1;
+            const t = socketTester.get(ws);
+            if (t !== undefined)
+                open.add(t);
+        }
+        return { connections, testers: open.size };
+    };
     const http = createServer((req, res) => handleHttp(req, res, {
         store,
         annotations,
-        dispatcher,
         testers,
         wsPath,
         makeId,
         log,
+        presence,
         onCapReached: opts.onCapReached,
+        onAnnotation: opts.onAnnotation,
     }));
     const wss = new WebSocketServer({ server: http, path: wsPath });
     wss.on("connection", (ws, req) => {
@@ -74,6 +84,12 @@ export function startRelay(opts = {}) {
             resolved = true;
             const attribution = testers.attribute(sessionId);
             tester = attribution.tester;
+            // Recorded against the SOCKET so the live presence read can see it: the
+            // tester above is a closure local that no other scope can reach, and the
+            // registry is ever-seen. A key that missed the grammar records nothing and
+            // the connection counts as a connection with no tester.
+            if (tester !== undefined)
+                socketTester.set(ws, tester);
             if (attribution.warnCapReached)
                 opts.onCapReached?.();
         };
@@ -147,9 +163,19 @@ function handleQuery(req, res, url, ctx) {
     readQuery(req, url)
         .then((q) => {
         const result = ctx.store.query(q);
+        // ONE BRANCH on the existing route, and the envelope is unchanged.
+        // Returning a RelayResult rather than a bespoke `{count}` keeps the reply
+        // its own liveness-and-identity proof: `isRelayResponding` recognises a
+        // Vincentt relay by `events` being an array and `latestSeq` a number, so a
+        // stranger on a reused port answers something else and the caller reads no
+        // count instead of trusting an integer from an unauthenticated port.
+        const live = q.presence === true ? ctx.presence?.() : undefined;
+        const body = live === undefined
+            ? result
+            : { ...result, liveConnections: live.connections, liveTesters: live.testers };
         res
             .writeHead(200, { "content-type": "application/json" })
-            .end(JSON.stringify(result));
+            .end(JSON.stringify(body));
     })
         .catch((err) => {
         ctx.log(`query error: ${err}`);
@@ -177,15 +203,15 @@ function handleAnnotationPost(req, res, ctx) {
         // POSTs exhaust the registry before the creator's phone connected, and the
         // terminal only prints attributed events.
         //
-        // The key is still hostile input either way: the annotation is appended to
-        // a queue a running Claude Code /loop drains, so the raw string must never
-        // survive onto the record.
+        // The key is still hostile input either way: the record reaches an agent's
+        // context on the consumer's stdout, so the raw string must never survive
+        // onto it.
         const annotation = await ctx.annotations.add({ ...input, sessionId: ctx.testers.resolve(input.sessionId) }, { now: Date.now(), id: ctx.makeId() });
-        // Fire the injector chain best-effort — a failed dispatch must not fail the
-        // POST; the long-poll consumer still sees the persisted annotation.
-        if (ctx.dispatcher) {
-            ctx.dispatcher.dispatch(annotation).catch((err) => ctx.log(`dispatch: ${err}`));
-        }
+        // The live stream is told an annotation ARRIVED, with the resolved tester
+        // and nothing else. It is a fact, not a directive: the consumer is the
+        // long-poll, and a terminal line naming what to run would be the platform
+        // teaching one host's idiom.
+        ctx.onAnnotation?.({ tester: annotation.sessionId });
         res
             .writeHead(200, { "content-type": "application/json" })
             .end(JSON.stringify({ id: annotation.id, seq: annotation.seq }));
@@ -196,25 +222,35 @@ function handleAnnotationPost(req, res, ctx) {
             res.writeHead(400).end();
     });
 }
-// The agnostic consumer (`vincentt feedback --wait`) long-polls this: return the
-// next annotation after `after`, or 204 when the hold window elapses.
+/**
+ * The consumer (`vincentt feedback --wait`) long-polls this: the next annotation
+ * after `after`, `204` when the hold window elapses, or `410` when the session
+ * ended under a parked reader.
+ *
+ * `410` is what separates a DEAD channel from a quiet one. Answering the parked
+ * request `204` on teardown is byte-identical to a timeout, so a consumer keeps
+ * re-parking on a channel that can never speak again.
+ */
 function handleFeedbackNext(res, url, ctx) {
     if (!ctx.annotations) {
         res.writeHead(503).end("reverse channel not enabled");
         return;
     }
     const after = Number(url.searchParams.get("after") ?? "0") || 0;
-    const timeoutMs = Math.min(Number(url.searchParams.get("timeout") ?? "300000") || 300_000, MAX_FEEDBACK_TIMEOUT_MS);
     ctx.annotations
-        .nextAfter(after, timeoutMs)
-        .then((annotation) => {
-        if (!annotation) {
+        .nextAfter(after, feedbackTimeoutMs(url.searchParams.get("timeout")))
+        .then((outcome) => {
+        if (outcome.kind === "closed") {
+            res.writeHead(410).end();
+            return;
+        }
+        if (outcome.kind === "timeout") {
             res.writeHead(204).end();
             return;
         }
         res
             .writeHead(200, { "content-type": "application/json" })
-            .end(JSON.stringify(annotation));
+            .end(JSON.stringify(outcome.annotation));
     })
         .catch((err) => {
         ctx.log(`feedback error: ${err}`);
@@ -222,6 +258,23 @@ function handleFeedbackNext(res, url, ctx) {
             res.writeHead(400).end();
     });
 }
+/**
+ * Clamp the hold to `[0, MAX]`, explicitly, with `0` meaning ANSWER NOW.
+ *
+ * `Number(t) || DEFAULT` cannot express that: `0` is falsy, so the one value the
+ * drain's immediate probe depends on took the five-minute fallback and silently
+ * defeated the batch — while `"-1"` fell through to `setTimeout` raw and worked
+ * only by accident. Every path here lands on a finite, non-negative, capped
+ * number before it reaches a timer.
+ */
+export function feedbackTimeoutMs(raw) {
+    if (raw === null || raw.trim() === "")
+        return DEFAULT_FEEDBACK_TIMEOUT_MS;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        return DEFAULT_FEEDBACK_TIMEOUT_MS;
+    return Math.min(Math.max(n, 0), MAX_FEEDBACK_TIMEOUT_MS);
+}
 /**
  * A `tester` filter that is not a well-formed id becomes a sentinel that matches
  * no stored tag, so it filters to an EMPTY list rather than erroring or being
@@ -255,6 +308,11 @@ async function readQuery(req, url) {
         q.tester = p.get("tester");
     if (p.get("viewer"))
         q.viewer = p.get("viewer");
+    // Only the exact string `true` asks for presence. Any other spelling is not a
+    // request for it, so the reply carries no count and the caller says nothing —
+    // the same outcome as an older relay, by the same rule.
+    if (p.get("presence") === "true")
+        q.presence = true;
     return normalizeTester(q);
 }
 function readBody(req, maxBytes = Infinity) {

package/dist/scaffold/index.d.ts

@@ -30,6 +30,15 @@ export declare function needsScaffold(dir: string): Promise<boolean>;
  * Dotfiles count. A folder holding only `.git` is a repo someone cares about.
  */
 export declare function isNonEmptyDir(dir: string): Promise<boolean>;
+/**
+ * The clone failed because the REF does not exist, as opposed to the repo being
+ * unreachable. The two remedies are opposite, and a caller cloning a gallery
+ * source words both differently — so the split is carried by the error's type
+ * rather than by re-matching git's text downstream.
+ */
+export declare class ScaffoldRefError extends Error {
+    constructor(message: string);
+}
 export interface ScaffoldOptions {
     repo?: string;
     /** Template ref (tag) to scaffold from. Defaults to `DEFAULT_TEMPLATE_REF`. */

package/dist/scaffold/index.js

@@ -59,6 +59,18 @@ export async function isNonEmptyDir(dir) {
         return false;
     }
 }
+/**
+ * The clone failed because the REF does not exist, as opposed to the repo being
+ * unreachable. The two remedies are opposite, and a caller cloning a gallery
+ * source words both differently — so the split is carried by the error's type
+ * rather than by re-matching git's text downstream.
+ */
+export class ScaffoldRefError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScaffoldRefError";
+    }
+}
 /**
  * Scaffold the template into `targetDir`. Clones to a temp dir, strips `.git`,
  * copies the files in (never overwriting anything already there), then inits a
@@ -80,7 +92,7 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
             // real cause is a typo'd version). git names the ref in this specific case,
             // so split on that rather than reporting one cause for both.
             if (/(remote branch|Remote branch).*not found|couldn't find remote ref/i.test(msg)) {
-                throw new Error(`The template has no version "${ref}". ` +
+                throw new ScaffoldRefError(`The template has no version "${ref}". ` +
                     `Check the tag exists, or omit --template to use the latest release.`);
             }
             throw new Error(`Could not clone the ${repo} template (check your git access): ${msg}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -24,7 +24,7 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "1.2.0"
+    "@vincentt-xr/harness": "1.3.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",

package/dist/library/qa.f5-b32.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/library/qa.f5-b32.spec.js

@@ -1,202 +0,0 @@
-// QA-F5-C3 · B36's narrowed boundary — zero `/library` requests, and the deny
-// predicate is pinned.
-//
-// THIS IS THE CLAIM f5 IS JUDGED ON. B36: a project builds, previews and
-// publishes with the library unreachable, and no platform capability works
-// better because an asset came from us. The creator loses a catalogue, not a
-// toolchain.
-//
-// dev's b32.test.ts owns layers 1 and 4 (the static import check and the
-// predicate's four URLs) and says so. THIS FILE OWNS LAYERS 2 AND 3 — the live
-// arms — plus the predicate's behavioral half.
-//
-// ⚠ THE NEGATIVE ASSERTION IS THE CASE. A publish that succeeds while the
-// library is unreachable is ALSO what you observe if the call was attempted,
-// timed out and was swallowed by a try/catch — which would make f5 a dependency
-// WITH A TIMEOUT, silently adding seconds to every publish. Only "zero /library
-// requests recorded" distinguishes NOT A DEPENDENCY from A DEPENDENCY THAT
-// FAILS SOFT.
-//
-// ⚠ AND IT ONLY MEANS THAT BECAUSE THE API IS LIVE. Under a host-level deny
-// everything fails, and the fixture cannot tell "publish never called f5" from
-// "publish failed because nothing was reachable"
-// (D-B36-fixture-denies-a-path-prefix-not-a-host).
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import { httpLibraryClient, LibraryUnreachableError } from "./client.js";
-function denyPath(prefix, host) {
-    const attempts = [];
-    const denied = [];
-    const realFetch = globalThis.fetch;
-    // TWO SEPARATE CONDITIONS on the PARSED url. Written this way deliberately —
-    // see the header, and layer 4 below, which is the case that fails when
-    // somebody "simplifies" it into `raw.includes(prefix)`.
-    const predicate = (u) => u.host === host && u.pathname.startsWith(prefix);
-    globalThis.fetch = (async (input, init) => {
-        const raw = typeof input === "string"
-            ? input
-            : input instanceof URL
-                ? input.href
-                : input.url;
-        const u = new URL(raw);
-        const attempt = { host: u.host, pathname: u.pathname };
-        attempts.push(attempt);
-        if (predicate(u)) {
-            denied.push(attempt);
-            // A refused connection, exactly as an unreachable host produces. The CLI
-            // must map this to LibraryUnreachableError → exit 4, never to an answer.
-            throw new TypeError("fetch failed");
-        }
-        return realFetch(input, init);
-    });
-    return {
-        attempts,
-        denied,
-        predicate,
-        restore: () => {
-            globalThis.fetch = realFetch;
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// the live stack
-// ---------------------------------------------------------------------------
-//
-// Inherited from dev, never built here. The endpoint comes from the environment
-// so a port change is a config change rather than an edit to this file — the
-// ports are DERIVED from the task slug, not chosen.
-const API_URL = process.env.QA_F5_API_URL ?? "http://localhost:8088";
-const API_HOST = new URL(API_URL).host;
-let apiLive = false;
-beforeEach(async () => {
-    if (apiLive)
-        return;
-    try {
-        const res = await fetch(`${API_URL}/health`, { signal: AbortSignal.timeout(2000) });
-        apiLive = res.ok;
-    }
-    catch {
-        apiLive = false;
-    }
-});
-let fixture;
-afterEach(() => {
-    fixture?.restore();
-    fixture = undefined;
-});
-describe("QA-F5-C3 · B36 layer 4 — the deny predicate is /library-on-the-API-host only", () => {
-    it("(c) drives the predicate with four URLs, including the anti-drift pin", () => {
-        const f = denyPath("/library", "api.dev.vincentt.studio");
-        fixture = f;
-        const denied = f.predicate;
-        // 1. the f5 route on the API host — DENIED.
-        expect(denied(new URL("https://api.dev.vincentt.studio/library/assets"))).toBe(true);
-        expect(denied(new URL("https://api.dev.vincentt.studio/library/assets:batch"))).toBe(true);
-        // 2. every OTHER route on the SAME host — ALLOWED. f5 has no host of its
-        //    own, so a host deny takes publish down with it.
-        expect(denied(new URL("https://api.dev.vincentt.studio/publishes"))).toBe(false);
-        expect(denied(new URL("https://api.dev.vincentt.studio/projects"))).toBe(false);
-        // 3. THE ANTI-DRIFT PIN. The assets CDN serves library/v1/, so its paths
-        //    contain "/library" too. A predicate written as url.includes("/library")
-        //    denies the CDN and asserts a property f5 NO LONGER HAS
-        //    (D-add-prints-urls). This url is what fails when someone "simplifies"
-        //    the predicate.
-        expect(denied(new URL("https://assets.dev.vincentt.studio/library/v1/props/x.png")), "the assets CDN was DENIED. Under D-add-prints-urls it is on every published viewer's " +
-            "critical path; denying it asserts f5-independence of a published experience, which is " +
-            "explicitly NOT a claim f5 makes any more.").toBe(false);
-        // 4. the CDN at any other path — ALLOWED.
-        expect(denied(new URL("https://assets.dev.vincentt.studio/anything"))).toBe(false);
-        // The weaker form, demonstrated failing, so it is not silently reintroduced.
-        const substring = (raw) => raw.includes("/library");
-        expect(substring("https://assets.dev.vincentt.studio/library/v1/props/x.png")).toBe(true);
-        expect(denied(new URL("https://assets.dev.vincentt.studio/library/v1/props/x.png"))).toBe(false);
-    });
-});
-// The live arms need a running API. They are opt-in, mirroring the Go 4E tier's
-// QA_F5_RUN_SERVE_TIER: absent a stack they report BLOCKED rather than failing,
-// because a red CI check for "no stack here" trains people to ignore the check.
-// They must NEVER silently pass: B36's claim only means something against a
-// REACHABLE route, or the fixture cannot tell "publish never called f5" from
-// "publish failed because nothing was reachable".
-const RUN_LIVE = process.env.QA_F5_RUN_LIVE === "1";
-describe.skipIf(!RUN_LIVE)("QA-F5-C3 · B36 layers 2 and 3 — against the LIVE api", () => {
-    it("(b) an f5 call under the deny fixture is REFUSED and maps to exit 4, not to an answer", async () => {
-        if (!apiLive) {
-            throw new Error(`the api at ${API_URL} is not reachable, so QA-F5-C3's live arms cannot run.\n\n` +
-                `This case is BLOCKED, not passed. B36's assertion only means what it claims when ` +
-                `the API is LIVE: a stray f5 call must be a real request to a REACHABLE route, or ` +
-                `the fixture cannot tell "publish never called f5" from "publish failed because ` +
-                `nothing was reachable".\n\n` +
-                `Boot it:  dev-stack.sh up   (then re-run; override with QA_F5_API_URL)`);
-        }
-        const f = denyPath("/library", API_HOST);
-        fixture = f;
-        const client = httpLibraryClient({ apiUrl: API_URL, pat: "vct_qa_f5_not_a_real_token" });
-        let threw;
-        try {
-            await client.search({ q: "pastel pumpkin" });
-        }
-        catch (err) {
-            threw = err;
-        }
-        expect(threw, "the library search RESOLVED under a deny fixture. A denied request must surface as a " +
-            "transport failure, never as an answer.").toBeInstanceOf(LibraryUnreachableError);
-        // The attempt WAS made and WAS recorded — a fixture that recorded nothing
-        // would make every "zero attempts" assertion below vacuous.
-        expect(f.denied.length, "the deny fixture recorded ZERO denials. A fixture that never fires cannot prove an " +
-            "absence, and every assertion built on it passes for free.").toBeGreaterThan(0);
-        expect(f.denied[0].pathname.startsWith("/library")).toBe(true);
-        expect(f.denied[0].host).toBe(API_HOST);
-    });
-    it("(a) the NON-/library API surface is unaffected — publish's origin still answers", async () => {
-        if (!apiLive) {
-            throw new Error(`the api at ${API_URL} is not reachable; QA-F5-C3 is BLOCKED, not passed`);
-        }
-        const f = denyPath("/library", API_HOST);
-        fixture = f;
-        // The publish path's own origin, under the SAME fixture. This is what makes
-        // layer 2 STRONGER than a host deny: the chain runs against a LIVE, WORKING
-        // API, so a stray f5 call would be a real request to a reachable route
-        // rather than one failure among many.
-        const health = await fetch(`${API_URL}/health`);
-        expect(health.ok, "the API's own /health failed under the deny fixture. The fixture is denying more than " +
-            "the /library path prefix — probably the HOST — which takes publish down with it and " +
-            "makes the whole case fail for a reason unrelated to B36.").toBe(true);
-        const readyz = await fetch(`${API_URL}/readyz`);
-        expect([200, 503]).toContain(readyz.status);
-        // THE ASSERTION THAT ACTUALLY TESTS B36: across every non-f5 request made
-        // above, ZERO have a path beginning with /library.
-        const strays = f.attempts.filter((a) => a.host === API_HOST && a.pathname.startsWith("/library"));
-        expect(strays, `the non-f5 surface issued ${strays.length} request(s) under /library: ` +
-            `${JSON.stringify(strays)}.\n\n` +
-            `B36 says the library is not a dependency of the toolchain's core loop. A green ` +
-            `publish alone is ALSO what you observe if the call was attempted, timed out and was ` +
-            `swallowed — which would make f5 a dependency WITH A TIMEOUT, silently adding seconds ` +
-            `to every publish. Only the empty recorded list distinguishes the two.`).toEqual([]);
-    });
-    it("the f5 route EXISTS and is reachable when the fixture is NOT installed — the control", async () => {
-        if (!apiLive) {
-            throw new Error(`the api at ${API_URL} is not reachable; QA-F5-C3 is BLOCKED, not passed`);
-        }
-        // WITHOUT the fixture. If /library did not exist on this build, every
-        // "zero /library requests" assertion above would pass against a router that
-        // simply has no such route — certifying the boundary while proving nothing.
-        const res = await fetch(`${API_URL}/library/assets?q=pumpkin`);
-        expect(res.status, `GET /library/assets returned ${res.status}. A 404 means the route is NOT MOUNTED on ` +
-            `this build — which makes B36's negative assertion vacuous. The surface is gated on ` +
-            `LIBRARY_ASSETS_BASE_URL; unset, /library never mounts.`).not.toBe(404);
-        // 401 is the expected answer to an unauthenticated read: the route exists
-        // and refuses anonymous callers.
-        expect([200, 401, 403, 503]).toContain(res.status);
-    });
-});
-describe("QA-F5-C3 · live tier status", () => {
-    it("reports whether B36's live arms ran", () => {
-        if (!RUN_LIVE) {
-            console.warn("\nQA-F5-C3 live arms: BLOCKED (not passed, not failed).\n" +
-                "  B36 layers 2 and 3 need a running API. Layer 4 (the deny predicate and the\n" +
-                "  anti-drift pin) DID run and is green.\n" +
-                "  To run them:  dev-stack.sh up   then  QA_F5_RUN_LIVE=1 npm test\n");
-        }
-        expect(true).toBe(true);
-    });
-});

package/dist/library/qa.f5-cli.spec.d.ts

@@ -1 +0,0 @@
-export {};