@vincentt-xr/cli 0.7.0 → 0.8.0

package/dist/library/wire.js

@@ -0,0 +1,167 @@
+// The f5 asset-library wire shapes, and the ONE parser every renderer reads through.
+//
+// The envelope is camelCase (resultCount, gaps, resolved, unknown) while the asset
+// RECORD is snake_case (has_alpha, usage_hint, text_in_image, occupies_canvas).
+// That mix is deliberate and it is the API's only mixed-convention response
+// (implementation 2.12): the record's vocabulary sits beside English prose in an
+// agent's context, so it reads as prose-adjacent rather than as code identifiers.
+// NEITHER SIDE IS NORMALIZED HERE. Rewriting the record to camelCase would silently
+// break every agent prompt in the wild that reads `usage_hint`.
+//
+// EVERY field is read defensively, for the reason lib/diagnostics.ts records: the
+// CLI and the API are versioned separately on a creator's machine — `npx vincentt`
+// fetches whatever the registry has and points it at whatever API the config
+// resolves to. A field a renderer reads unguarded is a field whose removal from the
+// API crashes the command, which is exactly what removing `sessions` did once.
+// A missing optional field must degrade to a missing LINE, never to an exception.
+/**
+ * The asset id shape. Base32-lower, matching the server's `^lib_[a-z2-7]{16}$`
+ * exactly.
+ *
+ * The alphabet is the house convention across this API (f3 sessions {32}, f4
+ * uploads {26}, preview host labels, publish keys) and it excludes 0/1/8/9 so an
+ * id read off a terminal carries no visually ambiguous characters. 16 chars is
+ * 80 bits, which is what makes the key pattern unguessable, one of the four
+ * counters to an agent inventing a URL.
+ *
+ * The CLI briefly accepted hex as well, because every EXAMPLE id written into
+ * the design record was hex and contradicted the record's own regex. User ruling
+ * 2026-08-23: the regex is authoritative and the examples were wrong. Matching
+ * the server exactly is what keeps a client-side reject and a server-side
+ * `unknown[]` from ever disagreeing.
+ */
+export const LIB_ID_RE = /^lib_[a-z2-7]{16}$/;
+export function isLibraryId(s) {
+    return LIB_ID_RE.test(s);
+}
+function obj(v) {
+    return typeof v === "object" && v !== null ? v : {};
+}
+function str(o, k) {
+    return typeof o[k] === "string" ? o[k] : undefined;
+}
+function num(o, k) {
+    return typeof o[k] === "number" && Number.isFinite(o[k]) ? o[k] : undefined;
+}
+function bool(o, k) {
+    return typeof o[k] === "boolean" ? o[k] : undefined;
+}
+function strArray(o, k) {
+    const v = o[k];
+    if (!Array.isArray(v))
+        return undefined;
+    return v.filter((x) => typeof x === "string");
+}
+/**
+ * Parse one asset record.
+ *
+ * `kind` is admitted ONLY as "prop" or "frame". Anything else — including "" and
+ * "unknown" — parses to ABSENT rather than being passed through, because a record
+ * whose kind is the literal string "unknown" would render as a real classification
+ * on the line an agent uses to decide whether the asset is usable at all.
+ *
+ * Returns undefined when `id`/`url` are missing: a record with no URL is not a
+ * usable result, and dropping it is better than rendering an entry whose payload
+ * line is blank.
+ */
+export function parseAssetRecord(raw) {
+    const o = obj(raw);
+    const id = str(o, "id");
+    const url = str(o, "url");
+    if (id === undefined || url === undefined)
+        return undefined;
+    // The wire is an input too. A record whose url is not https is dropped rather
+    // than rendered, so a compromised or misconfigured API cannot point --download
+    // at file:// or a link-local address.
+    if (!url.startsWith("https://"))
+        return undefined;
+    const kindRaw = str(o, "kind");
+    const kind = kindRaw === "prop" || kindRaw === "frame" ? kindRaw : undefined;
+    // An empty string is the "not confidently read" case the API omits; treat a
+    // stray "" the same way rather than rendering an empty labelled line.
+    const textInImage = str(o, "text_in_image");
+    return {
+        id,
+        url,
+        ...(kind !== undefined ? { kind } : {}),
+        ...(num(o, "width") !== undefined ? { width: num(o, "width") } : {}),
+        ...(num(o, "height") !== undefined ? { height: num(o, "height") } : {}),
+        ...(str(o, "aspect") !== undefined ? { aspect: str(o, "aspect") } : {}),
+        ...(bool(o, "has_alpha") !== undefined ? { has_alpha: bool(o, "has_alpha") } : {}),
+        ...(num(o, "bytes") !== undefined ? { bytes: num(o, "bytes") } : {}),
+        ...(str(o, "format") !== undefined ? { format: str(o, "format") } : {}),
+        ...(str(o, "subject") !== undefined ? { subject: str(o, "subject") } : {}),
+        ...(strArray(o, "style") !== undefined ? { style: strArray(o, "style") } : {}),
+        ...(strArray(o, "palette") !== undefined ? { palette: strArray(o, "palette") } : {}),
+        ...(str(o, "render") !== undefined ? { render: str(o, "render") } : {}),
+        ...(str(o, "view") !== undefined ? { view: str(o, "view") } : {}),
+        ...(str(o, "description") !== undefined
+            ? { description: str(o, "description") }
+            : {}),
+        ...(str(o, "usage_hint") !== undefined ? { usage_hint: str(o, "usage_hint") } : {}),
+        ...(textInImage ? { text_in_image: textInImage } : {}),
+        ...(num(o, "occupies_canvas") !== undefined
+            ? { occupies_canvas: num(o, "occupies_canvas") }
+            : {}),
+        ...(bool(o, "retired") !== undefined ? { retired: bool(o, "retired") } : {}),
+    };
+}
+function parseGaps(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const g of raw) {
+        const o = obj(g);
+        const tag = str(o, "tag");
+        const message = str(o, "message");
+        // Both fields are load-bearing and carry different jobs: the agent BRANCHES on
+        // `tag` and QUOTES `message`. A half-formed gap is dropped rather than rendered
+        // with an invented half.
+        if (tag !== undefined && message !== undefined)
+            out.push({ tag, message });
+    }
+    return out;
+}
+/**
+ * Parse the search envelope.
+ *
+ * `resultCount` is taken from the wire when present and otherwise derived from the
+ * array, so a truncated envelope still renders a truthful count rather than 0 —
+ * and 0 is the one value that must never be invented, because zero results is a
+ * meaningful product answer (the honest-empty path) rather than an absence.
+ */
+export function parseSearchResponse(raw) {
+    const o = obj(raw);
+    const results = Array.isArray(o.results)
+        ? o.results.map(parseAssetRecord).filter((r) => r !== undefined)
+        : [];
+    return {
+        ...(str(o, "query") !== undefined ? { query: str(o, "query") } : {}),
+        ...(str(o, "revision") !== undefined ? { revision: str(o, "revision") } : {}),
+        resultCount: num(o, "resultCount") ?? results.length,
+        results,
+        gaps: parseGaps(o.gaps),
+    };
+}
+/**
+ * Parse the batch envelope. `unknown[]` entries are echoed VERBATIM by the server
+ * and are kept as raw strings — they are the caller's own input coming back, which
+ * is what lets an agent diff against what it sent without parsing our prose.
+ */
+export function parseBatchResponse(raw) {
+    const o = obj(raw);
+    const resolved = Array.isArray(o.resolved)
+        ? o.resolved.map(parseAssetRecord).filter((r) => r !== undefined)
+        : [];
+    const unknown = Array.isArray(o.unknown)
+        ? o.unknown.filter((x) => typeof x === "string")
+        : [];
+    return { resolved, unknown };
+}
+/** A single record from `GET /library/assets/{id}` — the same record shape, unwrapped. */
+export function parseFetchResponse(raw) {
+    const o = obj(raw);
+    // Tolerate both a bare record and an { asset: … } envelope: /me already taught
+    // this codebase that an envelope can appear on a route that once returned bare.
+    return parseAssetRecord(o.asset !== undefined ? o.asset : o);
+}

package/dist/publish/prompt.js

@@ -7,10 +7,25 @@ import readline from "node:readline";
 /** Reads one line from stdin. Anything that is not an explicit answer takes the default. */
 export function stdinConfirm(input = process.stdin, output = process.stdout) {
     return async (prompt, defaultYes) => {
+        // A pipe cannot consent. Readline answers a piped line as readily as a typed
+        // one, so `echo y | vincentt publish` and `echo y | vincentt dx --send` both
+        // read as a person saying yes. A confirmation exists to put a human in the
+        // loop; when there is no terminal there is no human to put there, and the
+        // safe answer is no — never `defaultYes`, which on a [Y/n] prompt would turn
+        // an absent human into an approving one.
+        if (!input.isTTY)
+            return false;
         const rl = readline.createInterface({ input, output });
         try {
-            const answer = await new Promise((resolve) => rl.question(prompt, resolve));
-            return interpretAnswer(answer, defaultYes);
+            // `close` without an answer must resolve, not hang: on EOF readline never
+            // invokes the question callback, so awaiting it alone abandons the promise
+            // and every statement after the await — including the caller's "not sent"
+            // path — silently never runs.
+            const answer = await new Promise((resolve) => {
+                rl.question(prompt, resolve);
+                rl.once("close", () => resolve(undefined));
+            });
+            return answer === undefined ? false : interpretAnswer(answer, defaultYes);
         }
         finally {
             rl.close();

package/dist/shared/config.d.ts

@@ -7,6 +7,16 @@ export interface MachineConfig {
     pat: string;
     /** Org slug commands act in when no --org flag or VINCENTT_ORG env is given. */
     activeOrg: string;
+    /**
+     * Durable authorization for unattended `dx --send`. Written only by
+     * `vincentt dx enable`, which requires a TTY. Cleared by `disable` and by `logout`.
+     */
+    dxSendEnabled?: boolean;
+    /**
+     * ISO8601 UTC, when enablement was granted. Its AGE is the mitigation for having
+     * no expiry, so an unparseable value fails closed rather than printing.
+     */
+    dxSendEnabledAt?: string;
 }
 export interface ProjectBinding {
     /** The backend Project id this working tree publishes to. */
@@ -26,9 +36,26 @@ export declare function loadMachineConfig(): Promise<Partial<MachineConfig>>;
  * every write, even when the file pre-existed with looser perms).
  */
 export declare function writeMachineConfig(patch: Partial<MachineConfig>): Promise<string>;
+/**
+ * Set or clear unattended-send enablement (`vincentt dx enable` / `disable`).
+ *
+ * A dedicated function rather than a `writeMachineConfig` patch because clearing
+ * has to DELETE the keys. A patch of `{dxSendEnabled: undefined}` happens to work
+ * — JSON.stringify drops undefined values — but only by a coincidence of the
+ * serializer, and the read of a key that survived would be the difference between
+ * off and on.
+ */
+export declare function writeDxEnablement(next: {
+    at: string;
+} | undefined): Promise<string>;
 /**
  * Remove the stored PAT from ~/.vincentt/config.json (used by `vincentt logout`),
  * preserving apiUrl and any other fields. Returns whether a token was present.
+ *
+ * Unattended-send enablement goes with the PAT. This function preserves every
+ * other field by design, which would leave a disconnected machine still armed to
+ * transmit for whoever signs in next — a creator who disconnects a machine has
+ * disconnected it.
  */
 export declare function clearMachineToken(): Promise<{
     path: string;

package/dist/shared/config.js

@@ -8,6 +8,7 @@
 // Env vars (VINCENTT_API_URL / VINCENTT_PAT) override the file for local/dogfood
 // runs so a creator can point at a dev backend without editing the machine config.
 // The binding's optional apiUrl does NOT — see decideApiUrl.
+import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -31,18 +32,44 @@ export async function loadMachineConfig() {
     return (await readJsonIfExists(MACHINE_CONFIG_PATH)) ?? {};
 }
 /**
- * Persist the machine config with owner-only perms. `writeFile`'s `mode` only applies when
- * it CREATES the file, so a pre-existing config.json with looser perms (e.g. 0644) would keep
- * them and leave a bearer credential world-readable. An explicit chmod after the write tightens
- * it to 0600 every time, whether the file was just created or already existed.
+ * Persist the machine config with owner-only perms, ATOMICALLY: write a sibling
+ * temp file at 0600, then rename it over the target. Rename is atomic on the same
+ * filesystem, so there is no window in which config.json is truncated.
+ *
+ * Atomicity is not incidental cleanup. `dx enable` is a third writer to this file
+ * and, unlike `login`/`logout`, one an AGENT can trigger — in a session where
+ * `login` may also be running, against the file holding the bearer credential. A
+ * `writeFile` interrupted mid-write leaves a truncated config with the PAT gone,
+ * and it presents as an unexplained logout or as every later command throwing a
+ * SyntaxError, neither of which points at the write that caused it.
+ *
+ * `writeFile`'s `mode` only applies when it CREATES the file, so the temp file is
+ * chmod'ed explicitly: a lingering 0644 temp file would be a second, world-readable
+ * copy of the PAT. The temp file is removed if the rename fails, so a failed write
+ * leaves neither a truncated config nor a stray credential copy.
+ *
+ * The temp name is unique per call. A fixed `config.json.tmp` is safe for one
+ * writer and destructive for two: concurrent `login` and `dx enable` would write
+ * the same path, so whichever renamed second would fail ENOENT with its write
+ * silently lost — and a failing writer's cleanup would delete the other's
+ * in-flight file. Uniqueness also makes the `catch` safe by construction, since
+ * a writer can then only ever remove its own temp file.
  */
 async function persistMachineConfig(next) {
     await fs.mkdir(path.dirname(MACHINE_CONFIG_PATH), { recursive: true, mode: 0o700 });
-    await fs.writeFile(MACHINE_CONFIG_PATH, JSON.stringify(next, null, 2) + "\n", {
-        encoding: "utf8",
-        mode: 0o600,
-    });
-    await fs.chmod(MACHINE_CONFIG_PATH, 0o600);
+    const tmp = `${MACHINE_CONFIG_PATH}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+    try {
+        await fs.writeFile(tmp, JSON.stringify(next, null, 2) + "\n", {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await fs.chmod(tmp, 0o600);
+        await fs.rename(tmp, MACHINE_CONFIG_PATH);
+    }
+    catch (err) {
+        await fs.rm(tmp, { force: true }).catch(() => { });
+        throw err;
+    }
     return MACHINE_CONFIG_PATH;
 }
 /**
@@ -55,14 +82,42 @@ export async function writeMachineConfig(patch) {
     const next = { ...(await loadMachineConfig()), ...patch };
     return persistMachineConfig(next);
 }
+/**
+ * Set or clear unattended-send enablement (`vincentt dx enable` / `disable`).
+ *
+ * A dedicated function rather than a `writeMachineConfig` patch because clearing
+ * has to DELETE the keys. A patch of `{dxSendEnabled: undefined}` happens to work
+ * — JSON.stringify drops undefined values — but only by a coincidence of the
+ * serializer, and the read of a key that survived would be the difference between
+ * off and on.
+ */
+export async function writeDxEnablement(next) {
+    const cfg = await loadMachineConfig();
+    if (next === undefined) {
+        delete cfg.dxSendEnabled;
+        delete cfg.dxSendEnabledAt;
+    }
+    else {
+        cfg.dxSendEnabled = true;
+        cfg.dxSendEnabledAt = next.at;
+    }
+    return persistMachineConfig(cfg);
+}
 /**
  * Remove the stored PAT from ~/.vincentt/config.json (used by `vincentt logout`),
  * preserving apiUrl and any other fields. Returns whether a token was present.
+ *
+ * Unattended-send enablement goes with the PAT. This function preserves every
+ * other field by design, which would leave a disconnected machine still armed to
+ * transmit for whoever signs in next — a creator who disconnects a machine has
+ * disconnected it.
  */
 export async function clearMachineToken() {
     const current = await loadMachineConfig();
     const hadToken = Boolean(current.pat);
     delete current.pat;
+    delete current.dxSendEnabled;
+    delete current.dxSendEnabledAt;
     await persistMachineConfig(current);
     return { path: MACHINE_CONFIG_PATH, hadToken };
 }

package/package.json

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