@vincentt-xr/cli 0.22.0 → 0.23.0

package/MIGRATION.md

@@ -3,6 +3,17 @@
 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

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

@@ -1446,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");
@@ -1549,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 —
@@ -1556,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,
@@ -1565,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
@@ -1597,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 {
@@ -1642,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/journal.d.ts

@@ -12,6 +12,8 @@ export interface JournalEntry {
     err: string | null;
     /** Hash of the working tree, so runs group by project without recording where it is. */
     wt: string;
+    /** `editor` only: why it exited 1, one word from a closed set. Never a path or a value. */
+    reason?: string;
 }
 /**
  * Beside the machine config, so the journal shares the home the PAT already
@@ -38,6 +40,7 @@ export interface RecordInput {
     endedAt: number;
     exitCode: number;
     error?: unknown;
+    reason?: string;
 }
 export declare function buildEntry(input: RecordInput): JournalEntry;
 /**

package/dist/dx/journal.js

@@ -68,8 +68,10 @@ function trim(file) {
         return;
     fs.writeFileSync(file, lines.slice(-MAX_ENTRIES).join("\n") + "\n", "utf8");
 }
+/** Only a lowercase word survives as a reason, so no caller can route a value through it. */
+const REASON = /^[a-z_]{1,40}$/;
 export function buildEntry(input) {
-    return {
+    const entry = {
         ts: new Date(input.startedAt).toISOString(),
         v: input.cliVersion,
         verb: verbOf(input.argv),
@@ -79,6 +81,9 @@ export function buildEntry(input) {
         err: classify(input.error),
         wt: workingTreeId(input.cwd),
     };
+    if (input.reason !== undefined && REASON.test(input.reason))
+        entry.reason = input.reason;
+    return entry;
 }
 /**
  * Append one entry. Never throws: a journal that can break a publish is a

package/dist/dx/skeleton.js

@@ -39,6 +39,7 @@ const KNOWN_VERBS = new Set([
     "create",
     "domain",
     "dx",
+    "editor",
     "feedback",
     "init",
     "link",
@@ -82,10 +83,12 @@ const KNOWN_FLAGS = new Set([
     "--port",
     "--preview",
     "--restart",
+    "--selection",
     "--send",
     "--session",
     "--since",
     "--slug",
+    "--status",
     "--stop",
     "--template",
     "--tester",

package/dist/editor/app.d.ts

@@ -0,0 +1,61 @@
+export declare const EDITOR_BUNDLE_NAME = "Vincentt Editor.app";
+export declare const EDITOR_BUNDLE_ID = "studio.vincentt.editor";
+export declare const MIN_MACOS_MAJOR = 14;
+/** The Apple Team ID of the Developer ID that signs Vincentt Editor. */
+export declare const VINCENTT_TEAM_ID = "RB8P2M86YU";
+/**
+ * The designated requirement: Apple-anchored, a Developer ID leaf (1.2.840.113635.100.6.1.13)
+ * under the Developer ID intermediate (1.2.840.113635.100.6.2.6), the leaf's OU the Team ID,
+ * and the bundle identifier.
+ */
+export declare function designatedRequirement(teamId: string, identifier: string): string;
+export declare const EDITOR_REQUIREMENT: string;
+/** `/Applications`, then the user's own `~/Applications` (from the user database, not HOME). */
+export declare function defaultSearchRoots(): string[];
+export type Verdict = {
+    ok: true;
+} | {
+    ok: false;
+    detail: string;
+};
+export interface RunningCopy {
+    pid: number;
+    bundlePath: string;
+}
+/** The OS questions the launcher and the read flags ask. Tests replace any of them. */
+export interface MacSystem {
+    /** The macOS product version (`14.5`), or undefined when unreadable. */
+    osVersion(): Promise<string | undefined>;
+    /** `codesign --verify --deep --strict -R=<requirement> <app>`. */
+    verify(app: string, requirement: string): Promise<Verdict>;
+    /** Info.plist values of a bundle; read only after the bundle passed `verify`. */
+    bundleInfo(app: string): Promise<{
+        executable?: string;
+        version?: string;
+    }>;
+    /** Running apps registered with LaunchServices under this bundle identifier. */
+    runningCopies(bundleId: string): Promise<RunningCopy[]>;
+    /** `codesign --verify -R=<requirement> <pid>`: the running code of `pid`, as the kernel holds it. */
+    verifyPid(pid: number, requirement: string): Promise<Verdict>;
+    /** When `pid` started (epoch ms, whole seconds), or undefined when it cannot be read. */
+    startTime(pid: number): Promise<number | undefined>;
+    /** `/usr/bin/open -a <app> <folder>`; rejects when `open` fails. */
+    open(app: string, folder: string): Promise<void>;
+}
+/** codesign's last stderr line, without the leading `<path>: ` it names the bundle with. */
+export declare function codesignDetail(stderr: string, app: string): string;
+/** `lsappinfo find` output → its ASNs. */
+export declare function parseAsns(out: string): string[];
+/** `lsappinfo info -only pid -only bundlepath <asn>` output → the copy it names. */
+export declare function parseAppInfo(out: string): RunningCopy | undefined;
+/**
+ * `ps -o lstart=` run with LC_ALL=C and TZ=UTC0 (`Thu Oct 23 00:15:02 2026`, UTC) → epoch ms.
+ * Parsed as UTC, so the result does not depend on this process's time zone.
+ */
+export declare function parseLstart(out: string): number | undefined;
+/** `14.5` → 14, `13.6.1` → 13; undefined when it is not a version. */
+export declare function macosMajor(version: string | undefined): number | undefined;
+export declare function macSystem(): MacSystem;
+export declare function pidAlive(pid: number): boolean;
+/** Both paths with links resolved, compared; a path that cannot be resolved compares as given. */
+export declare function samePath(a: string, b: string): Promise<boolean>;

package/dist/editor/app.js

@@ -0,0 +1,180 @@
+// The installed Vincentt Editor app as the launcher sees it: where it may live, the designated
+// requirement it must meet, and the macOS probes that answer questions about it. Every probe
+// runs a system tool by absolute path; none reads the environment or the project.
+import { execFile } from "node:child_process";
+import { realpath } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { toolPath } from "./tools.js";
+const execFileP = promisify(execFile);
+export const EDITOR_BUNDLE_NAME = "Vincentt Editor.app";
+export const EDITOR_BUNDLE_ID = "studio.vincentt.editor";
+export const MIN_MACOS_MAJOR = 14;
+/** The Apple Team ID of the Developer ID that signs Vincentt Editor. */
+export const VINCENTT_TEAM_ID = "RB8P2M86YU";
+/**
+ * The designated requirement: Apple-anchored, a Developer ID leaf (1.2.840.113635.100.6.1.13)
+ * under the Developer ID intermediate (1.2.840.113635.100.6.2.6), the leaf's OU the Team ID,
+ * and the bundle identifier.
+ */
+export function designatedRequirement(teamId, identifier) {
+    return ("anchor apple generic" +
+        " and certificate leaf[field.1.2.840.113635.100.6.1.13] exists" +
+        " and certificate 1[field.1.2.840.113635.100.6.2.6] exists" +
+        ` and certificate leaf[subject.OU] = "${teamId}"` +
+        ` and identifier "${identifier}"`);
+}
+export const EDITOR_REQUIREMENT = designatedRequirement(VINCENTT_TEAM_ID, EDITOR_BUNDLE_ID);
+/** `/Applications`, then the user's own `~/Applications` (from the user database, not HOME). */
+export function defaultSearchRoots() {
+    return ["/Applications", path.join(os.userInfo().homedir, "Applications")];
+}
+const RUN = {
+    timeout: 30_000,
+    maxBuffer: 4 << 20,
+    env: { LC_ALL: "C", PATH: "/usr/bin:/bin" },
+};
+async function run(tool, args, env = RUN.env) {
+    const cmd = toolPath(tool);
+    if (cmd === undefined)
+        throw new Error(`${tool} is not where macOS keeps it`);
+    return (await execFileP(cmd, args, { ...RUN, env })).stdout;
+}
+/** codesign's last stderr line, without the leading `<path>: ` it names the bundle with. */
+export function codesignDetail(stderr, app) {
+    const lines = stderr
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l !== "");
+    const last = lines[lines.length - 1] ?? "codesign refused the app";
+    return last.startsWith(`${app}: `) ? last.slice(app.length + 2) : last;
+}
+/** `lsappinfo find` output → its ASNs. */
+export function parseAsns(out) {
+    return [...out.matchAll(/ASN:0x[0-9a-f]+-0x[0-9a-f]+/gi)].map((m) => m[0]);
+}
+/** `lsappinfo info -only pid -only bundlepath <asn>` output → the copy it names. */
+export function parseAppInfo(out) {
+    const pid = /"pid"\s*=\s*(\d+)/.exec(out)?.[1];
+    const bundle = /"LSBundlePath"\s*=\s*"(.*)"\s*$/m.exec(out)?.[1];
+    if (pid === undefined || bundle === undefined || bundle === "")
+        return undefined;
+    return { pid: Number(pid), bundlePath: bundle };
+}
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+/**
+ * `ps -o lstart=` run with LC_ALL=C and TZ=UTC0 (`Thu Oct 23 00:15:02 2026`, UTC) → epoch ms.
+ * Parsed as UTC, so the result does not depend on this process's time zone.
+ */
+export function parseLstart(out) {
+    const m = /^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/.exec(out.trim());
+    if (m === null)
+        return undefined;
+    const month = MONTHS.indexOf(m[1]);
+    if (month < 0)
+        return undefined;
+    const t = Date.UTC(Number(m[6]), month, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]));
+    return Number.isFinite(t) ? t : undefined;
+}
+/** `14.5` → 14, `13.6.1` → 13; undefined when it is not a version. */
+export function macosMajor(version) {
+    const m = /^(\d+)(?:\.\d+)*$/.exec(version?.trim() ?? "");
+    return m ? Number(m[1]) : undefined;
+}
+/** `codesign <args>`: ok on exit 0, else its last stderr line (with `subject: ` removed). */
+async function codesignVerify(args, subject) {
+    const cmd = toolPath("codesign");
+    if (cmd === undefined)
+        return { ok: false, detail: "codesign is not where macOS keeps it" };
+    try {
+        await execFileP(cmd, args, RUN);
+        return { ok: true };
+    }
+    catch (err) {
+        const stderr = err.stderr;
+        return { ok: false, detail: codesignDetail(stderr ?? String(err), subject) };
+    }
+}
+export function macSystem() {
+    return {
+        osVersion: async () => {
+            const v = await run("sw_vers", ["-productVersion"]).catch(() => "");
+            return v.trim() || undefined;
+        },
+        verify: (app, requirement) => codesignVerify(["--verify", "--deep", "--strict", `-R=${requirement}`, app], app),
+        verifyPid: (pid, requirement) => Number.isInteger(pid) && pid > 0
+            ? codesignVerify(["--verify", `-R=${requirement}`, String(pid)], String(pid))
+            : Promise.resolve({ ok: false, detail: "not a process id" }),
+        bundleInfo: async (app) => {
+            const plist = path.join(app, "Contents", "Info.plist");
+            const read = async (key) => (await run("plutil", ["-extract", key, "raw", "-o", "-", plist]).catch(() => "")).trim() || undefined;
+            return {
+                executable: await read("CFBundleExecutable"),
+                version: await read("CFBundleShortVersionString"),
+            };
+        },
+        runningCopies: async (bundleId) => {
+            // Throws when the running copies cannot be listed: an unknown answer is not "none".
+            const found = await run("lsappinfo", ["find", `bundleID=${bundleId}`]);
+            const asns = parseAsns(found);
+            if (asns.length === 0 && found.trim() !== "")
+                throw new Error("lsappinfo find answered without an ASN");
+            const copies = [];
+            for (const asn of asns) {
+                const info = await run("lsappinfo", [
+                    "info",
+                    "-only",
+                    "pid",
+                    "-only",
+                    "bundlepath",
+                    asn,
+                ]);
+                const copy = parseAppInfo(info);
+                if (copy === undefined)
+                    throw new Error("lsappinfo info named no pid and bundle");
+                // LaunchServices can list an app for a moment after it exits.
+                if (pidAlive(copy.pid))
+                    copies.push(copy);
+            }
+            return copies;
+        },
+        startTime: async (pid) => parseLstart(await run("ps", ["-o", "lstart=", "-p", String(pid)], {
+            ...RUN.env,
+            TZ: "UTC0",
+        }).catch(() => "")),
+        open: async (app, folder) => {
+            await run("open", ["-a", app, folder]);
+        },
+    };
+}
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** Both paths with links resolved, compared; a path that cannot be resolved compares as given. */
+export async function samePath(a, b) {
+    const ra = await realpath(a).catch(() => path.resolve(a));
+    const rb = await realpath(b).catch(() => path.resolve(b));
+    return ra === rb;
+}

package/dist/editor/copy.d.ts

@@ -0,0 +1,22 @@
+export declare const DOWNLOAD_URL = "https://vincentt.studio/editor";
+export declare const NOTHING_OPENED = "Nothing was opened.";
+export declare const NOT_RUNNING = "\u2717 No editor is running for this folder.";
+/** `~/Downloads/Vincentt Editor.app` for a path under the home folder. */
+export declare function tildePath(p: string, home?: string): string;
+export declare function sent(name: string): string;
+export declare function notInstalled(): string[];
+/** `app` is the refused bundle; the copy names the folder it was found in. */
+export declare function badSignature(app: string): string[];
+/** The copy on disk passes, but the one running from the same place does not. */
+export declare function runningCopyNotSigned(): string[];
+export declare function notMacos(): string[];
+export declare function macosTooOld(version: string): string[];
+export declare function otherCopyRunning(bundlePath: string): string[];
+/** A flag the launcher had before it handed off to the app (`--port`, `--dev-url`). */
+export declare function removedFlag(flag: string): string[];
+export declare function unknownFlag(flag: string): string[];
+export declare function strayArgument(): string[];
+export declare function bothReads(): string[];
+export declare function openFailed(): string[];
+/** A local file written in a schema major this CLI does not know. */
+export declare function tooNew(schema: string): string[];

package/dist/editor/copy.js

@@ -0,0 +1,95 @@
+// The `vincentt editor` screens (features/f21-visual-editor/mock/cli.md, C1 to C3). After a
+// non-zero exit the last line states what did not happen.
+import os from "node:os";
+import path from "node:path";
+import { agentSafe } from "./text.js";
+export const DOWNLOAD_URL = "https://vincentt.studio/editor";
+export const NOTHING_OPENED = "Nothing was opened.";
+export const NOT_RUNNING = "✗ No editor is running for this folder.";
+/** `~/Downloads/Vincentt Editor.app` for a path under the home folder. */
+export function tildePath(p, home = os.homedir()) {
+    const safe = agentSafe(p, 400);
+    if (home && (safe === home || safe.startsWith(home + "/"))) {
+        return "~" + safe.slice(home.length);
+    }
+    return safe;
+}
+export function sent(name) {
+    return `✓ Sent ${agentSafe(name, 80)} to Vincentt Editor.`;
+}
+export function notInstalled() {
+    return [
+        `✗ Vincentt Editor is not installed. Get it at ${DOWNLOAD_URL}`,
+        NOTHING_OPENED,
+    ];
+}
+/** `app` is the refused bundle; the copy names the folder it was found in. */
+export function badSignature(app) {
+    return [
+        `✗ The Vincentt Editor in ${tildePath(path.dirname(app))} is not signed by Vincentt, so the CLI will not open it.`,
+        `  Delete it and download it again from ${DOWNLOAD_URL}`,
+        NOTHING_OPENED,
+    ];
+}
+/** The copy on disk passes, but the one running from the same place does not. */
+export function runningCopyNotSigned() {
+    return [
+        "✗ The Vincentt Editor that is running is not signed by Vincentt, so the CLI will not open it.",
+        "  Quit the running Vincentt Editor, then run vincentt editor again.",
+        NOTHING_OPENED,
+    ];
+}
+export function notMacos() {
+    return ["✗ Vincentt Editor runs on macOS only for now.", NOTHING_OPENED];
+}
+export function macosTooOld(version) {
+    return [
+        `✗ Vincentt Editor needs macOS 14 or later. This Mac has macOS ${agentSafe(version, 20)}.`,
+        NOTHING_OPENED,
+    ];
+}
+export function otherCopyRunning(bundlePath) {
+    return [
+        `✗ Another Vincentt Editor is running from ${tildePath(bundlePath)}.`,
+        "  Quit the other Vincentt Editor first, then run vincentt editor again.",
+        NOTHING_OPENED,
+    ];
+}
+/** A flag the launcher had before it handed off to the app (`--port`, `--dev-url`). */
+export function removedFlag(flag) {
+    return [
+        `✗ ${flag} was removed. Vincentt Editor starts the preview itself.`,
+        "  Run:  vincentt editor",
+        NOTHING_OPENED,
+    ];
+}
+export function unknownFlag(flag) {
+    return [
+        `✗ vincentt editor has no option ${agentSafe(flag, 40)}.`,
+        "  Run:  vincentt editor   (or --selection --json, or --status --json)",
+        NOTHING_OPENED,
+    ];
+}
+export function strayArgument() {
+    return [
+        "✗ vincentt editor takes no folder name. Run it inside the project, or pass --dir <folder>.",
+        NOTHING_OPENED,
+    ];
+}
+export function bothReads() {
+    return ["✗ --selection and --status cannot be used together. Run one, then the other."];
+}
+export function openFailed() {
+    return [
+        "✗ macOS could not hand the folder to Vincentt Editor.",
+        "  Open Vincentt Editor from Applications, then run vincentt editor again.",
+        NOTHING_OPENED,
+    ];
+}
+/** A local file written in a schema major this CLI does not know. */
+export function tooNew(schema) {
+    return [
+        `✗ Vincentt Editor wrote ${agentSafe(schema, 80)}, which is newer than this CLI reads.`,
+        "  Update the CLI:  npm install -g @vincentt-xr/cli@latest",
+    ];
+}

package/dist/editor/handoffs.d.ts

@@ -0,0 +1,12 @@
+/** Hand-off time (epoch ms) by project key. */
+export type Handoffs = Record<string, number>;
+/** Resolved per call: the home folder is the seam tests move. */
+export declare function handoffsPath(): string;
+/** The key a canonical project path is recorded under. */
+export declare function projectKey(project: string): string;
+/** Every recorded hand-off; empty when the file is absent, a link or unreadable. */
+export declare function readHandoffs(file?: string): Promise<Handoffs>;
+/** The last hand-off of `project` (a canonical path), or undefined when there was none. */
+export declare function lastHandoff(project: string, file?: string): Promise<number | undefined>;
+/** Records a hand-off of `project`, keeping the newest entries. Best-effort: never throws. */
+export declare function recordHandoff(project: string, at: number, file?: string): Promise<void>;