@vincentt-xr/cli 0.21.0 → 0.23.0

package/MIGRATION.md

@@ -3,6 +3,32 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.23.0
+
+required: false
+No action required. New verb `vincentt editor`, which hands the project to the Vincentt Editor desktop app.
+- `vincentt editor` (macOS 14 or later, no account) finds `Vincentt Editor.app` in `/Applications`, then `~/Applications`, checks it is signed by Vincentt, hands it the project folder and exits 0 with `✓ Sent <name> to Vincentt Editor.` It does not wait for the app. The app is a separate download from https://vincentt.studio/editor; the CLI installs no editor binary and has no port option for it.
+- It exits 1, last line `Nothing was opened.`, when the app is not installed, the installed copy is not signed by Vincentt, the Mac is not on macOS 14 or later, or another copy of the app is running from a different folder.
+- `vincentt editor --json` prints one `vincentt.editor-open/1` object: `{"schema","handedOff":true,"project","app","appVersion"}`, or `handedOff: false` with a `reason` (`not_installed`, `bad_signature`, `unsupported_os`, `other_copy_running`, `open_failed`) and, where known, `app` and `detail`. The sentence goes to stderr.
+- `vincentt editor --selection [--json]` prints what is selected in the editor (`vincentt.editor-selection/1`), and `vincentt editor --status --json` the editor's state for the folder (`vincentt.editor-state/1`, including `app.lastOpen`). Both work on any OS and exit 1, with one JSON object still on stdout, when no editor is running for the folder.
+- In `--status --json`, `app` is always `{"version","lastOpen"}`; when no editor is running, `lastOpen` is reported only for a folder this machine handed over with `vincentt editor`, from a state file written after that hand-off, and is `null` otherwise.
+- The CLI keeps those hand-offs in `~/.vincentt/editor-handoffs.json`, as a hash of each folder's path and a time, never the path itself. A file written in a newer format than this CLI reads is refused with an upgrade line on stderr and nothing on stdout.
+
+## 0.22.0
+
+required: false
+No action required. Behaviour that changed:
+- `vincentt dx enable` at a terminal now asks `Allow unattended reports on your account? [y/N]` and, on `y`, records the grant on your Vincentt account first, then sets this machine. Success reads `Enabled for your account. Reports may now be sent without a prompt from any machine signed in to it.`
+- If the account does not record the grant, `vincentt dx enable` changes nothing and exits 1 with `✗ Vincentt did not record your consent.`, `✗ Too many consent changes. Wait a minute and try again.`, or `✗ Could not reach Vincentt to record your consent.` A refused sign-in exits 4 and a too-old CLI exits 5, as on other verbs.
+- Unattended `vincentt dx --send` and `vincentt report` now check the account first. An account grant sends; an account that is not granted refuses (exit 1) and clears this machine's setting, so turning reports off in the console or on another machine reaches this one. This machine's setting is used on its own only when the account cannot be reached. An interactive session still asks and makes no account check.
+- The `Unattended send: ENABLED since <day> (<n> days)` line now ends with where the answer came from: `· granted from the CLI`, `· granted in the console`, `· on your account`, or `· this machine (account not checked)`. `vincentt dx` and `vincentt version` check the account for up to 3 seconds first; `vincentt version` never fails because of that check.
+- `vincentt dx --json` adds `dxConsent`: `{"state": "on" | "off" | "unknown", "checked": "account" | "machine", "at"?, "via"?}`. `dxSendEnabled` and `dxSendEnabledAt` still describe this machine's setting.
+- `vincentt preview` has a new ending: when the preview server answers the tunnel with a reply this CLI cannot accept, the preview ends once with `✗ Preview stopped: the preview server sent an invalid reply. Update the CLI or try again later.` (exit 1) instead of reconnecting every few seconds indefinitely. The screen names the upgrade command and `vincentt preview`.
+- `vincentt publish` refuses the whole publish, listing the files, when a folder in the build output turns into a link to somewhere outside it while publish reads it. Let the build finish, then publish again.
+- `vincentt publish` refuses to upload when the platform's upload link does not carry the checksum publish computed for that file; nothing is sent, and the screen names the file.
+- A folder or file in the build output that publish cannot read now ends the publish with the "changed while publish was reading it" screen naming the path inside the build output, instead of a raw error message holding the full path.
+- File names printed on publish refusal screens show bidirectional and direction-mark characters as visible `\uXXXX` escapes.
+
 ## 0.21.0
 
 required: false

package/dist/cli/args.js

@@ -42,6 +42,8 @@ export const BOOLEAN_FLAGS = new Set([
     "--yes",
     "--download",
     "--no-context",
+    "--selection",
+    "--status",
     "--help",
     "-h",
 ]);

package/dist/cli/index.js

@@ -29,7 +29,7 @@ import { listProjectsCommand } from "../lib/listProjects.js";
 import { initCommand } from "../lib/initCommand.js";
 import { linkCommand, printUnreachable, unlinkCommand } from "../lib/projects.js";
 import { whoamiCommand } from "../lib/whoami.js";
-import { renderVersion, versionReport } from "../lib/version.js";
+import { renderVersion, VERSION_ACCOUNT_TIMEOUT_MS, versionReport, } from "../lib/version.js";
 import { diagQuery, diagRead, previewStart, previewStop, previewStopSignal, projectCreate, } from "../lib/lifecycle.js";
 import { publishCommand } from "../publish/command.js";
 import { stdinAsk, stdinConfirm } from "../publish/prompt.js";
@@ -53,7 +53,7 @@ import * as feedbackCopy from "../lib/feedbackCopy.js";
 import { record as recordInvocation } from "../dx/journal.js";
 import { dxDisableCommand, dxEnableCommand, dxSendCommand, parseDxOptions, runDx, sinceUsageLines, } from "../dx/command.js";
 import { httpConsentBackend, runConsentInBrowser } from "../dx/consent.js";
-import { DX_UNATTENDED_SUNSET, loadEnablement } from "../dx/enablement.js";
+import { DX_UNATTENDED_SUNSET, loadEnablement, resolveConsentView, } from "../dx/enablement.js";
 import { journalEnabled, journalPath, readJournal } from "../dx/journal.js";
 import { postReport } from "../dx/send.js";
 import { nudgeFor } from "../dx/nudge.js";
@@ -1139,14 +1139,22 @@ function cliVersion() {
     }
 }
 async function version() {
+    const now = Date.now();
     const report = await versionReport(projectDir(), {
         cliVersion: cliVersion(),
         allowCustomApi: has("--allow-custom-api"),
+        consent: {
+            auth: dxAuth,
+            readAccount: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now, VERSION_ACCOUNT_TIMEOUT_MS),
+            clearLocal: () => writeDxEnablement(undefined),
+        },
     });
     for (const line of renderVersion(report))
         console.log(line);
 }
 // ---- dx ---------------------------------------------------------------------
+/** The account bound on `vincentt dx` (f7 Scenario 3c); the send gate uses the default. */
+const DX_ACCOUNT_TIMEOUT_MS = 3_000;
 /**
  * The API host + PAT for a dx call, or undefined when signed out.
  *
@@ -1197,6 +1205,7 @@ async function dx() {
                     onProgress: (l) => console.log(l),
                 });
             },
+            grantAccountConsent: (auth) => consent.grant(auth.apiUrl, auth.pat, now),
             revokeAccountConsent: (auth) => consent.revoke(auth.apiUrl, auth.pat),
         };
         process.exitCode = options.enable
@@ -1214,7 +1223,15 @@ async function dx() {
     // relaxation, not throw through it.
     const enablement = await loadEnablement(now);
     if (!options.send) {
-        process.exitCode = runDx(argv, (l) => console.log(l), () => enablement);
+        // The report tail and `dxConsent` read the account first, bounded at 3 s.
+        const view = await resolveConsentView({
+            auth: await dxAuth(),
+            readAccount: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now, DX_ACCOUNT_TIMEOUT_MS),
+            local: () => enablement,
+            clearLocal: () => writeDxEnablement(undefined),
+            timeoutMs: DX_ACCOUNT_TIMEOUT_MS,
+        });
+        process.exitCode = runDx(argv, (l) => console.log(l), () => view.local, () => view);
         return;
     }
     // `--send` is the one path out of this machine, so it resolves auth the way
@@ -1231,10 +1248,9 @@ async function dx() {
         confirm: (q) => stdinConfirm()(`${q} [y/N] `, false),
         interactive,
         enablement: () => enablement,
-        // The third arm: the account-wide grant, read from /me. Consulted only when the
-        // first two have not already allowed the send, and allowed to throw — a /me that
-        // is unreachable falls back to the other two arms rather than blocking.
+        // The account decides when it answers; never read on an interactive session.
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+        clearEnablement: () => writeDxEnablement(undefined),
         // `--dir`-or-cwd, the same resolution every other verb uses, so `--dir`
         // works on a send as it does everywhere else.
         cwd: projectDir(),
@@ -1276,6 +1292,7 @@ async function report() {
         interactive,
         enablement: () => enablement,
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+        clearEnablement: () => writeDxEnablement(undefined),
         // `--dir`-or-cwd, the same resolution every other verb uses, so `--dir`
         // works on a report as it does everywhere else.
         cwd: projectDir(),
@@ -1429,6 +1446,25 @@ async function domain() {
         yes: has("--yes"),
     });
 }
+// ---- Vincentt Editor (f21) --------------------------------------------------
+/** Why `editor` exited 1, for the journal (one word from a closed set, B-F7-1). */
+let editorReason;
+/**
+ * `vincentt editor` hands the project folder to the installed Vincentt Editor app and exits.
+ * Needs no account and makes no network call.
+ */
+async function editor() {
+    const { editorVerb } = await import("../editor/launcher.js");
+    // The launcher's parser accepts `--dir=<path>`, so the folder it names is the one handed over.
+    const dir = flag("--dir") ?? valueOfEqualsFlag(argv, "--dir");
+    const run = await editorVerb(argv.slice(1), dir ? path.resolve(dir) : process.cwd());
+    for (const l of run.stdout)
+        console.log(l);
+    for (const l of run.stderr)
+        console.error(l);
+    editorReason = run.reason;
+    process.exitCode = run.exitCode;
+}
 // ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
@@ -1532,6 +1568,8 @@ async function main() {
             return outdated();
         case "domain":
             return domain();
+        case "editor":
+            return editor();
     }
 }
 // Every invocation is journaled here, at the one site that sees all of them —
@@ -1539,6 +1577,8 @@ async function main() {
 // 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();
+/** Verbs that make no network request, footnotes included: their footnotes never refresh. */
+const NO_NETWORK_VERBS = new Set(["editor"]);
 function journal(exitCode, error) {
     recordInvocation({
         argv,
@@ -1548,6 +1588,7 @@ function journal(exitCode, error) {
         endedAt: Date.now(),
         exitCode,
         error,
+        reason: editorReason,
     });
     // 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
@@ -1580,7 +1621,7 @@ function journal(exitCode, error) {
             for (const l of updateNotice(cliVersion(), cached?.latest))
                 console.error(l);
         }
-        if (!isFresh(cached, Date.now()))
+        if (!isFresh(cached, Date.now()) && !NO_NETWORK_VERBS.has(verbOf(argv)))
             refreshUpdateCache();
     }
     catch {
@@ -1625,7 +1666,8 @@ async function announceBehind() {
                 console.error(l);
             }
         }
-        if (needsRefresh(loadReleaseCache(), Date.now())) {
+        if (needsRefresh(loadReleaseCache(), Date.now()) &&
+            !NO_NETWORK_VERBS.has(verbOf(argv))) {
             refreshReleaseCache({
                 apiUrl: machineApiUrl(await loadMachineConfig()),
                 now: () => Date.now(),

package/dist/cli/usage-text.js

@@ -60,7 +60,16 @@ export const USAGE_TEXT = `Vincentt CLI: the local-first AR dev loop\n\n` +
     `                       [--no-qr] [--stop]\n` +
     `                       Runs dev.command and forwards dev.port from vincentt.json,\n` +
     `                       else npm run dev on a free port (passed as PORT).\n` +
-    `                       Re-running prints the live link; --restart mints a new one.\n\n` +
+    `                       Re-running prints the live link; --restart mints a new one.\n` +
+    `  editor             Hand this project to the Vincentt Editor app (macOS 14 or\n` +
+    `                       later) and exit. Opens only the app in /Applications or\n` +
+    `                       ~/Applications, signed by Vincentt. No account needed.\n` +
+    `                       [--json] one vincentt.editor-open/1 object; handedOff says\n` +
+    `                       the folder reached the app, not that it opened.\n` +
+    `  editor --selection  The object selected in the editor, with its source\n` +
+    `                       location and values  [--json]\n` +
+    `  editor --status --json  The editor's state for this folder, including\n` +
+    `                       app.lastOpen. Both reads exit 1 when no editor runs here.\n\n` +
     // f16. HELP TEACHES THE CANONICAL VERBS ONLY: `add` and `remove` are accepted
     // as silent aliases and are deliberately ABSENT here, because help, docs and
     // every error string are where the vocabulary is actually taught. Listing the

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", "report", "outdated", "domain"];
+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", "outdated", "domain", "editor"];
 export type PinnedVerb = (typeof PINNED_VERBS)[number];
 export declare const VERB_HANDLERS: {
     readonly version: true;
@@ -22,6 +22,7 @@ export declare const VERB_HANDLERS: {
     readonly report: true;
     readonly outdated: true;
     readonly domain: true;
+    readonly editor: true;
 };
 export type DispatchVerb = keyof typeof VERB_HANDLERS;
 export declare function resolveVerb(cmd: string | undefined): DispatchVerb | undefined;

package/dist/cli/verb-surface.js

@@ -26,6 +26,10 @@ export const PINNED_VERBS = [
     // collection verb. `domains` is routed to an answer, not accepted as a verb —
     // see domainVerbRedirect. An addition, so B-F3-8 permits it.
     "domain",
+    // Appended (f21): the Vincentt Editor launcher. `editor`, not `edit`: an agent
+    // reading "vincentt edit" would take it as a command that changes files. An
+    // addition, so B-F3-8 permits it.
+    "editor",
 ];
 // 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
@@ -52,6 +56,7 @@ export const VERB_HANDLERS = {
     report: true,
     outdated: true,
     domain: true,
+    editor: 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/command.d.ts

@@ -1,5 +1,5 @@
-import type { ConsentDecision } from "./consent.js";
-import type { Enablement } from "./enablement.js";
+import type { ConsentDecision, GrantResult } from "./consent.js";
+import type { AccountRead, ConsentView, Enablement } from "./enablement.js";
 import type { JournalEntry, JournalWindow } from "./journal.js";
 import type { WireReport } from "./send.js";
 import { type BuiltWith } from "../platform/resolve.js";
@@ -11,10 +11,15 @@ export interface DxDeps {
     enabled: () => boolean;
     path: () => string;
     /**
-     * Durable unattended-send state. Optional so the many callers that only read
-     * the journal need not resolve it; absent reads as not enabled.
+     * This machine's copy of the grant (the local flag). Optional so the many callers that
+     * only read the journal need not resolve it; absent reads as not enabled.
      */
     enablement?: () => Enablement;
+    /**
+     * The account-first answer the report tail and `dxConsent` show. Absent falls back to
+     * the local flag, reported as checked on this machine only.
+     */
+    consentView?: () => ConsentView;
 }
 /** How far back a report looks. */
 export interface DxWindow {
@@ -53,7 +58,7 @@ export declare function sinceUsageLines(raw: string): 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, enablement?: () => Enablement): number;
+export declare function runDx(args: string[], print: (line: string) => void, enablement?: () => Enablement, consentView?: () => ConsentView): number;
 export interface DxEnableDeps {
     print: (line: string) => void;
     now: () => number;
@@ -89,6 +94,14 @@ export interface DxEnableDeps {
      * no socket, no browser, and no clock to test.
      */
     consentInBrowser?: () => Promise<ConsentDecision>;
+    /**
+     * POST /me/dx-consent with the PAT, on the terminal path. Rejects only with the version
+     * refusal or the sign-in error; every other outcome is a GrantResult.
+     */
+    grantAccountConsent?: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<GrantResult>;
     /**
      * DELETE /me/dx-consent. Used only by `disable`, and allowed to throw — the caller
      * treats a network failure as "local revoke still stands", never as a reason to leave
@@ -103,11 +116,13 @@ export interface DxEnableDeps {
  * `vincentt dx enable` — grant durable permission to send DX reports without asking
  * first.
  *
- * TWO PATHS, and which one runs is decided by whether there is a terminal to ask in:
+ * TWO PATHS to ONE account grant, and which one runs is decided by whether there is a
+ * terminal to ask in:
  *
- *   - At a TTY: the original terminal prompt, unchanged. A person is already here and
- *     can read the disclosure where they stand; sending them to a browser would be
- *     ceremony.
+ *   - At a TTY: the terminal prompt. A person is already here and can read the
+ *     disclosure where they stand; sending them to a browser would be ceremony. On `y`
+ *     the CLI POSTs /me/dx-consent with the PAT, and writes the local flag only after
+ *     the account recorded the grant.
  *   - With no TTY: the BROWSER path. This is the case the feature exists for — a
  *     creator driving the CLI through a coding agent has no terminal, so the old code
  *     refused and the flow dead-ended. It now opens the console, where a human can
@@ -130,8 +145,8 @@ export declare function dxEnableCommand(deps: DxEnableDeps, sunset: number): Pro
  * Clears BOTH local keys AND revokes the account grant when there is a PAT to do it
  * with. Both halves are needed: a creator who runs `disable` means "stop sending", and
  * clearing only the local flag would leave the account grant standing, so the very next
- * `--send` would be authorized by arm (c) and the command would appear not to have
- * worked.
+ * `--send` would be authorized by the account and the command would appear not to
+ * have worked.
  *
  * ORDER IS DELIBERATE: local first, network second. The local clear is the one that
  * cannot fail and the one that stops THIS machine, which is the machine the creator is
@@ -168,18 +183,19 @@ export interface DxSendDeps extends DxDeps {
      * convenience, not authorization.
      */
     interactive: () => boolean;
-    /** Durable unattended-send state, read strictly. Absent reads as not enabled. */
+    /** This machine's flag, read strictly. Absent reads as not enabled. */
     enablement?: () => Enablement;
     /**
-     * The ACCOUNT's consent, read from GET /me. The third arm of the gate.
-     *
-     * Allowed to throw, and its throw is not fatal — see the gate below. Absent (the dep
-     * not wired at all) reads as not consented, never as "unknown, so allow".
+     * The ACCOUNT's consent, read from GET /me. Allowed to throw; a throw reads as
+     * unreadable. Absent reads as unreadable too: it can only let a valid local flag stand,
+     * never authorize on its own.
      */
     accountConsent?: (auth: {
         apiUrl: string;
         pat: string;
-    }) => Promise<Enablement>;
+    }) => Promise<AccountRead>;
+    /** Clears this machine's flag when the account answers "not granted". */
+    clearEnablement?: () => Promise<unknown>;
     /**
      * The version set. Injectable so a fixed set — or a REJECTING promise, the arm
      * proving a fault omits — can be driven with no filesystem. Defaults to the one
@@ -188,6 +204,46 @@ export interface DxSendDeps extends DxDeps {
     builtWith?: () => Promise<BuiltWith | undefined>;
     cwd?: string;
 }
+/** What the send gate needs. `dx --send` and `report` both satisfy it. */
+export interface SendGateDeps {
+    interactive: () => boolean;
+    enablement?: () => Enablement;
+    accountConsent?: (auth: {
+        apiUrl: string;
+        pat: string;
+    }) => Promise<AccountRead>;
+    clearEnablement?: () => Promise<unknown>;
+}
+export type SendGate = {
+    arm: "interactive";
+} | {
+    arm: "unattended";
+    enablement: Enablement;
+} | {
+    arm: "refused";
+};
+/**
+ * The one consent gate both send paths call (f7 Scenario 3), checked in order:
+ *
+ *   1. an interactive session → ask, then send. No /me read at all, so a creator at their
+ *      own terminal is never blocked by an API being slow or down.
+ *   2. signed in and GET /me answers: a strict grant sends (source: account); any other
+ *      200 clears this machine's flag and refuses.
+ *   3. /me cannot be read and this machine's flag is valid → send (source: machine).
+ *
+ * An unreadable /me never authorizes by itself; it only lets an existing local flag stand.
+ */
+export declare function gateSend(deps: SendGateDeps, auth: {
+    apiUrl: string;
+    pat: string;
+} | undefined): Promise<SendGate>;
+/**
+ * The gate's refusal. It NAMES the enabling command: a refusal is an answer to a
+ * command the caller typed, which makes it SOLICITED output — the prohibition is on
+ * UNBIDDEN output instructing a caller. A refusal naming nothing leaves a human at
+ * exit 1 with no path forward, for no security gain.
+ */
+export declare const SEND_REFUSAL_LINES: readonly string[];
 /**
  * `vincentt dx --send`.
  *
@@ -195,6 +251,6 @@ export interface DxSendDeps extends DxDeps {
  * who cannot see what leaves their machine before it leaves has not agreed to
  * anything:
  *
- *     friction → GATE (three arms) → auth → RESOLVE → build → SHOW → ask → post
+ *     friction → auth → GATE → RESOLVE → build → SHOW → ask → post
  */
 export declare function dxSendCommand(deps: DxSendDeps, options: DxOptions): Promise<number>;