@vincentt-xr/cli 0.1.4 → 0.2.0

package/dist/relay/store.js

@@ -1,22 +1,52 @@
 // The relay's memory: a bounded ring buffer of recent diagnostics events,
 // queryable the way the MCP server asks ("network events since seq 40", "last
-// 20 errors"). Pure and dependency-free so it is fully unit-testable; the WS
-// server in server.ts is a thin wrapper that feeds this and answers queries
-// from it.
+// 20 errors", "just tester t2"). Pure and dependency-free so it is fully
+// unit-testable; the WS server in server.ts is a thin wrapper that feeds this
+// and answers queries from it.
+//
+// This buffer is where diagnostics content lives, and the ONLY place besides
+// the phone's memory (B19). It is on the CREATOR'S OWN MACHINE.
 export class EventStore {
     capacity;
     buf = [];
-    sessionsSeen = new Set();
+    /**
+     * Insertion-ordered, so the roster reads in arrival order rather than in
+     * whatever order a hash lands. Labels are never removed: a viewer that
+     * disconnected 20 seconds ago still has events in this buffer, and dropping
+     * its label would make them unfilterable.
+     */
+    viewersSeen = new Set();
+    /**
+     * Same rule, same reason, for testers — and it matters MORE here, because
+     * `--tester t1` is what a creator runs at the moment the tester who hit the
+     * bug has already closed their tab.
+     *
+     * Note what is NOT here: a set of raw client session keys. The store used to
+     * hold one and return it in `RelayResult.sessions`, which put a
+     * viewer-controlled string on the terminal and in MCP tool output. The raw key
+     * never enters this file; the relay maps it to a tester id first.
+     */
+    testersSeen = new Set();
     latest = -1;
     constructor(capacity = 5000) {
         this.capacity = capacity;
     }
-    /** Ingest a batch from a client. Tracks the session and advances latestSeq. */
-    ingest(sessionId, events) {
-        this.sessionsSeen.add(sessionId);
+    /**
+     * Ingest a batch from a client. Both the VIEWER and the TESTER come from the
+     * connection's own resolution, never from the payload — the device never
+     * proposes its own label (B22), and an identifier taken from the body would be
+     * a viewer-supplied string flowing to the terminal and to MCP tool output.
+     */
+    ingest(events, tags = {}) {
+        const { viewer, tester } = tags;
+        if (viewer !== undefined)
+            this.viewersSeen.add(viewer);
+        if (tester !== undefined)
+            this.testersSeen.add(tester);
         for (const e of events) {
-            // Tag ownership on the stored copy so cross-session queries can filter.
-            this.buf.push(withSession(e, sessionId));
+            // Tag ownership on the stored copy so per-tester and per-viewer queries
+            // can filter.
+            this.buf.push(withTags(e, viewer, tester));
             if (e.seq > this.latest)
                 this.latest = e.seq;
         }
@@ -28,7 +58,12 @@ export class EventStore {
     /** Answer an MCP query against the buffer. Newest-biased when limited. */
     query(q = {}) {
         let out = this.buf.filter((e) => {
-            if (q.sessionId && sessionOf(e) !== q.sessionId)
+            // Filters INTERSECT. A caller passing both wants the events matching both;
+            // ORing them would answer a question nobody asked with more data than they
+            // requested, under a heading naming one.
+            if (q.tester && testerOf(e) !== q.tester)
+                return false;
+            if (q.viewer && viewerOf(e) !== q.viewer)
                 return false;
             if (q.kind && e.kind !== q.kind)
                 return false;
@@ -40,29 +75,48 @@ export class EventStore {
             out = out.slice(out.length - q.limit); // keep the newest `limit`
         }
         return {
-            events: out.map(stripSession),
+            events: out.map(stripTags),
+            // Parallel to `events`, so a follower can print the label in column one
+            // without inventing a placeholder for an unattributed event.
+            eventViewers: out.map(viewerOf),
+            eventTesters: out.map(testerOf),
             latestSeq: this.latest,
-            sessions: [...this.sessionsSeen],
+            testers: [...this.testersSeen],
+            viewers: [...this.viewersSeen],
         };
     }
+    /** The label an event carries, for the live terminal stream. */
+    viewerFor(e) {
+        return viewerOf(e);
+    }
+    /** The tester an event carries, for the live terminal stream. */
+    testerFor(e) {
+        return testerOf(e);
+    }
     size() {
         return this.buf.length;
     }
 }
-// The store tags each event with its owning session out-of-band (a symbol key)
-// so it survives in the buffer without polluting the wire type. Queries strip
-// it before returning.
-const SESSION = Symbol("session");
-function withSession(e, sessionId) {
+// The store tags each event with its owning viewer and tester out-of-band
+// (symbol keys) so they survive in the buffer without polluting the wire type.
+// Queries strip them before returning.
+const VIEWER = Symbol("viewer");
+const TESTER = Symbol("tester");
+function withTags(e, viewer, tester) {
     return Object.assign(Object.create(Object.getPrototypeOf(e)), e, {
-        [SESSION]: sessionId,
+        ...(viewer === undefined ? {} : { [VIEWER]: viewer }),
+        ...(tester === undefined ? {} : { [TESTER]: tester }),
     });
 }
-function sessionOf(e) {
-    return e[SESSION];
+function viewerOf(e) {
+    return e[VIEWER];
+}
+function testerOf(e) {
+    return e[TESTER];
 }
-function stripSession(e) {
+function stripTags(e) {
     const copy = { ...e };
-    delete copy[SESSION];
+    delete copy[VIEWER];
+    delete copy[TESTER];
     return copy;
 }

package/dist/relay/testers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Attributed testers per run. Justified against D-Many-viewers-are-normal's
+ * 40-person demo, NOT against the platform's MaxConcurrentStreams = 256 — those
+ * count different things. 256 is per-session CONCURRENT CONNECTIONS, and one tab
+ * opens 2-6 under HTTP/1.1, so 64 tabs already exceeds what the platform admits
+ * and the platform's cap binds first. Memory does not choose this number: 64
+ * entries is about 4 KB.
+ *
+ * That argument holds ONLY because minting requires a WebSocket the harness
+ * opened — see `resolve` versus `attribute`. A door that could mint without a
+ * stream would not be bounded by the platform's stream cap at all, and filling
+ * this registry is a denial of the creator's live terminal, not merely of an id.
+ */
+export declare const MAX_TESTERS = 64;
+/**
+ * Refused keys remembered, so the cap warning prints ONCE per refused session
+ * rather than once per batch.
+ *
+ * This set is what makes print-once bounded. The key is client-supplied, so
+ * without a cap here its size is a number a client chooses by cycling
+ * sessionStorage. Past this many, further sessions are still refused but no
+ * longer remembered — so a pathological client can re-trigger its own warning
+ * line. That is the correct failure: noisy, local and self-inflicted, versus
+ * unbounded memory on the creator's machine.
+ */
+export declare const MAX_REFUSED_TOMBSTONES = 256;
+/** What the relay learned from one batch's key. */
+export interface Attribution {
+    /** The tester id, or undefined when this key is not attributed. */
+    readonly tester?: string;
+    /**
+     * True exactly once per refused session — the batch that should print the cap
+     * warning. Every later batch from the same refused key reports false.
+     */
+    readonly warnCapReached: boolean;
+}
+export declare class TesterRegistry {
+    private readonly maxTesters;
+    private readonly maxRefused;
+    /** Insertion-ordered, so ids read in arrival order. */
+    private readonly byKey;
+    /** Refused keys, for print-once. Holds no id — these were never assigned one. */
+    private readonly refused;
+    private next;
+    constructor(maxTesters?: number, maxRefused?: number);
+    /**
+     * Resolve a client-supplied key to a tester id, assigning one on first sight.
+     *
+     * The key is validated against the SAME grammar the client mints, with no
+     * sanitize-and-keep branch — the readViewerLabel discipline, applied to the
+     * field beside the label that never had it. A key that misses the grammar is
+     * un-attributed: its events are still ingested, only the tester tag is absent.
+     *
+     * Entries are NEVER removed for the life of the process. That mirrors
+     * viewersSeen in the event store and for its stated reason: the ring buffer
+     * holds events that outlive their producer, and dropping a tester's id would
+     * make its already-stored events unfilterable — worse than never having
+     * labelled them. `--tester t1` must keep answering for the tester who just hit
+     * the bug, because that is the moment the creator runs it.
+     */
+    attribute(key: unknown): Attribution;
+    /**
+     * Resolve a key WITHOUT ever assigning one — the read-only door.
+     *
+     * The annotation POST uses this, and the distinction is load-bearing. That
+     * route is UNAUTHENTICATED and reachable by anyone holding the preview's
+     * capability URL, so if it could mint, 64 bare `fetch` calls would exhaust the
+     * registry before the creator's own phone ever connected. Entries are never
+     * evicted, so that state would be permanent for the run — and because the
+     * terminal only prints attributed events, the creator's live stream would go
+     * blank for every real tester.
+     *
+     * Minting requires a WebSocket the harness actually opened. An annotation can
+     * therefore be attributed to a tester that already exists, and is otherwise
+     * un-attributed, which is the correct failure: the creator still gets their
+     * bug report, it just carries no id.
+     */
+    resolve(key: unknown): string | undefined;
+    /** Ids assigned so far, in arrival order. Never includes a refused session. */
+    testers(): string[];
+    /** How many keys hold an id. Bounded by maxTesters. */
+    get size(): number;
+    /** Whether this id was ever assigned — for `--tester` miss messages. */
+    has(tester: string): boolean;
+}
+/**
+ * Is this a well-formed tester id? Used at the query boundary so a malformed
+ * `--tester` filters to nothing rather than erroring or matching broadly.
+ */
+export declare function isTesterId(s: unknown): s is string;

package/dist/relay/testers.js

@@ -0,0 +1,144 @@
+// The tester registry: the one place a client-supplied session key becomes a
+// tester id the creator can read.
+//
+// A TESTER is one browser tab on one preview, recognised across refreshes. It is
+// deliberately NOT called a device: a tab is what the key can honestly
+// distinguish, one person with two tabs is two testers, and over-claiming is how
+// a debugging coordinate turns into an identity.
+//
+// The whole structure lives in the `vincentt preview` process and dies with it.
+// It is NEVER persisted: a tester id surviving a restart would be exactly the
+// cross-session correlator this design refuses (B22).
+//
+// Pure and dependency-free, like store.ts beside it, so every rule below is
+// unit-testable without a socket.
+import { CLIENT_SESSION_ID_RE, TESTER_ID_RE } from "@vincentt-xr/harness/events";
+/**
+ * Attributed testers per run. Justified against D-Many-viewers-are-normal's
+ * 40-person demo, NOT against the platform's MaxConcurrentStreams = 256 — those
+ * count different things. 256 is per-session CONCURRENT CONNECTIONS, and one tab
+ * opens 2-6 under HTTP/1.1, so 64 tabs already exceeds what the platform admits
+ * and the platform's cap binds first. Memory does not choose this number: 64
+ * entries is about 4 KB.
+ *
+ * That argument holds ONLY because minting requires a WebSocket the harness
+ * opened — see `resolve` versus `attribute`. A door that could mint without a
+ * stream would not be bounded by the platform's stream cap at all, and filling
+ * this registry is a denial of the creator's live terminal, not merely of an id.
+ */
+export const MAX_TESTERS = 64;
+/**
+ * Refused keys remembered, so the cap warning prints ONCE per refused session
+ * rather than once per batch.
+ *
+ * This set is what makes print-once bounded. The key is client-supplied, so
+ * without a cap here its size is a number a client chooses by cycling
+ * sessionStorage. Past this many, further sessions are still refused but no
+ * longer remembered — so a pathological client can re-trigger its own warning
+ * line. That is the correct failure: noisy, local and self-inflicted, versus
+ * unbounded memory on the creator's machine.
+ */
+export const MAX_REFUSED_TOMBSTONES = 256;
+const UNATTRIBUTED = { warnCapReached: false };
+export class TesterRegistry {
+    maxTesters;
+    maxRefused;
+    /** Insertion-ordered, so ids read in arrival order. */
+    byKey = new Map();
+    /** Refused keys, for print-once. Holds no id — these were never assigned one. */
+    refused = new Set();
+    next = 1;
+    constructor(maxTesters = MAX_TESTERS, maxRefused = MAX_REFUSED_TOMBSTONES) {
+        this.maxTesters = maxTesters;
+        this.maxRefused = maxRefused;
+        // TESTER_ID_RE tops out at t999, and `--tester` validates against it. A cap
+        // above that would mint ids the filter then refuses, making those testers
+        // permanently unselectable — a silent failure that would surface only to
+        // whoever raised the cap.
+        if (maxTesters > 999) {
+            throw new Error(`maxTesters ${maxTesters} exceeds the t999 id grammar`);
+        }
+    }
+    /**
+     * Resolve a client-supplied key to a tester id, assigning one on first sight.
+     *
+     * The key is validated against the SAME grammar the client mints, with no
+     * sanitize-and-keep branch — the readViewerLabel discipline, applied to the
+     * field beside the label that never had it. A key that misses the grammar is
+     * un-attributed: its events are still ingested, only the tester tag is absent.
+     *
+     * Entries are NEVER removed for the life of the process. That mirrors
+     * viewersSeen in the event store and for its stated reason: the ring buffer
+     * holds events that outlive their producer, and dropping a tester's id would
+     * make its already-stored events unfilterable — worse than never having
+     * labelled them. `--tester t1` must keep answering for the tester who just hit
+     * the bug, because that is the moment the creator runs it.
+     */
+    attribute(key) {
+        if (typeof key !== "string" || !CLIENT_SESSION_ID_RE.test(key))
+            return UNATTRIBUTED;
+        const existing = this.byKey.get(key);
+        if (existing !== undefined)
+            return { tester: existing, warnCapReached: false };
+        if (this.byKey.size >= this.maxTesters) {
+            // REFUSE. Never recycle.
+            //
+            // Every natural cap implementation merges or splits silently. `hash(key) %
+            // N` is the one a reader reaches for because it is stateless, and it
+            // deterministically collides the 65th tester with an existing one.
+            // LRU-evict is the same failure mirrored: one tester reappears as two.
+            // Refusing is the only branch whose failure is VISIBLE.
+            if (this.refused.has(key))
+                return UNATTRIBUTED;
+            if (this.refused.size < this.maxRefused)
+                this.refused.add(key);
+            return { warnCapReached: true };
+        }
+        const tester = `t${this.next++}`;
+        this.byKey.set(key, tester);
+        return { tester, warnCapReached: false };
+    }
+    /**
+     * Resolve a key WITHOUT ever assigning one — the read-only door.
+     *
+     * The annotation POST uses this, and the distinction is load-bearing. That
+     * route is UNAUTHENTICATED and reachable by anyone holding the preview's
+     * capability URL, so if it could mint, 64 bare `fetch` calls would exhaust the
+     * registry before the creator's own phone ever connected. Entries are never
+     * evicted, so that state would be permanent for the run — and because the
+     * terminal only prints attributed events, the creator's live stream would go
+     * blank for every real tester.
+     *
+     * Minting requires a WebSocket the harness actually opened. An annotation can
+     * therefore be attributed to a tester that already exists, and is otherwise
+     * un-attributed, which is the correct failure: the creator still gets their
+     * bug report, it just carries no id.
+     */
+    resolve(key) {
+        if (typeof key !== "string")
+            return undefined;
+        return this.byKey.get(key);
+    }
+    /** Ids assigned so far, in arrival order. Never includes a refused session. */
+    testers() {
+        return [...this.byKey.values()];
+    }
+    /** How many keys hold an id. Bounded by maxTesters. */
+    get size() {
+        return this.byKey.size;
+    }
+    /** Whether this id was ever assigned — for `--tester` miss messages. */
+    has(tester) {
+        for (const t of this.byKey.values())
+            if (t === tester)
+                return true;
+        return false;
+    }
+}
+/**
+ * Is this a well-formed tester id? Used at the query boundary so a malformed
+ * `--tester` filters to nothing rather than erroring or matching broadly.
+ */
+export function isTesterId(s) {
+    return typeof s === "string" && TESTER_ID_RE.test(s);
+}

package/dist/shared/authError.d.ts

@@ -0,0 +1 @@
+export declare function authFailureMessage(label: string, status: number, detail: string): string;

package/dist/shared/authError.js

@@ -0,0 +1,11 @@
+// A rejected PAT (401 from an authenticated call) is, after the auth cutover, the
+// universal first-run state: every existing `vct_` token was invalidated, so the raw
+// "(401): <body>" is unactionable noise for every user at once. Name the cause and give
+// the one instruction that fixes it. Any other status keeps its existing "(<n>): <body>"
+// shape — a 500/timeout is a different problem and must not be mislabeled a stale token.
+export function authFailureMessage(label, status, detail) {
+    if (status === 401) {
+        return "Your Vincentt access token is no longer valid — run `vincentt login` to sign in again.";
+    }
+    return `${label} (${status})${detail ? `: ${detail}` : ""}`;
+}

package/dist/shared/config.d.ts

@@ -3,6 +3,8 @@ export interface MachineConfig {
     apiUrl: string;
     /** Personal access token (bearer) for machine auth. */
     pat: string;
+    /** Org slug commands act in when no --org flag or VINCENTT_ORG env is given. */
+    activeOrg: string;
 }
 export interface ProjectBinding {
     /** The backend Project id this working tree publishes to. */
@@ -18,7 +20,8 @@ export declare function loadMachineConfig(): Promise<Partial<MachineConfig>>;
 /**
  * Merge a patch into ~/.vincentt/config.json (used by `harness login` to persist
  * a freshly minted PAT). Preserves any other fields already present. The file
- * holds a bearer credential, so the dir/file get owner-only perms.
+ * holds a bearer credential, so the dir/file get owner-only perms (enforced on
+ * every write, even when the file pre-existed with looser perms).
  */
 export declare function writeMachineConfig(patch: Partial<MachineConfig>): Promise<string>;
 /**
@@ -30,6 +33,23 @@ export declare function clearMachineToken(): Promise<{
     hadToken: boolean;
 }>;
 export declare function loadProjectBinding(cwd: string): Promise<ProjectBinding | undefined>;
+export interface LocatedBinding {
+    binding: ProjectBinding;
+    /** The directory holding `.vincentt/project.json` (cwd, or an ancestor). */
+    dir: string;
+    /** Absolute path of the binding file, for messages that name it. */
+    path: string;
+}
+/**
+ * Locate the binding by PRECEDENCE, never inference: cwd, then each ancestor up
+ * to and including the git root. Nothing is guessed from the folder name and
+ * there is no "you only have one project" fallback — a wrong-but-plausible
+ * binding is silent retargeting, which B12 forbids.
+ *
+ * The walk stops at the git root so a binding in a parent repo cannot capture an
+ * unrelated sibling tree, and at the filesystem root when there is no repo.
+ */
+export declare function locateProjectBinding(cwd: string): Promise<LocatedBinding | undefined>;
 /**
  * Write the per-tree binding and make sure `.vincentt/` is gitignored (so the
  * secret-free-but-tenant-scoped binding never rides a commit or `git archive`).
@@ -44,9 +64,57 @@ export interface ResolvedConfig {
     apiUrl: string;
     pat: string;
 }
+export declare const DEFAULT_API_URL = "http://localhost:5051";
+export interface ResolveConfigOptions {
+    /** Honor a binding's apiUrl override (the `--allow-custom-api` flag). */
+    allowCustomApi?: boolean;
+    /** Where advisory lines go. Defaults to a no-op so library callers stay quiet. */
+    warn?: (line: string) => void;
+}
+/**
+ * Decide which API host a call goes to, given every source that can name one.
+ *
+ * The rule is PROVENANCE, not location. A machine config and an env var are set by
+ * the person running the command; `.vincentt/project.json` travels with a
+ * repository, so anyone who can land a commit can set it — and since the PAT comes
+ * from machine-global config, honoring the file's host by default sends the user's
+ * bearer token to a host chosen by whoever wrote the repo. So the binding's apiUrl
+ * is ignored unless `--allow-custom-api` states intent, INVERTING the precedence
+ * shipped in 0.1.x.
+ */
+export interface ApiUrlDecision {
+    /** The host the request actually goes to. */
+    apiUrl: string;
+    /**
+     * The host the caller's OWN configuration names, whether or not it won. The
+     * advisory compares against this, not against the decision — on the flagged
+     * path the decision IS the binding, so reading it back would print the
+     * override twice and claim it was the machine config.
+     */
+    configuredUrl: string;
+    ignoredBindingApiUrl?: string;
+    usedBindingApiUrl?: string;
+}
+export declare function decideApiUrl(input: {
+    bindingApiUrl?: string;
+    envApiUrl?: string;
+    machineApiUrl?: string;
+    allowCustomApi?: boolean;
+}): ApiUrlDecision;
+/**
+ * Resolve the API URL + PAT for a machine call. Throws a clear, actionable error
+ * when no PAT is configured. When a binding's apiUrl diverges from the configured
+ * one, the safe branch has ALREADY been taken by the time the advisory prints —
+ * it reports a decision rather than asking for one.
+ */
+export declare function resolveConfig(cwd: string, opts?: ResolveConfigOptions): Promise<ResolvedConfig>;
 /**
- * Resolve the API URL + PAT for a machine call. Precedence: a project binding's
- * apiUrl wins for the URL; env vars override the machine-config file; the file is
- * the base. Throws a clear, actionable error when no PAT is configured.
+ * The Flow L12 transcripts. Ignoring an override is the loud case (both hosts on
+ * their own aligned lines, the mechanism named, and where to go look); honoring one
+ * on purpose is two quiet lines, because a creator who typed the flag has already
+ * stated intent and re-reading the lecture every run is how advisories get
+ * filtered out mentally — taking the un-flagged one with them.
  */
-export declare function resolveConfig(cwd: string): Promise<ResolvedConfig>;
+export declare function apiUrlAdvisory(decided: ApiUrlDecision, ctx: {
+    bindingPath: string;
+}): string[];