@vincentt-xr/cli 0.9.0 → 0.10.0

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

@@ -1,206 +0,0 @@
-// QA-F5-G6 · The cross-repo contract — the API's REAL output through the CLI's
-// REAL parser. EXEMPT from the guardrail budget and always written.
-//
-// This is HALF the case. The other half is
-// api/internal/httpapi/qa_f5_contract_test.go, which boots the real router over
-// the real corpus and writes the API's ACTUAL response bytes into
-// __fixtures__/api-golden/. This file feeds those exact bytes to the CLI's real
-// parser and renderers — never to a hand-written stub.
-//
-// WHY. A per-repo suite green against its OWN stub hides a param-name or casing
-// mismatch. On f1 the CLI emitted `redirect` while the console read
-// `redirect_uri`: every suite was green and login was broken end to end, and it
-// surfaced only at the security pass. f5 is the highest-probability casing bug
-// in the product, because it is the ONE response in this API with a mixed
-// convention — camelCase envelope, snake_case record — in a single body.
-//
-// ⚠ THE GOLDEN FILES ARE NOT HAND-EDITABLE. Editing one turns this case back
-// into a per-repo stub test, which is precisely the failure it exists to catch.
-// Regenerate them by running the Go half.
-import { existsSync, readFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
-import { searchLines, showLines, unknownBlockLines } from "./render.js";
-import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
-const GOLDEN = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "__fixtures__", "api-golden");
-/**
- * Read one captured response.
- *
- * A MISSING file FAILS rather than skips. A contract case that quietly tests
- * five of seven arms is worse than no case: it reports green while the two arms
- * that were dropped are exactly the ones nobody looked at.
- */
-function golden(name) {
-    const file = path.join(GOLDEN, `${name}.json`);
-    if (!existsSync(file)) {
-        throw new Error(`the captured API response ${name}.json is MISSING from ${GOLDEN}.\n\n` +
-            `Regenerate it from the api worktree:\n` +
-            `  go test -C <api> ./internal/httpapi/ -run TestQAF5G6 -count=1\n\n` +
-            `These files are the API's ACTUAL bytes. Do NOT hand-write one to make this pass — ` +
-            `a hand-written fixture turns the cross-repo contract case back into a per-repo stub ` +
-            `test, which is the exact failure it exists to catch.`);
-    }
-    return JSON.parse(readFileSync(file, "utf8"));
-}
-/** The raw object, for key-presence assertions a typed parse cannot make. */
-function rawGolden(name) {
-    return golden(name);
-}
-describe("QA-F5-G6 · every arm of the contract table round-trips", () => {
-    it("the capture manifest is complete — a missing arm FAILS rather than skips", () => {
-        const manifest = rawGolden("manifest");
-        expect(manifest.arms, "the capture manifest names no arms").toBeDefined();
-        for (const arm of manifest.arms ?? []) {
-            expect(existsSync(path.join(GOLDEN, `${arm}.json`)), `the manifest names ${arm} but the capture is missing`).toBe(true);
-        }
-        expect(manifest.arms?.length).toBeGreaterThanOrEqual(7);
-    });
-    it("(a) search WITH results — the camelCase envelope and the snake_case record BOTH survive", () => {
-        const raw = rawGolden("search-results");
-        // THE ENVELOPE IS camelCase. Asserted on the RAW bytes, because the parser
-        // would happily read either spelling and report nothing.
-        expect(Object.keys(raw), "the API's search envelope does not carry `resultCount`").toContain("resultCount");
-        expect(Object.keys(raw), "the API's search envelope carries a snake_case `result_count`. THE ENVELOPE IS " +
-            "camelCase and the RECORD is snake_case, in ONE body. Someone normalized both layers " +
-            "to one convention — which reads like a fix and silently breaks every agent prompt in " +
-            "the wild that was told the field is `usage_hint`.").not.toContain("result_count");
-        const res = parseSearchResponse(raw);
-        expect(res.resultCount).toBeGreaterThan(0);
-        expect(res.results.length).toBe(res.resultCount);
-        expect(res.gaps, "`gaps` is absent on a non-empty result set").toEqual([]);
-        // THE RECORD IS snake_case, and each of these is a field the renderer reads.
-        const rec = raw.results[0];
-        for (const k of ["id", "url", "has_alpha", "usage_hint", "occupies_canvas"]) {
-            expect(Object.keys(rec), `the API's record does not carry ${k}`).toContain(k);
-        }
-        for (const k of ["hasAlpha", "usageHint", "occupiesCanvas", "textInImage"]) {
-            expect(Object.keys(rec), `the API's record carries the camelCase key ${k}. The record is snake_case.`).not.toContain(k);
-        }
-        // The PARSER carried the values through, not merely the keys. A parser that
-        // read a key and dropped its value passes every key assertion above.
-        const parsed = res.results[0];
-        expect(parsed.id).toBe(rec.id);
-        expect(parsed.url).toBe(rec.url);
-        expect(parsed.usage_hint).toBe(rec.usage_hint);
-        expect(parsed.has_alpha).toBe(rec.has_alpha);
-        expect(parsed.occupies_canvas).toBe(rec.occupies_canvas);
-        // And the RENDERER prints the url — the one thing `add`/`search` exist to
-        // produce.
-        const screen = searchLines(res, "pumpkin").join("\n");
-        expect(screen).toContain(parsed.url);
-    });
-    it("(b) search with ZERO results — gaps[].tag AND gaps[].message BOTH survive", () => {
-        const raw = rawGolden("search-zero-gaps");
-        const res = parseSearchResponse(raw);
-        expect(res.resultCount).toBe(0);
-        expect(res.results).toEqual([]);
-        expect(res.gaps.length, "the API's zero-result response carried NO gaps through the CLI's parser. The honest " +
-            "empty is the whole feature: without gaps, an unexplained empty is what teaches an " +
-            "agent to invent a URL.").toBeGreaterThan(0);
-        for (const g of res.gaps) {
-            expect(g.tag, "a gap survived without its `tag`. An agent BRANCHES on tag and QUOTES message; " +
-                "shipping one means it branches on prose.").toBeTruthy();
-            expect(g.message, "a gap survived without its `message`").toBeTruthy();
-        }
-        // VERBATIM: the rendered sentence is byte-identical to the corpus's, not one
-        // the CLI composed.
-        const rawGaps = raw.gaps;
-        const screen = searchLines(res, "christmas face filter").join("\n");
-        // The renderer wraps at 70 columns, so compare on the collapsed whitespace.
-        const collapsed = screen.replace(/\s+/g, " ");
-        expect(collapsed, "the rendered zero-result screen does not carry the corpus's gap message VERBATIM. The " +
-            "moment the CLI edits this string it is COMPOSING an inventory claim rather than " +
-            "REPORTING one — and closing a gap stops being a corpus change.").toContain(rawGaps[0].message.replace(/\s+/g, " "));
-    });
-    it("(c) the 503 body carries NO gaps, NO results and NO resultCount — the CLI cannot render it as an empty answer", () => {
-        const raw = rawGolden("search-503");
-        for (const forbidden of ["gaps", "results", "resultCount"]) {
-            expect(Object.keys(raw), `the API's 503 body carries ${forbidden}. A LOAD FAILURE MUST NOT WEAR AN INVENTORY ` +
-                `FACT'S CLOTHES: with a \`gaps\` key present the CLI could render "the library has ` +
-                `no wearable assets" about a ~500-record library whose corpus merely failed to load.`).not.toContain(forbidden);
-        }
-        expect(raw.code).toBe("library_unavailable");
-    });
-    it("(d) batch PARTIAL — resolved and unknown are disjoint, and unknown echoes VERBATIM", () => {
-        const raw = rawGolden("batch-partial");
-        expect(Object.keys(raw)).toContain("resolved");
-        expect(Object.keys(raw)).toContain("unknown");
-        const res = parseBatchResponse(raw);
-        expect(res.resolved.length).toBeGreaterThan(0);
-        expect(res.unknown.length).toBeGreaterThan(0);
-        const resolvedIds = new Set(res.resolved.map((r) => r.id));
-        for (const u of res.unknown) {
-            expect(resolvedIds.has(u), `${u} is in BOTH arrays`).toBe(false);
-        }
-        // The echo is the caller's own input, verbatim, so an agent can diff against
-        // what it sent without parsing our prose.
-        expect(res.unknown).toContain("nope");
-        expect(res.unknown).toContain("lib_ffffffffffffffff");
-        // The renderer does not throw on a partial and names the offending strings.
-        const block = unknownBlockLines(res.unknown, res.resolved.length, true).join("\n");
-        expect(block).toContain("nope");
-    });
-    it("(e) fetch-one RETIRED — `retired` rides fetch and survives the parser", () => {
-        const raw = rawGolden("fetch-retired");
-        expect(Object.keys(raw), "the fetch response for a RETIRED asset carries no `retired` key. Without it a caller " +
-            "cannot tell a de-listed asset from a current one, which is the one fact they need to " +
-            "decide whether to keep using it — and the URL keeps serving forever either way (B37).").toContain("retired");
-        const rec = parseFetchResponse(raw);
-        expect(rec).toBeDefined();
-        expect(rec?.retired).toBe(true);
-        expect(() => showLines(rec)).not.toThrow();
-    });
-    it("(f) a record with NO kind renders FEWER lines and does NOT throw", () => {
-        const raw = rawGolden("fetch-no-kind");
-        expect(Object.keys(raw), "the unclassifiable record carries a `kind` key. It must be ABSENT — not \"\", not " +
-            "\"unknown\". `kind: \"\"` is a PLACEMENT CONTRACT that reads as a value, and an agent " +
-            "branching on it places an unclassifiable asset as a prop.").not.toContain("kind");
-        const rec = parseFetchResponse(raw);
-        expect(rec).toBeDefined();
-        expect(rec?.kind).toBeUndefined();
-        // The renderer READS EVERY FIELD DEFENSIVELY: a missing optional field must
-        // degrade to a MISSING LINE, never to an exception. The CLI and the API are
-        // versioned separately on a creator's machine — `npx vincentt` fetches
-        // whatever the registry has and points it at whatever API the config
-        // resolves to.
-        let lines = [];
-        expect(() => {
-            lines = showLines(rec);
-        }).not.toThrow();
-        const full = parseFetchResponse(rawGolden("fetch-retired"));
-        const fullLines = showLines(full);
-        expect(lines.length, "the record with no kind rendered the SAME number of lines as a full record — the " +
-            "renderer is emitting a line for a field that is not there.").toBeLessThan(fullLines.length);
-    });
-    it("(g) stage's 202 carries every field the operator's process must transport", () => {
-        const raw = rawGolden("stage-202");
-        // The camelCase envelope of the admin surface. `confirmationDigest` is the
-        // ONE wire value both sides COMPUTE rather than copy, which is why a
-        // differing key order or float format silently makes EVERY commit fail.
-        for (const k of ["revisionId", "counts", "diff", "confirmationDigest", "ratio", "expiresAt"]) {
-            expect(Object.keys(raw), `the stage response omits ${k}`).toContain(k);
-        }
-        expect(typeof raw.confirmationDigest).toBe("string");
-        expect(raw.confirmationDigest.length).toBeGreaterThan(16);
-        // The diff's own shape, which the ratio tripwire and the digest are computed
-        // over.
-        const diff = raw.diff;
-        for (const k of ["added", "removed", "changed", "ratio"]) {
-            expect(Object.keys(diff), `the diff omits ${k}`).toContain(k);
-        }
-        // The server's ratio and the envelope's agree. Two numbers for one fact is
-        // how a client ends up trusting the wrong one.
-        expect(raw.ratio).toBe(diff.ratio);
-        // ⚠ THE CLI DOES NOT RECOMPUTE THE DIGEST IN v1.
-        //
-        // The catalog's (g) called for the CLI to recompute confirmationDigest from
-        // the diff bytes and match the server's, pinned to a golden vector. That arm
-        // was RETIRED with `vincentt library publish`
-        // (D-cli-does-not-publish-the-corpus-admin-panel-will): there is no CLI code
-        // that computes a digest, so there is nothing to compare. The SERVER-side
-        // half of the pin — that the value is present, stable and computed over the
-        // diff — is asserted here and in the Go contract test; the CLIENT-side half
-        // belongs to the admin panel's groom.
-    });
-});

package/dist/relay/injectors.d.ts

@@ -1,29 +0,0 @@
-import type { Annotation } from "@vincentt-xr/harness/events";
-export interface Injector {
-    /** Stable id for config/logging: "claude-code" | "paste" | … */
-    readonly name: string;
-    /** Cheap best-effort readiness probe. The dispatcher skips unavailable injectors. */
-    isAvailable(): Promise<boolean>;
-    /**
-     * Deliver so the agent acts with zero user action. Resolves when the host
-     * accepted the injection (not when the agent finishes). Throws if it couldn't —
-     * the dispatcher falls through to the next injector (paste never throws).
-     */
-    inject(a: Annotation): Promise<void>;
-}
-export interface Dispatcher {
-    dispatch(a: Annotation): Promise<string>;
-}
-/** Walk the injector chain; first available that accepts wins, else fall through. */
-export declare function createDispatcher(injectors: Injector[], onLog?: (msg: string) => void): Dispatcher;
-/**
- * Claude Code passive injector: append the annotation to a queue a running `/loop`
- * drains. Available only when the queue dir exists (the loop has been set up), so a
- * project with no loop configured falls through to the fallback.
- */
-export declare function claudeCodeInjector(queuePath: string): Injector;
-/**
- * Universal never-fail fallback. When no zero-action injector accepted the
- * annotation, stage a ready prompt so the worst case is a single paste.
- */
-export declare function pasteInjector(onReady: (prompt: string) => void): Injector;

package/dist/relay/injectors.js

@@ -1,72 +0,0 @@
-// The one per-agent seam of the reverse channel (docs/harness-annotation-push.md).
-// Everything upstream — capture, relay, store — is agent-agnostic; turning a
-// stored annotation into an agent turn goes through an Injector. The dispatcher
-// walks an ordered chain: the first available injector that accepts wins, and on
-// failure it falls through to the next. The final injector never fails.
-//
-// This change ships only the Claude Code passive injector (append to the queue a
-// running `/loop` drains) plus the never-fail paste fallback. Active injectors and
-// other agents' injectors are follow-ups behind this same interface.
-import { appendFile, mkdir } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import path from "node:path";
-/** Walk the injector chain; first available that accepts wins, else fall through. */
-export function createDispatcher(injectors, onLog = () => undefined) {
-    return {
-        async dispatch(a) {
-            for (const inj of injectors) {
-                try {
-                    if (!(await inj.isAvailable()))
-                        continue;
-                    await inj.inject(a);
-                    onLog(`annotation ${a.id} → ${inj.name}`);
-                    return inj.name;
-                }
-                catch (err) {
-                    onLog(`injector ${inj.name} failed: ${err.message}; falling back`);
-                }
-            }
-            // Unreachable when a never-fail fallback (pasteInjector) terminates the chain.
-            throw new Error("no injector accepted the annotation");
-        },
-    };
-}
-/**
- * Claude Code passive injector: append the annotation to a queue a running `/loop`
- * drains. Available only when the queue dir exists (the loop has been set up), so a
- * project with no loop configured falls through to the fallback.
- */
-export function claudeCodeInjector(queuePath) {
-    return {
-        name: "claude-code",
-        async isAvailable() {
-            return existsSync(path.dirname(queuePath));
-        },
-        async inject(a) {
-            await mkdir(path.dirname(queuePath), { recursive: true });
-            const line = JSON.stringify({
-                id: a.id,
-                seq: a.seq,
-                message: a.message,
-                screenshot: a.screenshotPath,
-                spec: a.spec,
-            }) + "\n";
-            await appendFile(queuePath, line, "utf8");
-        },
-    };
-}
-/**
- * Universal never-fail fallback. When no zero-action injector accepted the
- * annotation, stage a ready prompt so the worst case is a single paste.
- */
-export function pasteInjector(onReady) {
-    return {
-        name: "paste",
-        async isAvailable() {
-            return true;
-        },
-        async inject(a) {
-            onReady(`Review annotation ${a.id}: ${a.message}\nScreenshot: ${a.screenshotPath}`);
-        },
-    };
-}