@vincentt-xr/cli 0.7.0 → 0.9.0

package/dist/publish/command.js

@@ -148,6 +148,11 @@ export async function publishCommand(deps, opts = {}) {
         address,
         liveVersion: project.liveVersion ?? undefined,
         fetchImpl,
+        org: {
+            name: orgName || undefined,
+            slug: (await deps.orgSlug?.()) || undefined,
+            consoleUrl: deps.consoleUrl,
+        },
     });
 }
 async function runUpload(deps, cfg, i) {
@@ -156,7 +161,7 @@ async function runUpload(deps, cfg, i) {
         opened = await openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl);
     }
     catch (err) {
-        for (const l of openErrorLines(err, i.address, i.liveVersion))
+        for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
             deps.print(l);
         return 1;
     }
@@ -221,6 +226,9 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
         catch (err) {
             if (!(err instanceof PublishApiError))
                 throw err;
+            // The plan limit is a 409 and falls past this branch deliberately. It is
+            // the interlock refusing, not the flip failing, and retrying it three
+            // times would be the retry loop the refusal exists to stop.
             if (err.code === "publish_flip_failed" || err.status === 502) {
                 if (attempt === COMMIT_RETRIES) {
                     for (const l of copy.flipFailed(i.address, i.liveVersion))
@@ -236,15 +244,39 @@ async function commitWithHealing(deps, cfg, i, uploadId) {
                 await deps.sleep(COMMIT_RETRY_DELAY_MS);
                 continue;
             }
-            for (const l of commitErrorLines(err, i.address, i.liveVersion))
+            for (const l of commitErrorLines(err, i.address, i.liveVersion, i.org))
                 deps.print(l);
             return 1;
         }
     }
     return 1;
 }
-function commitErrorLines(err, address, liveVersion) {
+/**
+ * The plan-limit refusal, from the detail the API sends. It is reachable from
+ * open AND from commit, because the interlock lives at the port and every flip
+ * path folds through the same 409.
+ *
+ * The figures come off the wire and are never computed here: a CLI that derived
+ * an allowance would be guessing at another service's state.
+ */
+function planLimitLines(err, org) {
+    return copy.planLimitRefused({
+        // THE WIRE WINS over the machine's configured active org. The API names the
+        // org that owns this project; the local config names whichever org the CLI
+        // was last pointed at, and they are not always the same one.
+        orgName: err.detail.orgName ?? org?.name,
+        orgSlug: err.detail.orgSlug ?? org?.slug,
+        planName: err.detail.planName,
+        figureBytes: err.detail.figureBytes ?? 0,
+        allowanceBytes: err.detail.allowanceBytes ?? 0,
+        cutOffAt: err.detail.cutOffAt,
+        consoleUrl: org?.consoleUrl,
+    });
+}
+function commitErrorLines(err, address, liveVersion, org) {
     switch (err.code) {
+        case "unavailable_plan_limit":
+            return planLimitLines(err, org);
         case "publish_expired":
             return copy.publishExpired(address, liveVersion);
         case "publish_contended":
@@ -267,7 +299,7 @@ function commitErrorLines(err, address, liveVersion) {
             ];
     }
 }
-function openErrorLines(err, address, liveVersion) {
+function openErrorLines(err, address, liveVersion, org) {
     if (!(err instanceof PublishApiError)) {
         return [
             "",
@@ -277,6 +309,9 @@ function openErrorLines(err, address, liveVersion) {
             "",
         ];
     }
+    if (err.code === "unavailable_plan_limit") {
+        return planLimitLines(err, org);
+    }
     if (err.code === "publish_too_large") {
         return copy.tooLargeFromServer(err.detail.observed ?? 0, err.detail.limit ?? 0);
     }

package/dist/publish/copy.d.ts

@@ -132,6 +132,35 @@ export declare function finishing(): string;
 export declare function liveAt(liveUrl: string, version: number): string[];
 /** Prints only if a retry is needed. It says nothing about a failure, because nothing has failed yet. */
 export declare function takingLonger(): string;
+export interface PlanLimitInput {
+    /** The org's display name, and its slug when the CLI holds one. */
+    orgName?: string;
+    orgSlug?: string;
+    /** The plan in force. Absent when the API did not name one — the line is then dropped. */
+    planName?: string;
+    figureBytes: number;
+    allowanceBytes: number;
+    /** RFC3339, from the cutoff marker. */
+    cutOffAt?: string;
+    consoleUrl?: string;
+}
+/**
+ * Flow L32 — the org is cut off and open-publish refused before a byte moved.
+ *
+ * This is NOT flipFailed and must never be folded into it. The API gives the two
+ * distinct wire codes because one means the system working correctly and the
+ * other means the ledger is broken; a creator told "the address didn't switch
+ * over" when they hit a plan limit has been told the platform is malfunctioning.
+ *
+ * The three facts are a STACKED ALIGNED BLOCK because they are a comparison —
+ * the figure against the allowance. Inline they are a sentence to parse; stacked
+ * an agent and a human read them the same way.
+ *
+ * "cannot be done from the CLI" is load-bearing: an agent's default response to a
+ * failure is to retry, and naming the remedy as a human action outside the tool
+ * is the only thing that stops the loop.
+ */
+export declare function planLimitRefused(i: PlanLimitInput): string[];
 /**
  * The cause is NOT named. Every non-healing arm of the commit state machine
  * returns this identically by design, and the CLI must not invent a distinction

package/dist/publish/copy.js

@@ -440,6 +440,92 @@ export function liveAt(liveUrl, version) {
 export function takingLonger() {
     return "!  Taking a moment longer than usual…";
 }
+const SUPPORT_EMAIL = "hello@vincentt.studio";
+/**
+ * Flow L32 — the org is cut off and open-publish refused before a byte moved.
+ *
+ * This is NOT flipFailed and must never be folded into it. The API gives the two
+ * distinct wire codes because one means the system working correctly and the
+ * other means the ledger is broken; a creator told "the address didn't switch
+ * over" when they hit a plan limit has been told the platform is malfunctioning.
+ *
+ * The three facts are a STACKED ALIGNED BLOCK because they are a comparison —
+ * the figure against the allowance. Inline they are a sentence to parse; stacked
+ * an agent and a human read them the same way.
+ *
+ * "cannot be done from the CLI" is load-bearing: an agent's default response to a
+ * failure is to retry, and naming the remedy as a human action outside the tool
+ * is the only thing that stops the loop.
+ */
+export function planLimitRefused(i) {
+    const rows = [];
+    if (i.orgName || i.orgSlug)
+        rows.push(["Organization", orgLabel(i.orgName, i.orgSlug)]);
+    if (i.planName) {
+        rows.push(["Plan", `${i.planName} — ${formatBytes(i.allowanceBytes)} traffic per month`]);
+    }
+    else {
+        rows.push(["Allowance", `${formatBytes(i.allowanceBytes)} traffic per month`]);
+    }
+    rows.push(["Served", `${formatBytes(i.figureBytes)} this month`]);
+    const when = i.cutOffAt ? shortDate(i.cutOffAt) : "";
+    const takenOn = when ? ` on ${when}` : "";
+    return [
+        "",
+        "✗ Vincentt has taken this organization's published addresses offline.",
+        "",
+        ...alignedRows(rows),
+        "",
+        `  Published addresses were taken offline${takenOn} because the organization`,
+        "  went over its monthly traffic allowance. Restoring this is a manual action",
+        "  by a Vincentt operator and cannot be done from the CLI.",
+        "",
+        "  Every version is still stored and the address is still yours.",
+        "",
+        ...remedyLines(i.orgSlug, i.consoleUrl),
+        "  Nothing was uploaded.",
+        "",
+    ];
+}
+function orgLabel(name, slug) {
+    if (name && slug && name !== slug)
+        return `${name} (${slug})`;
+    return name || slug || "";
+}
+/**
+ * Left-aligned label column. Distinct from alignedPair, which right-aligns two
+ * values so magnitudes compare — here the values are prose of different kinds.
+ */
+function alignedRows(rows) {
+    const width = Math.max(...rows.map((r) => r[0].length));
+    return rows.map(([label, value]) => `  ${label.padEnd(width)}   ${value}`);
+}
+/**
+ * f4's rule: where a verb does not exist because the act belongs to another
+ * surface, say where it lives and link to it — and if the link cannot be built,
+ * drop the link and keep the explanation.
+ */
+function remedyLines(orgSlug, consoleUrl) {
+    if (!orgSlug)
+        return [`  Email ${SUPPORT_EMAIL}.`, ""];
+    const base = (consoleUrl ?? "https://console.vincentt.studio").replace(/\/$/, "");
+    return [
+        `  See ${base}/orgs/${orgSlug}/usage, or email`,
+        `  ${SUPPORT_EMAIL}.`,
+        "",
+    ];
+}
+const MONTHS = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+/** `29 Aug` — the date the creator reads, in UTC, matching the marker's own day. */
+function shortDate(iso) {
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return "";
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
+}
 // ---- Flow L29, the server-side failures ---------------------------------------
 /**
  * The cause is NOT named. Every non-healing arm of the commit state machine

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/scaffold/index.d.ts

@@ -30,6 +30,15 @@ export declare function needsScaffold(dir: string): Promise<boolean>;
  * Dotfiles count. A folder holding only `.git` is a repo someone cares about.
  */
 export declare function isNonEmptyDir(dir: string): Promise<boolean>;
+/**
+ * The clone failed because the REF does not exist, as opposed to the repo being
+ * unreachable. The two remedies are opposite, and a caller cloning a gallery
+ * source words both differently — so the split is carried by the error's type
+ * rather than by re-matching git's text downstream.
+ */
+export declare class ScaffoldRefError extends Error {
+    constructor(message: string);
+}
 export interface ScaffoldOptions {
     repo?: string;
     /** Template ref (tag) to scaffold from. Defaults to `DEFAULT_TEMPLATE_REF`. */

package/dist/scaffold/index.js

@@ -59,6 +59,18 @@ export async function isNonEmptyDir(dir) {
         return false;
     }
 }
+/**
+ * The clone failed because the REF does not exist, as opposed to the repo being
+ * unreachable. The two remedies are opposite, and a caller cloning a gallery
+ * source words both differently — so the split is carried by the error's type
+ * rather than by re-matching git's text downstream.
+ */
+export class ScaffoldRefError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScaffoldRefError";
+    }
+}
 /**
  * Scaffold the template into `targetDir`. Clones to a temp dir, strips `.git`,
  * copies the files in (never overwriting anything already there), then inits a
@@ -80,7 +92,7 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
             // real cause is a typo'd version). git names the ref in this specific case,
             // so split on that rather than reporting one cause for both.
             if (/(remote branch|Remote branch).*not found|couldn't find remote ref/i.test(msg)) {
-                throw new Error(`The template has no version "${ref}". ` +
+                throw new ScaffoldRefError(`The template has no version "${ref}". ` +
                     `Check the tag exists, or omit --template to use the latest release.`);
             }
             throw new Error(`Could not clone the ${repo} template (check your git access): ${msg}`);

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.9.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",