@vincentt-xr/cli 0.5.1 → 0.7.0

package/dist/cli/args.d.ts

@@ -13,6 +13,8 @@ export declare function isHelpInvocation(args: string[]): boolean;
  * skip a publish the creator asked for. Anywhere else it stays an unknown flag.
  */
 export declare function isVersionInvocation(args: string[]): boolean;
+/** Flags that stand alone; every other `--flag` consumes the next argument. */
+export declare const BOOLEAN_FLAGS: Set<string>;
 export declare function refusedFlag(args: string[]): string | undefined;
 /**
  * The bare arguments, with flag VALUES removed. Without this, `vincentt link --dir

package/dist/cli/args.js

@@ -18,7 +18,7 @@ export function isVersionInvocation(args) {
     return args[0] === "--version" || args[0] === "-v";
 }
 /** Flags that stand alone; every other `--flag` consumes the next argument. */
-const BOOLEAN_FLAGS = new Set([
+export const BOOLEAN_FLAGS = new Set([
     "--force",
     "--preview",
     "--json",
@@ -26,6 +26,10 @@ const BOOLEAN_FLAGS = new Set([
     "--wait",
     "--watch",
     "--stop",
+    "--restart",
+    "--no-qr",
+    "--verbose",
+    "--send",
     "--no-install",
     "--allow-custom-api",
     "--yes",

package/dist/cli/index.js

@@ -31,10 +31,16 @@ import { consoleVerbCommand, isConsoleOnlyVerb } from "../publish/consoleVerbs.j
 import { PreviewUi } from "../preview/command.js";
 import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview } from "../lib/relayInfo.js";
-import { mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
+import { attachedToRunning, mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
 import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
+import { record as recordInvocation } from "../dx/journal.js";
+import { dxSendCommand, parseDxOptions, runDx } from "../dx/command.js";
+import { journalEnabled, journalPath, readJournal } from "../dx/journal.js";
+import { postReport } from "../dx/send.js";
+import { nudgeFor } from "../dx/nudge.js";
+import { verbOf } from "../dx/skeleton.js";
 import { isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
 // The console origin serves /cli-auth (the browser target for `vincentt login`). VINCENTT_
 // CONSOLE_URL overrides for dev/dogfood; VINCENTT_EDITOR_URL is honored as a legacy alias.
@@ -305,8 +311,23 @@ async function preview() {
     // treated as absent, which lands on the mint the creator actually asked for.
     const existing = await readLivePreview(cwd);
     if (existing !== undefined) {
-        await followPreview(existing, ui, filterTester, filterViewer);
-        return;
+        if (has("--restart")) {
+            // Asked for explicitly, so the old session is ended before the mint —
+            // otherwise the server's supersede rule would race the new one.
+            await previewStopSignal(cwd);
+        }
+        else if (filterTester === undefined && filterViewer === undefined) {
+            // No filter means the caller wanted the preview, not a diagnostics stream:
+            // hand them the link and exit rather than blocking in the follow loop.
+            // Following a live preview is what `vincentt logs`/`network`/`trace` are.
+            for (const l of attachedToRunning(existing.url, existing.expiresAt))
+                console.log(l);
+            return;
+        }
+        else {
+            await followPreview(existing, ui, filterTester, filterViewer);
+            return;
+        }
     }
     let ending = null;
     let resolveDone;
@@ -402,6 +423,10 @@ async function preview() {
  */
 async function followPreview(info, ui, filterTester, filterViewer) {
     console.log("→ Attaching to the preview running in this folder");
+    // The link, on its own line: a caller who is following a tester still needs to
+    // know which preview they landed on, and re-running to find out is the loop
+    // this printing exists to break.
+    console.log(info.url);
     const following = filterTester ?? filterViewer;
     if (following !== undefined) {
         console.log(`✓ Following ${following}`);
@@ -555,6 +580,42 @@ async function version() {
     for (const line of renderVersion(report))
         console.log(line);
 }
+// ---- dx ---------------------------------------------------------------------
+async function dx() {
+    const options = parseDxOptions(argv);
+    if (!options.send) {
+        process.exitCode = runDx(argv, (l) => console.log(l));
+        return;
+    }
+    // `--send` is the one path out of this machine, so it resolves auth the way
+    // every other authed verb does and refuses rather than guessing.
+    process.exitCode = await dxSendCommand({
+        entries: readJournal,
+        print: (l) => console.log(l),
+        now: () => Date.now(),
+        enabled: () => journalEnabled(),
+        path: journalPath,
+        cliVersion,
+        auth: async () => {
+            // resolveConfig THROWS when there is no PAT, and its message is written
+            // for a verb that cannot proceed at all. Sending a DX report is
+            // optional, so a signed-out creator gets one plain line from
+            // dxSendCommand instead of a config-file stack trace.
+            try {
+                const cfg = await resolveConfig(projectDir(), {
+                    allowCustomApi: has("--allow-custom-api"),
+                });
+                return cfg.pat ? { apiUrl: cfg.apiUrl, pat: cfg.pat } : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+        post: (apiUrl, pat, report) => postReport(apiUrl, pat, report),
+        confirm: (q) => stdinConfirm()(`${q} [y/N] `, false),
+        interactive: () => Boolean(process.stdin.isTTY),
+    }, options);
+}
 // ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
@@ -593,7 +654,8 @@ function usage() {
         `  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\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` +
@@ -607,7 +669,11 @@ function usage() {
         `Servers\n` +
         `  relay              Run the diagnostics/annotation relay\n\n` +
         `Meta\n` +
-        `  version            CLI version, and the API this machine resolves to\n\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\n` +
         `Common options: --dir <path> (project dir, default cwd)\n` +
         `                --allow-custom-api  honor a binding's apiUrl override\n`);
 }
@@ -655,6 +721,8 @@ async function main() {
             return feedback();
         case "relay":
             return relay();
+        case "dx":
+            return dx();
         default:
             // Flow L30: rolling back and taking an address offline are console
             // actions, and a bare "unknown command" here would be the product failing
@@ -666,7 +734,43 @@ async function main() {
             process.exitCode = 1;
     }
 }
-main().catch((err) => {
+// Every invocation is journaled here, at the one site that sees all of them —
+// the verbs, both pre-switch gates, the console-only fallback and the unknown
+// command. Recording is best-effort and local-only (see dx/journal.ts); it never
+// changes what the CLI does or what it exits with.
+const startedAt = Date.now();
+function journal(exitCode, error) {
+    recordInvocation({
+        argv,
+        cliVersion: cliVersion(),
+        cwd: process.cwd(),
+        startedAt,
+        endedAt: Date.now(),
+        exitCode,
+        error,
+    });
+    // The hint goes out AFTER the run it is about, so it reads as a footnote to
+    // what just happened rather than a warning about what is about to. Never on
+    // `dx` itself — telling someone reading the friction report that they could
+    // read the friction report is noise.
+    if (verbOf(argv) === "dx")
+        return;
+    try {
+        for (const l of nudgeFor(readJournal(), Date.now()))
+            console.log(l);
+    }
+    catch {
+        // A hint that can break a publish is not worth having.
+    }
+}
+main()
+    .then(() => {
+    // Verbs report failure by assigning process.exitCode and returning, so the
+    // resolved path is not necessarily the successful one.
+    journal(Number(process.exitCode ?? 0));
+})
+    .catch((err) => {
     console.error(`\n✗ ${err instanceof Error ? err.message : String(err)}`);
+    journal(1, err);
     process.exit(1);
 });

package/dist/dx/clusters.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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 {
+    kind: ClusterKind;
+    skeleton: string;
+    entries: JournalEntry[];
+    /** Wall time from the first to the last call in the run, in ms. */
+    spanMs: number;
+    errors: number;
+    /** True when the run ended on a success — the caller got there eventually. */
+    recovered: boolean;
+}
+/**
+ * Group consecutive same-skeleton entries and keep the runs that look like
+ * friction. Entries are expected in chronological order.
+ */
+export declare function findClusters(entries: JournalEntry[]): Cluster[];
+/**
+ * Rank by cost × recurrence: a cluster's cost is the calls it wasted, and a
+ * skeleton seen across several clusters is a recurring gap rather than a bad
+ * afternoon. Error clusters outrank repetition ones at equal weight — the
+ * caller was actively blocked rather than merely inefficient.
+ */
+export declare function rankClusters(clusters: Cluster[]): Cluster[];

package/dist/dx/clusters.js

@@ -0,0 +1,71 @@
+/** A repetition run must be at least this long to count as friction. */
+const REPETITION_MIN = 3;
+/**
+ * How close together repeated calls must sit to read as one struggle. Three
+ * `preview` runs across a working day are three sessions; three inside ten
+ * minutes are one caller not getting what they needed.
+ */
+const REPETITION_WINDOW_MS = 10 * 60 * 1000;
+function span(run) {
+    const first = Date.parse(run[0].ts);
+    const last = Date.parse(run[run.length - 1].ts);
+    return Number.isFinite(first) && Number.isFinite(last) ? last - first : 0;
+}
+/**
+ * Group consecutive same-skeleton entries and keep the runs that look like
+ * friction. Entries are expected in chronological order.
+ */
+export function findClusters(entries) {
+    const clusters = [];
+    for (let i = 0; i < entries.length;) {
+        const skel = entries[i].skel;
+        const run = [];
+        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 spanMs = span(run);
+        // 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
+        // trains a reader to skim past the report entirely.
+        if (errors > 0 && run.length >= 2) {
+            clusters.push({
+                kind: "error",
+                skeleton: skel,
+                entries: run,
+                spanMs,
+                errors,
+                recovered: run[run.length - 1].exit === 0,
+            });
+        }
+        else if (errors === 0 &&
+            run.length >= REPETITION_MIN &&
+            spanMs <= REPETITION_WINDOW_MS) {
+            clusters.push({
+                kind: "repetition",
+                skeleton: skel,
+                entries: run,
+                spanMs,
+                errors: 0,
+                recovered: true,
+            });
+        }
+        i = j;
+    }
+    return clusters;
+}
+/**
+ * Rank by cost × recurrence: a cluster's cost is the calls it wasted, and a
+ * skeleton seen across several clusters is a recurring gap rather than a bad
+ * afternoon. Error clusters outrank repetition ones at equal weight — the
+ * caller was actively blocked rather than merely inefficient.
+ */
+export function rankClusters(clusters) {
+    const recurrence = new Map();
+    for (const c of clusters) {
+        recurrence.set(c.skeleton, (recurrence.get(c.skeleton) ?? 0) + 1);
+    }
+    const weight = (c) => c.entries.length * (recurrence.get(c.skeleton) ?? 1) * (c.kind === "error" ? 2 : 1);
+    return [...clusters].sort((a, b) => weight(b) - weight(a));
+}

package/dist/dx/command.d.ts

@@ -0,0 +1,50 @@
+import type { JournalEntry } from "./journal.js";
+import type { WireReport } from "./send.js";
+export interface DxDeps {
+    entries: () => JournalEntry[];
+    print: (line: string) => void;
+    now: () => number;
+    enabled: () => boolean;
+    path: () => string;
+}
+export interface DxOptions {
+    /** Only consider runs from the last N days. */
+    days: number;
+    json: boolean;
+    /** Send the findings to the Vincentt team. Never implied by anything else. */
+    send: boolean;
+    /** Skip the confirmation prompt. Only meaningful with --send. */
+    yes: boolean;
+    /** The creator's own words about the friction, carried with the report. */
+    note?: string;
+}
+export declare function parseDxOptions(args: string[]): DxOptions;
+export declare function dxCommand(deps: DxDeps, options: DxOptions): number;
+/** Wire the command to the real journal. */
+export declare function runDx(args: string[], print: (line: string) => void): number;
+export interface DxSendDeps extends DxDeps {
+    /** Resolved API host + PAT. Absent when the creator is not signed in. */
+    auth: () => Promise<{
+        apiUrl: string;
+        pat: string;
+    } | undefined>;
+    post: (apiUrl: string, pat: string, report: WireReport) => Promise<{
+        ref: string;
+        findings: number;
+        expiresAt: string;
+    }>;
+    /** Ask before sending. Returns false to abort. */
+    confirm: (question: string) => Promise<boolean>;
+    cliVersion: () => string;
+    /** True when stdin is a terminal — i.e. a human is here to answer. */
+    interactive: () => boolean;
+}
+/**
+ * `vincentt dx --send`.
+ *
+ * The order is the consent model and is not an implementation detail: find the
+ * friction, BUILD the payload, SHOW it in full, ask, and only then send. A
+ * creator who cannot see what leaves their machine before it leaves has not
+ * agreed to anything.
+ */
+export declare function dxSendCommand(deps: DxSendDeps, options: DxOptions): Promise<number>;

package/dist/dx/command.js

@@ -0,0 +1,167 @@
+import { findClusters, rankClusters } from "./clusters.js";
+import { journalEnabled, journalPath, readJournal } from "./journal.js";
+import { buildReport, renderPayload } from "./send.js";
+const DEFAULT_DAYS = 7;
+export function parseDxOptions(args) {
+    const i = args.indexOf("--days");
+    const raw = i !== -1 ? Number(args[i + 1]) : NaN;
+    const n = args.indexOf("--note");
+    const note = n !== -1 ? args[n + 1] : undefined;
+    return {
+        days: Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_DAYS,
+        json: args.includes("--json"),
+        send: args.includes("--send"),
+        yes: args.includes("--yes"),
+        note: note !== undefined && !note.startsWith("-") ? note : undefined,
+    };
+}
+function withinDays(entries, days, now) {
+    const cutoff = now - days * 24 * 60 * 60 * 1000;
+    return entries.filter((e) => {
+        const t = Date.parse(e.ts);
+        return Number.isFinite(t) && t >= cutoff;
+    });
+}
+function seconds(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    return `${Math.round(s / 60)}m`;
+}
+function describe(c) {
+    const head = c.kind === "error"
+        ? `${c.entries.length}× ${c.skeleton} — ${c.errors} failed${c.recovered ? ", then succeeded" : ", never recovered"}`
+        : `${c.entries.length}× ${c.skeleton} — all succeeded, within ${seconds(c.spanMs)}`;
+    const why = c.kind === "error"
+        ? c.recovered
+            ? "  The caller got there in the end. What did the first failure not tell them?"
+            : "  The caller retried, then gave up. This one blocked real work."
+        : "  Repeated with no error: the caller did not get what they needed the first time.";
+    const errs = [
+        ...new Set(c.entries.map((e) => e.err).filter((e) => e !== null)),
+    ];
+    const lines = [`• ${head}`, why];
+    if (errs.length > 0)
+        lines.push(`  Errors: ${errs.join(", ")}`);
+    return lines;
+}
+export function dxCommand(deps, options) {
+    if (!deps.enabled()) {
+        deps.print("The DX journal is off (VINCENTT_DX_JOURNAL=0). Nothing is being recorded.");
+        return 0;
+    }
+    const all = deps.entries();
+    if (all.length === 0) {
+        deps.print("No journal yet — it fills as you use the CLI.");
+        deps.print(`  ${deps.path()}`);
+        return 0;
+    }
+    const entries = withinDays(all, options.days, deps.now());
+    const clusters = rankClusters(findClusters(entries));
+    if (options.json) {
+        deps.print(JSON.stringify({ window: `${options.days}d`, runs: entries.length, clusters }, null, 2));
+        return 0;
+    }
+    deps.print(`${entries.length} runs in the last ${options.days} days.`);
+    deps.print("");
+    if (clusters.length === 0) {
+        // A clean window is a real result. Manufacturing a finding to fill the
+        // report is how a signal becomes noise.
+        deps.print("No friction detected.");
+    }
+    else {
+        deps.print(`${clusters.length} friction ${clusters.length === 1 ? "point" : "points"}, worst first:`);
+        deps.print("");
+        for (const c of clusters) {
+            for (const l of describe(c))
+                deps.print(l);
+            deps.print("");
+        }
+        deps.print("If an agent ran these, ask it what it was trying to do — the journal");
+        deps.print("records the shape of a run, not the intent behind it.");
+    }
+    // Printed on every report, findings or not: where the file is and that it
+    // stays put is the claim that lets this run without asking permission first,
+    // and a claim only made on some runs is one a reader cannot rely on.
+    deps.print("");
+    deps.print(`Journal: ${deps.path()} (local only, never sent)`);
+    return 0;
+}
+/** Wire the command to the real journal. */
+export function runDx(args, print) {
+    return dxCommand({
+        entries: readJournal,
+        print,
+        now: () => Date.now(),
+        enabled: () => journalEnabled(),
+        path: journalPath,
+    }, parseDxOptions(args));
+}
+/**
+ * `vincentt dx --send`.
+ *
+ * The order is the consent model and is not an implementation detail: find the
+ * friction, BUILD the payload, SHOW it in full, ask, and only then send. A
+ * creator who cannot see what leaves their machine before it leaves has not
+ * agreed to anything.
+ */
+export async function dxSendCommand(deps, options) {
+    if (!deps.enabled()) {
+        deps.print("The DX journal is off (VINCENTT_DX_JOURNAL=0). There is nothing to send.");
+        return 0;
+    }
+    const entries = withinDays(deps.entries(), options.days, deps.now());
+    const clusters = rankClusters(findClusters(entries));
+    if (clusters.length === 0) {
+        // Nothing to report is a result, not a failure. Sending an empty report
+        // would cost the creator a round trip to tell us nothing.
+        deps.print(`No friction detected in the last ${options.days} days — nothing to send.`);
+        return 0;
+    }
+    // --yes REQUIRES a terminal.
+    //
+    // The nudge prints into an agent's transcript, and an agent that reads it has
+    // every incentive to act: it just failed four times. Its reflex for an
+    // interactive prompt is to add --yes. That path ends with the AGENT deciding
+    // to transmit, supplying the note, and the human seeing the payload scroll
+    // past in a transcript they may not be reading — which is not the opt-in this
+    // feature is built around.
+    //
+    // Without --yes there is no such path: the prompt reads EOF under a pipe and
+    // fails closed. So the gate is narrow on purpose — it closes the one way an
+    // autonomous caller could consent on a creator's behalf, and leaves --yes
+    // working for the human who has read the payload.
+    if (options.yes && !deps.interactive()) {
+        deps.print("Sending a DX report is the creator's call, so --yes needs a terminal.");
+        deps.print("Run `vincentt dx --send` yourself, or drop --yes to be asked.");
+        return 1;
+    }
+    const auth = await deps.auth();
+    if (auth === undefined) {
+        deps.print("Not signed in. Run `vincentt login` to send a report.");
+        return 1;
+    }
+    const report = buildReport(clusters, deps.cliVersion(), options.note);
+    for (const l of renderPayload(report))
+        deps.print(l);
+    deps.print("");
+    if (!options.yes && !(await deps.confirm("Send this report?"))) {
+        deps.print("Not sent.");
+        return 0;
+    }
+    try {
+        const res = await deps.post(auth.apiUrl, auth.pat, report);
+        deps.print("");
+        deps.print(`✓ Reported — ${res.findings} ${res.findings === 1 ? "finding" : "findings"}, ref ${res.ref}`);
+        deps.print(`  Kept until ${res.expiresAt}, then deleted.`);
+        deps.print("  Your journal stays on this machine.");
+        return 0;
+    }
+    catch (err) {
+        deps.print("");
+        deps.print(`✗ ${err instanceof Error ? err.message : String(err)}`);
+        return 1;
+    }
+}

package/dist/dx/journal.d.ts

@@ -0,0 +1,51 @@
+export interface JournalEntry {
+    /** ISO8601 UTC, invocation start. */
+    ts: string;
+    /** CLI version, so a finding can be dropped once the fix ships. */
+    v: string;
+    verb: string;
+    /** Flag names with values elided — the retry-cluster key. */
+    skel: string;
+    exit: number;
+    ms: number;
+    /** Error CLASS (`err.name`), never a message — messages carry user data. */
+    err: string | null;
+    /** Hash of the working tree, so runs group by project without recording where it is. */
+    wt: string;
+}
+/**
+ * Beside the machine config, so the journal shares the home the PAT already
+ * lives in — and so a run made outside any project (`login`, `version`) is still
+ * recorded, which a per-project file could not do.
+ *
+ * Resolved per call rather than captured at module load: the home directory is
+ * the seam tests move, and a frozen path would silently write to the real one.
+ */
+export declare function journalPath(): string;
+/** `VINCENTT_DX_JOURNAL=0` turns recording off. A local file still needs an off switch. */
+export declare function journalEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * A stable, non-reversible handle for "the folder this run happened in". Enough
+ * to group runs by project — which is what makes the one-session-per-tree
+ * friction visible — without recording anyone's directory layout.
+ */
+export declare function workingTreeId(cwd: string): string;
+export interface RecordInput {
+    argv: string[];
+    cliVersion: string;
+    cwd: string;
+    startedAt: number;
+    endedAt: number;
+    exitCode: number;
+    error?: unknown;
+}
+export declare function buildEntry(input: RecordInput): JournalEntry;
+/**
+ * Append one entry. Never throws: a journal that can break a publish is a
+ * liability, and every failure mode here (read-only home, full disk, a
+ * concurrent writer) is one the creator would rather have silently ignored than
+ * turned into a failed command.
+ */
+export declare function record(input: RecordInput): void;
+/** Read the journal oldest-first. Malformed lines are skipped, not fatal. */
+export declare function readJournal(): JournalEntry[];