@vincentt-xr/cli 0.6.0 → 0.7.0

package/dist/cli/args.js

@@ -29,6 +29,7 @@ export const BOOLEAN_FLAGS = new Set([
     "--restart",
     "--no-qr",
     "--verbose",
+    "--send",
     "--no-install",
     "--allow-custom-api",
     "--yes",

package/dist/cli/index.js

@@ -36,7 +36,11 @@ 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 { runDx } from "../dx/command.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.
@@ -576,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");
@@ -631,7 +671,9 @@ function usage() {
         `Meta\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. Never sent.\n\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`);
 }
@@ -680,8 +722,7 @@ async function main() {
         case "relay":
             return relay();
         case "dx":
-            process.exitCode = runDx(argv, (l) => console.log(l));
-            return;
+            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
@@ -708,6 +749,19 @@ function journal(exitCode, error) {
         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(() => {

package/dist/dx/command.d.ts

@@ -1,4 +1,5 @@
 import type { JournalEntry } from "./journal.js";
+import type { WireReport } from "./send.js";
 export interface DxDeps {
     entries: () => JournalEntry[];
     print: (line: string) => void;
@@ -10,8 +11,40 @@ 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

@@ -1,12 +1,18 @@
 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) {
@@ -93,3 +99,69 @@ export function runDx(args, print) {
         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/nudge.d.ts

@@ -0,0 +1,7 @@
+import type { JournalEntry } from "./journal.js";
+/**
+ * The nudge fires only on a cluster the CURRENT run just completed, so it
+ * appears at the moment of friction rather than as a standing complaint about
+ * something that happened this morning.
+ */
+export declare function nudgeFor(entries: JournalEntry[], now: number): string[];

package/dist/dx/nudge.js

@@ -0,0 +1,54 @@
+/**
+ * The nudge: a one-line hint, printed after a command that just completed a
+ * friction cluster, telling the creator the report exists.
+ *
+ * It is here because a command nobody remembers produces no data. A creator
+ * building an AR app is not going to think "I should audit my tooling" — they
+ * are going to swear at the fourth preview and keep going. The moment the
+ * friction happens is the only moment the report is cheap to ask for.
+ *
+ * It is a HINT and never an action. Nothing is sent, nothing is queued, and the
+ * creator still has to type the command — which is what keeps `--send` an
+ * explicit act rather than a dialog they clicked through while annoyed.
+ */
+import { findClusters } from "./clusters.js";
+/** How far back a nudge looks. A cluster older than this is not "right now". */
+const WINDOW_MS = 15 * 60 * 1000;
+/**
+ * The nudge fires only on a cluster the CURRENT run just completed, so it
+ * appears at the moment of friction rather than as a standing complaint about
+ * something that happened this morning.
+ */
+export function nudgeFor(entries, now) {
+    if (entries.length === 0)
+        return [];
+    const recent = entries.filter((e) => {
+        const t = Date.parse(e.ts);
+        return Number.isFinite(t) && now - t <= WINDOW_MS;
+    });
+    if (recent.length === 0)
+        return [];
+    const last = recent[recent.length - 1];
+    const clusters = findClusters(recent);
+    // Only a cluster the LAST entry belongs to. A cluster the caller already
+    // worked past is not friction they are feeling now, and nagging about it is
+    // how a hint becomes noise a reader learns to skip.
+    const live = clusters.find((c) => c.skeleton === last.skel && c.entries[c.entries.length - 1].ts === last.ts);
+    if (live === undefined)
+        return [];
+    const what = live.kind === "repetition"
+        ? `${live.entries.length} runs of \`${live.skeleton}\` in a few minutes.`
+        : `\`${live.skeleton}\` failed ${live.errors}× just now.`;
+    // STATES A FACT, NEVER AN INSTRUCTION.
+    //
+    // This line lands in an agent's transcript, because in the agent-driven loop
+    // the CLI's stdout IS the agent's input. "Run `vincentt dx --send` to report
+    // this" is a directive an autonomous caller will simply obey — and a report
+    // an agent decided to send is automation wearing consent's clothes, not the
+    // opt-in this feature is built around. Naming that a command exists is
+    // information; telling a caller to transmit is not.
+    //
+    // Note it names `vincentt dx` (which only READS, locally) and never the
+    // sending form.
+    return ["", `  ! ${what}`, "    `vincentt dx` shows friction from your recent runs."];
+}

package/dist/dx/send.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `vincentt dx --send` — the one place anything from the journal leaves the
+ * machine.
+ *
+ * The journal itself is local and unconditional. Sending is neither: it happens
+ * only when a creator types this flag, and only after they have been shown the
+ * exact payload. That ordering is the whole consent model — a report is an act,
+ * not a background transmission — so nothing in this file may be called from a
+ * path the creator did not ask for.
+ *
+ * What goes: the SHAPE of the friction (skeleton, counts, timing, error class
+ * names) plus the CLI version and platform. What never goes: the raw journal,
+ * flag values, paths, error messages, or anything about which project this was.
+ * The server re-validates all of it — a client that leaked a value cannot
+ * persist it by asking — but the boundary is drawn here first, because a payload
+ * that needs server-side scrubbing was built wrong.
+ */
+import type { Cluster } from "./clusters.js";
+/** A finding as it goes on the wire. Mirrors the API's dxFindingRequest. */
+export interface WireFinding {
+    kind: "error" | "repetition";
+    skeleton: string;
+    calls: number;
+    errors: number;
+    spanMs: number;
+    errorClasses?: string[];
+    note?: string;
+}
+export interface WireReport {
+    cliVersion: string;
+    platform: string;
+    findings: WireFinding[];
+}
+/**
+ * The server bounds a report at 50 findings and refuses the whole thing past
+ * that, so the worst clusters are sent rather than the request rejected. They
+ * arrive ranked, so this is a head, not a sample.
+ */
+export declare const MAX_SENT_FINDINGS = 50;
+export declare function platformTag(): string;
+/**
+ * Build the wire payload from ranked clusters.
+ *
+ * Every field here is derived from the journal's own skeletonized entries — this
+ * function reads counts and timings, never values. If a future journal field
+ * carries content, it must not be added to this mapping without the same
+ * scrutiny the skeleton got.
+ */
+export declare function buildReport(clusters: Cluster[], cliVersion: string, note?: string): WireReport;
+/**
+ * Render the payload for the creator to read BEFORE it is sent.
+ *
+ * This is not a summary of the payload — it is the payload, formatted. A preview
+ * that paraphrased what would be sent would be exactly the wrong thing to show
+ * someone deciding whether to send it.
+ */
+export declare function renderPayload(report: WireReport): string[];
+export interface SendResult {
+    ref: string;
+    findings: number;
+    expiresAt: string;
+}
+export declare class DXSendError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
+}
+/**
+ * POST the report. The caller has already shown the payload and had it accepted.
+ */
+export declare function postReport(apiUrl: string, pat: string, report: WireReport, fetchImpl?: typeof fetch): Promise<SendResult>;

package/dist/dx/send.js

@@ -0,0 +1,108 @@
+/**
+ * The server bounds a report at 50 findings and refuses the whole thing past
+ * that, so the worst clusters are sent rather than the request rejected. They
+ * arrive ranked, so this is a head, not a sample.
+ */
+export const MAX_SENT_FINDINGS = 50;
+/** Error classes per finding, matching the server's bound. */
+const MAX_ERROR_CLASSES = 10;
+export function platformTag() {
+    return `${process.platform}-${process.arch}`;
+}
+/**
+ * Build the wire payload from ranked clusters.
+ *
+ * Every field here is derived from the journal's own skeletonized entries — this
+ * function reads counts and timings, never values. If a future journal field
+ * carries content, it must not be added to this mapping without the same
+ * scrutiny the skeleton got.
+ */
+export function buildReport(clusters, cliVersion, note) {
+    const findings = clusters.slice(0, MAX_SENT_FINDINGS).map((c) => {
+        const classes = [
+            ...new Set(c.entries.map((e) => e.err).filter((e) => e !== null)),
+        ].slice(0, MAX_ERROR_CLASSES);
+        const f = {
+            kind: c.kind,
+            skeleton: c.skeleton,
+            calls: c.entries.length,
+            errors: c.errors,
+            spanMs: Math.max(0, Math.round(c.spanMs)),
+        };
+        if (classes.length > 0)
+            f.errorClasses = classes;
+        return f;
+    });
+    // The note rides on the first finding: it is the creator's own words about the
+    // friction they are reporting, and the report is about one sitting.
+    if (note !== undefined && note.trim() !== "" && findings.length > 0) {
+        findings[0].note = note.trim();
+    }
+    return { cliVersion, platform: platformTag(), findings };
+}
+/**
+ * Render the payload for the creator to read BEFORE it is sent.
+ *
+ * This is not a summary of the payload — it is the payload, formatted. A preview
+ * that paraphrased what would be sent would be exactly the wrong thing to show
+ * someone deciding whether to send it.
+ */
+export function renderPayload(report) {
+    const hasNote = report.findings.some((f) => f.note !== undefined && f.note !== "");
+    const lines = [
+        "This is what would be sent:",
+        "",
+        ...JSON.stringify(report, null, 2)
+            .split("\n")
+            .map((l) => `  ${l}`),
+        "",
+    ];
+    // The generated fields carry shape only. The NOTE does not, and saying
+    // otherwise above a note that may hold a path or a token would be asking the
+    // creator to consent on a false claim — the one thing this screen exists to
+    // prevent. So the sentence changes when a note is present.
+    if (hasNote) {
+        lines.push("  The generated fields carry no paths, flag values, or error messages.", "  YOUR NOTE IS SENT EXACTLY AS WRITTEN — check it for paths, URLs,", "  tokens, or customer names before sending.");
+    }
+    else {
+        lines.push("  No paths, no flag values, no error messages, and nothing about which", "  project this was.");
+    }
+    lines.push("  Your journal stays on this machine.");
+    return lines;
+}
+export class DXSendError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "DXSendError";
+    }
+}
+/**
+ * POST the report. The caller has already shown the payload and had it accepted.
+ */
+export async function postReport(apiUrl, pat, report, fetchImpl = fetch) {
+    const res = await fetchImpl(`${apiUrl}/dx-reports`, {
+        method: "POST",
+        headers: { "content-type": "application/json", authorization: `Bearer ${pat}` },
+        body: JSON.stringify(report),
+    });
+    if (!res.ok) {
+        let detail = "";
+        try {
+            const body = (await res.json());
+            detail = body.message ?? "";
+        }
+        catch {
+            // A non-JSON body is not more informative than the status.
+        }
+        if (res.status === 401) {
+            throw new DXSendError("Your access token is no longer valid — run `vincentt login`.", 401);
+        }
+        // A 400 here means the payload this CLI built failed the server's own
+        // grammar. Surfaced verbatim rather than softened: it is a bug in this CLI,
+        // and the creator is the one who can report it.
+        throw new DXSendError(detail !== "" ? detail : `The report was not accepted (${res.status}).`, res.status);
+    }
+    return (await res.json());
+}

package/dist/dx/skeleton.js

@@ -10,6 +10,83 @@
  */
 import { BOOLEAN_FLAGS } from "../cli/args.js";
 const ELIDED = "<v>";
+/**
+ * The verbs this CLI dispatches. A first bare token that is not one of these is
+ * not a verb — it is whatever the caller typed, and it must not be kept.
+ *
+ * Keeping it verbatim was a leak: an agent that mistypes
+ * `vincentt publish-acme-demo-to-prod`, fails, and retries builds a top-ranked
+ * friction cluster, so a customer's name ended up at the head of both the
+ * on-disk journal and any report built from it. Lowercase kebab-case is exactly
+ * what slugs and project names are made of, so no character-class check catches
+ * this — only a list of the verbs that actually exist.
+ */
+const KNOWN_VERBS = new Set([
+    "create",
+    "dx",
+    "feedback",
+    "init",
+    "link",
+    "login",
+    "logout",
+    "logs",
+    "network",
+    "preview",
+    "publish",
+    "relay",
+    "trace",
+    "unlink",
+    "version",
+    "whoami",
+    "help",
+]);
+/** Flags the CLI defines. An unknown `--flag` name is caller text, not signal. */
+const KNOWN_FLAGS = new Set([
+    "--allow-custom-api",
+    "--api",
+    "--console",
+    "--days",
+    "--dir",
+    "--dist",
+    "--editor",
+    "--errors",
+    "--force",
+    "--help",
+    "--json",
+    "--limit",
+    "--name",
+    "--no-install",
+    "--no-qr",
+    "--note",
+    "--org",
+    "--port",
+    "--preview",
+    "--restart",
+    "--send",
+    "--session",
+    "--since",
+    "--slug",
+    "--stop",
+    "--template",
+    "--tester",
+    "--timeout",
+    "--verbose",
+    "--version",
+    "--viewer",
+    "--wait",
+    "--watch",
+    "--yes",
+]);
+/**
+ * Placeholders for tokens the CLI does not recognize. Angle brackets cannot
+ * appear in a token the caller typed, so a caller cannot forge one.
+ *
+ * A mistyped verb still produces a finding — it clusters under `<verb>`, which
+ * is itself worth seeing (repeated unknown verbs mean an agent is guessing at a
+ * command that should exist).
+ */
+const UNKNOWN_VERB = "<verb>";
+const UNKNOWN_FLAG = "--<flag>";
 /**
  * Normalize an argv into `verb --flag=<v> <v>` form — the key a retry cluster
  * groups on. Two calls that differ only in their values share a skeleton, which
@@ -20,12 +97,18 @@ export function skeleton(args) {
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (!a.startsWith("-")) {
-            // The verb is the first bare token and is kept verbatim; every later
-            // positional is a value (a slug, an id, a path) and is elided.
-            out.push(out.length === 0 ? a : ELIDED);
+            // The first bare token is the verb — kept only when it is one we actually
+            // dispatch. Every later positional is a value (a slug, an id, a path).
+            if (out.length === 0) {
+                out.push(KNOWN_VERBS.has(a) ? a : UNKNOWN_VERB);
+            }
+            else {
+                out.push(ELIDED);
+            }
             continue;
         }
-        const name = a.split("=")[0];
+        const rawName = a.split("=")[0];
+        const name = KNOWN_FLAGS.has(rawName) ? rawName : UNKNOWN_FLAG;
         if (BOOLEAN_FLAGS.has(a)) {
             out.push(name);
             continue;
@@ -47,7 +130,7 @@ export function verbOf(args) {
     for (let i = 0; i < args.length; i++) {
         const a = args[i];
         if (!a.startsWith("-"))
-            return a;
+            return KNOWN_VERBS.has(a) ? a : UNKNOWN_VERB;
         if (!BOOLEAN_FLAGS.has(a) && !a.includes("="))
             i++;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",