@vincentt-xr/cli 0.14.1 → 0.15.0

package/dist/cli/index.js

@@ -1033,6 +1033,44 @@ async function dx() {
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
     }, options);
 }
+// ---- report -----------------------------------------------------------------
+/**
+ * `vincentt report "<what went wrong>"`.
+ *
+ * Shares `dx --send`'s consent arms, auth and disclosure screen deliberately —
+ * it is the same act of transmitting, differing only in what is carried. What it
+ * does NOT share is the friction precondition: this path never consults the
+ * journal for clusters, because the report it sends is about something the
+ * journal could not detect.
+ */
+async function report() {
+    const { parseReportOptions, reportCommand } = await import("../dx/report.js");
+    const { postObservationReport } = await import("../dx/reportIo.js");
+    const now = Date.now();
+    const interactive = () => Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const enablement = await loadEnablement(now);
+    process.exitCode = await reportCommand({
+        print: (l) => console.log(l),
+        now: () => now,
+        cliVersion,
+        // Best-effort: the context line is a courtesy, and a journal that is off or
+        // unreadable must never block someone from sending what they typed.
+        entries: () => {
+            try {
+                return readJournal();
+            }
+            catch {
+                return [];
+            }
+        },
+        auth: dxAuth,
+        post: (apiUrl, pat, r) => postObservationReport(apiUrl, pat, r),
+        confirm: (q) => stdinConfirm()(`${q} [y/N] `, false),
+        interactive,
+        enablement: () => enablement,
+        accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+    }, parseReportOptions(argv.slice(1)));
+}
 // ---- assets (f5) ------------------------------------------------------------
 /**
  * `vincentt assets <search|show|add>` — the CLI's FIRST nested subcommand group,
@@ -1192,6 +1230,8 @@ async function main() {
             return assets();
         case "dx":
             return dx();
+        case "report":
+            return report();
     }
 }
 // Every invocation is journaled here, at the one site that sees all of them —

package/dist/cli/usage-text.js

@@ -100,7 +100,11 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `                       Asks you to confirm in your terminal. Stays on until you\n` +
     `                       disable it, and is shown on \`vincentt dx\` and\n` +
     `                       \`vincentt version\` while on.\n` +
-    `  dx disable         Turn that off again.\n\n` +
+    `  dx disable         Turn that off again.\n` +
+    `  report "<text>"    Tell us something went wrong, in your own words.\n` +
+    `                       For when nothing failed but something looked wrong —\n` +
+    `                       the case \`dx --send\` cannot see. Shows the exact\n` +
+    `                       payload and asks first. [--no-context] [--yes]\n\n` +
     `Common options: --dir <path> (where to work, default cwd — for \`create\` this is\n` +
     `                              the PARENT of the new folder, not the folder itself)\n` +
     `                --allow-custom-api  honor a binding's apiUrl override\n`;

package/dist/cli/verb-surface.d.ts

@@ -1,4 +1,4 @@
-export declare const PINNED_VERBS: readonly ["version", "login", "logout", "whoami", "init", "create", "link", "unlink", "publish", "preview", "logs", "network", "trace", "feedback", "relay", "assets", "dx", "projects"];
+export declare const PINNED_VERBS: readonly ["version", "login", "logout", "whoami", "init", "create", "link", "unlink", "publish", "preview", "logs", "network", "trace", "feedback", "relay", "assets", "dx", "projects", "report"];
 export type PinnedVerb = (typeof PINNED_VERBS)[number];
 export declare const VERB_HANDLERS: {
     readonly version: true;
@@ -19,6 +19,7 @@ export declare const VERB_HANDLERS: {
     readonly assets: true;
     readonly dx: true;
     readonly projects: true;
+    readonly report: true;
 };
 export type DispatchVerb = keyof typeof VERB_HANDLERS;
 export declare function resolveVerb(cmd: string | undefined): DispatchVerb | undefined;

package/dist/cli/verb-surface.js

@@ -12,6 +12,10 @@ export const PINNED_VERBS = [
     // Appended: a read-only listing. Nothing above was renamed or removed, which
     // is the whole of what B-F3-8 pins — an addition is always permitted.
     "projects",
+    // Appended: the hand-written report. `dx --send` transmits DETECTED friction
+    // and refuses when it finds none; this carries what a creator TYPED, which is
+    // the half a journal keyed on exit codes cannot see. Also an addition.
+    "report",
 ];
 // The dispatch's verb set, as data. `main()` switches over this, so the two can
 // never disagree: a verb added to the CLI is a key added here, and QA-AHG-01
@@ -35,6 +39,7 @@ export const VERB_HANDLERS = {
     assets: true,
     dx: true,
     projects: true,
+    report: true,
 };
 // Answers "is this a verb this CLI accepts" without running it. The
 // console-redirect strings are NOT accepted here: they reach their explanation

package/dist/dx/report.d.ts

@@ -0,0 +1,102 @@
+/**
+ * `vincentt report "<what went wrong>"` — the creator's own words, sent.
+ *
+ * This exists because of a gap `dx --send` could not close. That command reports
+ * DETECTED friction: it reads the journal, finds clusters of retries and errors,
+ * and refuses when it finds none. But the friction a creator most wants to report
+ * is routinely the kind the journal cannot see — a command that exits 0 and puts
+ * the wrong thing on screen produces no error, no retry and no cluster. Asked to
+ * carry a note about one, `--send` had nothing to attach it to and said "no
+ * friction detected — nothing to send", which is the tool contradicting the
+ * person using it.
+ *
+ * So the note stops being a rider on a finding and becomes the payload. An
+ * observation carries no counts because there is nothing to count.
+ *
+ * The consent model is INHERITED, not relaxed. Sending is still gated on the
+ * same three arms as `--send` (a terminal, a local `dx enable`, or an account
+ * grant), the payload is still shown in full before it goes, and a note is still
+ * shown under a warning that it is transmitted exactly as written. This verb
+ * removes a refusal; it does not open a new door.
+ */
+import type { Enablement } from "./enablement.js";
+import type { JournalEntry } from "./journal.js";
+/** An observation as it goes on the wire. Mirrors the API's dxObservationRequest. */
+export interface WireObservation {
+    note: string;
+    context?: string;
+}
+export interface WireObservationReport {
+    cliVersion: string;
+    platform: string;
+    findings: never[];
+    observations: WireObservation[];
+}
+/** Matches the server's MaxDXNote. Checked here so a refusal costs no round trip. */
+export declare const MAX_NOTE = 2000;
+export interface ReportOptions {
+    note: string;
+    yes: boolean;
+    /** Suppress the context line — for a creator who would rather send the note alone. */
+    noContext: boolean;
+}
+/**
+ * Parse `vincentt report <note>`.
+ *
+ * The note is POSITIONAL and is read as the single argument after the verb,
+ * matching how `dx --note` already reads its own. A flag form would be worse
+ * here: the note routinely contains spaces and quotes, and the failure mode of a
+ * half-quoted flag value is a note that silently loses its tail.
+ */
+export declare function parseReportOptions(args: string[]): ReportOptions;
+/**
+ * The skeleton of the last command this creator ran, for context.
+ *
+ * Read from the journal rather than reconstructed, so it carries the same
+ * value-elided shape the journal already enforces — this is the one field on an
+ * observation not typed by the creator, and it must not become the field that
+ * leaks a path. The `report` invocation itself is excluded: the interesting
+ * command is the one BEFORE this one.
+ *
+ * Absent is a normal answer. The journal may be off, empty, or hold nothing but
+ * this run, and none of those is a reason to refuse to send what someone typed.
+ */
+export declare function lastContext(entries: JournalEntry[]): string | undefined;
+export declare function buildObservationReport(note: string, cliVersion: string, context?: string): WireObservationReport;
+/**
+ * Render the payload for the creator to read BEFORE it is sent.
+ *
+ * As in `send.ts`, this is the payload formatted, not a summary of it. The note
+ * warning is unconditional here, where it is conditional there: an observation
+ * is ALWAYS a note, so there is no path through this screen that does not need
+ * it.
+ */
+export declare function renderObservation(report: WireObservationReport): string[];
+export interface ReportDeps {
+    print: (line: string) => void;
+    now: () => number;
+    cliVersion: () => string;
+    entries: () => JournalEntry[];
+    auth: () => Promise<{
+        apiUrl: string;
+        pat: string;
+    } | undefined>;
+    post: (apiUrl: string, pat: string, report: WireObservationReport) => Promise<{
+        ref: string;
+        expiresAt: string;
+    }>;
+    confirm: (question: string) => Promise<boolean>;
+    interactive: () => boolean;
+    enablement?: () => Enablement;
+    accountConsent?: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<Enablement>;
+}
+/**
+ * `vincentt report`.
+ *
+ * Same order as `dx --send`, for the same reason: build the payload, SHOW it,
+ * ask, and only then send.
+ */
+export declare function reportCommand(deps: ReportDeps, options: ReportOptions): Promise<number>;

package/dist/dx/report.js

@@ -0,0 +1,161 @@
+import { enablementLine } from "./enablement.js";
+import { DXSendError, platformTag } from "./send.js";
+/** Matches the server's MaxDXNote. Checked here so a refusal costs no round trip. */
+export const MAX_NOTE = 2000;
+/**
+ * Parse `vincentt report <note>`.
+ *
+ * The note is POSITIONAL and is read as the single argument after the verb,
+ * matching how `dx --note` already reads its own. A flag form would be worse
+ * here: the note routinely contains spaces and quotes, and the failure mode of a
+ * half-quoted flag value is a note that silently loses its tail.
+ */
+export function parseReportOptions(args) {
+    const positionals = args.filter((a) => !a.startsWith("-"));
+    return {
+        note: positionals[0] ?? "",
+        yes: args.includes("--yes"),
+        noContext: args.includes("--no-context"),
+    };
+}
+/**
+ * The skeleton of the last command this creator ran, for context.
+ *
+ * Read from the journal rather than reconstructed, so it carries the same
+ * value-elided shape the journal already enforces — this is the one field on an
+ * observation not typed by the creator, and it must not become the field that
+ * leaks a path. The `report` invocation itself is excluded: the interesting
+ * command is the one BEFORE this one.
+ *
+ * Absent is a normal answer. The journal may be off, empty, or hold nothing but
+ * this run, and none of those is a reason to refuse to send what someone typed.
+ */
+export function lastContext(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.verb === "report")
+            continue;
+        return e.skel !== "" ? e.skel : undefined;
+    }
+    return undefined;
+}
+export function buildObservationReport(note, cliVersion, context) {
+    const o = { note: note.trim() };
+    if (context !== undefined && context !== "")
+        o.context = context;
+    return {
+        cliVersion,
+        platform: platformTag(),
+        // Always present and always empty: the server accepts a report with either
+        // carrier, and sending the key explicitly says "no findings" rather than
+        // leaving the shape to be inferred from an absent field.
+        findings: [],
+        observations: [o],
+    };
+}
+/**
+ * Render the payload for the creator to read BEFORE it is sent.
+ *
+ * As in `send.ts`, this is the payload formatted, not a summary of it. The note
+ * warning is unconditional here, where it is conditional there: an observation
+ * is ALWAYS a note, so there is no path through this screen that does not need
+ * it.
+ */
+export function renderObservation(report) {
+    return [
+        "This is what would be sent:",
+        "",
+        ...JSON.stringify(report, null, 2)
+            .split("\n")
+            .map((l) => `  ${l}`),
+        "",
+        "  YOUR NOTE IS SENT EXACTLY AS WRITTEN — check it for paths, URLs,",
+        "  tokens, or customer names before sending.",
+        "  The context line is the shape of your last command, with values removed.",
+        "  Your journal stays on this machine.",
+    ];
+}
+/**
+ * `vincentt report`.
+ *
+ * Same order as `dx --send`, for the same reason: build the payload, SHOW it,
+ * ask, and only then send.
+ */
+export async function reportCommand(deps, options) {
+    const note = options.note.trim();
+    if (note === "") {
+        deps.print('Usage: vincentt report "what went wrong"');
+        deps.print("");
+        deps.print("  Sends one note about the tooling to Vincentt. Use it when");
+        deps.print("  something looked wrong but no command failed.");
+        return 1;
+    }
+    if ([...note].length > MAX_NOTE) {
+        // Refused here rather than truncated, matching every other bound in this
+        // feature: silently sending half of what someone wrote makes the report a
+        // worse record than not having it.
+        deps.print(`That note is longer than ${MAX_NOTE} characters. Please shorten it.`);
+        return 1;
+    }
+    // The gate, inherited from `dx --send` verbatim. An agent composing a note and
+    // confirming it with --yes on a machine nobody granted is the case this stops.
+    const localEnablement = deps.enablement?.() ?? { enabled: false };
+    const interactive = deps.interactive();
+    const auth = await deps.auth();
+    let accountEnablement = { enabled: false };
+    if (!interactive && !localEnablement.enabled && auth !== undefined) {
+        try {
+            accountEnablement = (await deps.accountConsent?.(auth)) ?? { enabled: false };
+        }
+        catch {
+            // Fail closed. An unreachable API never authorizes a send.
+            accountEnablement = { enabled: false };
+        }
+    }
+    const enablement = localEnablement.enabled
+        ? localEnablement
+        : accountEnablement;
+    if (!interactive && !enablement.enabled) {
+        deps.print("Sending a report needs consent that has not been given on this account.");
+        deps.print("`vincentt dx enable` opens the Vincentt console so you can allow it.");
+        deps.print("It takes one click, and it works from here.");
+        return 1;
+    }
+    if (auth === undefined) {
+        deps.print("Not signed in. Run `vincentt login` to send a report.");
+        return 1;
+    }
+    const context = options.noContext ? undefined : lastContext(deps.entries());
+    const report = buildObservationReport(note, deps.cliVersion(), context);
+    const unattended = !interactive && enablement.enabled;
+    if (unattended) {
+        const line = enablementLine(enablement, deps.now());
+        if (line !== undefined) {
+            deps.print("");
+            deps.print(`${line}. Not asking.`);
+        }
+    }
+    for (const l of renderObservation(report))
+        deps.print(l);
+    deps.print("");
+    // The ask is skipped unattended or under --yes; the SHOW above never is.
+    if (!unattended && !options.yes) {
+        if (!(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(`Sent. Reference ${res.ref}.`);
+        deps.print("Thank you — this is the kind of thing we cannot detect on our own.");
+        return 0;
+    }
+    catch (err) {
+        if (err instanceof DXSendError) {
+            deps.print(err.message);
+            return 1;
+        }
+        throw err;
+    }
+}

package/dist/dx/reportIo.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The network half of `vincentt report`, kept out of `report.ts` so the command
+ * itself stays a pure function of its deps and needs no socket to test.
+ *
+ * It posts to the SAME endpoint `dx --send` does. An observation is not a
+ * different kind of thing from a report — it is a report whose carrier is a
+ * sentence rather than a cluster — and giving it its own route would have meant
+ * a second consent path, a second rate limiter and a second TTL to keep in step
+ * with the first.
+ */
+import type { WireObservationReport } from "./report.js";
+export interface ObservationResult {
+    ref: string;
+    expiresAt: string;
+}
+export declare function postObservationReport(apiUrl: string, pat: string, report: WireObservationReport, fetchImpl?: typeof fetch): Promise<ObservationResult>;

package/dist/dx/reportIo.js

@@ -0,0 +1,29 @@
+import { DXSendError } from "./send.js";
+export async function postObservationReport(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);
+        }
+        if (res.status === 429) {
+            // Distinguished from the generic path because it is the one refusal the
+            // creator can act on by simply waiting, and a bare "not accepted" would
+            // read as their report being rejected on its merits.
+            throw new DXSendError("Too many reports from this account just now — try again shortly.", 429);
+        }
+        throw new DXSendError(detail !== "" ? detail : `The report was not accepted (${res.status}).`, res.status);
+    }
+    return (await res.json());
+}

package/package.json

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