@vincentt-xr/cli 0.16.0 → 0.18.0

package/dist/shared/config.js

@@ -12,6 +12,7 @@ import { randomBytes } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { NotSignedInError } from "./authError.js";
 import { recordLocation } from "./recordLocation.js";
 export const MACHINE_CONFIG_PATH = path.join(os.homedir(), ".vincentt", "config.json");
 const BINDING_DIR = ".vincentt";
@@ -216,9 +217,41 @@ async function ensureGitignored(cwd, pattern) {
         // A missing/unwritable .gitignore must not fail project creation.
     }
 }
-export const DEFAULT_API_URL = "http://localhost:5051";
+/**
+ * Every environment variable the CLI reads a credential from. They are removed
+ * from the environment of the creator's dev command, which is repo-controlled.
+ * A credential read added to this file without a name here fails a unit test.
+ */
+export const CLI_CREDENTIAL_ENV = ["VINCENTT_PAT"];
+export function withoutCliCredentials(env) {
+    const out = { ...env };
+    // Compared upper-cased: Windows environment names are case-insensitive.
+    for (const key of Object.keys(out)) {
+        if (CLI_CREDENTIAL_ENV.includes(key.toUpperCase()))
+            delete out[key];
+    }
+    return out;
+}
+export const DEFAULT_API_URL = "https://api.vincentt.studio";
+/**
+ * The API host the person running the command configured: an explicit flag, then
+ * VINCENTT_API_URL, then the machine config, then the default. Every verb reads
+ * its host through here, so a token is never sent to one host by one verb and to
+ * another by the next. A binding's override is layered on top by decideApiUrl.
+ */
+export function configuredApiUrl(input) {
+    return strip(input.flagApiUrl || input.envApiUrl || input.machineApiUrl || DEFAULT_API_URL);
+}
+/** configuredApiUrl from this process's environment and a machine config already read. */
+export function machineApiUrl(machine, flagApiUrl) {
+    return configuredApiUrl({
+        flagApiUrl,
+        envApiUrl: process.env.VINCENTT_API_URL,
+        machineApiUrl: machine.apiUrl,
+    });
+}
 export function decideApiUrl(input) {
-    const configuredUrl = input.envApiUrl ?? input.machineApiUrl ?? DEFAULT_API_URL;
+    const configuredUrl = configuredApiUrl(input);
     const binding = input.bindingApiUrl;
     if (!binding || strip(binding) === strip(configuredUrl)) {
         return { apiUrl: configuredUrl, configuredUrl };
@@ -255,10 +288,8 @@ export async function resolveConfig(cwd, opts = {}) {
         }
     }
     const pat = process.env.VINCENTT_PAT ?? machine.pat;
-    if (!pat) {
-        throw new Error(`No Vincentt access token found. Add {"apiUrl":"…","pat":"…"} to ${MACHINE_CONFIG_PATH}, ` +
-            `or set the VINCENTT_PAT env var.`);
-    }
+    if (!pat)
+        throw new NotSignedInError();
     return { apiUrl: strip(decided.apiUrl), pat };
 }
 const BINDING_REL_PATH = `${BINDING_DIR}/${BINDING_FILE}`;
@@ -292,8 +323,8 @@ export function apiUrlAdvisory(decided, ctx) {
         `     your machine config:${pad}  ${decided.configuredUrl}`,
         "",
         "   Your access token is sent with every request, so it would go to",
-        `   ${hostOf(decided.ignoredBindingApiUrl)}. A binding file travels with a repository —`,
-        "   anyone who can commit to it can set this.",
+        `   ${hostOf(decided.ignoredBindingApiUrl)}. A binding file travels with a repository,`,
+        "   so anyone who can commit to it can set this.",
         "",
         "   Ignoring the binding and using your machine config.",
         "   To use the binding's API on purpose, re-run with --allow-custom-api.",

package/dist/shared/countLimit.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The detail every count refusal carries. Pinned to the api's `Decision.Err`
+ * renderer: `{limit, count, ceiling, orgName, orgSlug, planName}`.
+ *
+ * On THESE codes `limit` is the AXIS NAME — "seats" | "published" | "previews" |
+ * "storage" — and not a magnitude. It is typed as the transport's union rather
+ * than narrowed to `string`, because the same detail bag carries the byte-valued
+ * `limit` of `publish_too_large`, and a type that disagreed with the transport
+ * would push the mismatch to a cast at the call site.
+ *
+ * NOTHING BELOW READS IT. The axis is already known from the code that selected
+ * the renderer, so reading it back would be the renderer asking the wire to
+ * confirm which function it is. It is declared so the shape is complete and so a
+ * reader can see the field was considered.
+ */
+export interface CountLimitDetail {
+    limit?: number | string;
+    count?: number;
+    ceiling?: number;
+    orgName?: string;
+    orgSlug?: string;
+    planName?: string;
+}
+/**
+ * The org as the CLI can otherwise name it — the machine's configured active
+ * org. It is the FALLBACK and never the authority: see `resolveOrg`.
+ */
+export interface LocalOrgIdentity {
+    name?: string;
+    slug?: string;
+    consoleUrl?: string;
+}
+export interface ResolvedCountLimit {
+    orgName?: string;
+    orgSlug?: string;
+    planName?: string;
+    count: number;
+    ceiling: number;
+    consoleUrl?: string;
+}
+/**
+ * THE WIRE WINS over the machine's configured active org.
+ *
+ * The API names the org that owns the project being acted on; local config names
+ * whichever org the CLI was last pointed at, and on a machine with more than one
+ * workspace they are routinely different. Naming the local one would print the
+ * wrong workspace on the exact screen that is refusing the creator — and the
+ * refusal's figures are about the org the wire named, so a mismatched heading
+ * makes the numbers read as wrong rather than the name.
+ *
+ * The local values remain as a fallback for a body that carried neither, which
+ * is a refusal from an older api rather than a shape this client accepts.
+ */
+export declare function resolveCountLimit(detail: CountLimitDetail, local?: LocalOrgIdentity): ResolvedCountLimit;
+/**
+ * `Acme (acme)` — name and slug when they differ, one of them when they do not,
+ * and an empty string when the wire named neither. Matches f10's shipped
+ * plan-limit heading so the four plan refusals read as one family.
+ */
+export declare function orgLabel(name?: string, slug?: string): string;
+/**
+ * The figures, STACKED AND ALIGNED rather than inline. They are a comparison —
+ * the count against the ceiling — and f2's convention puts two values a creator
+ * must judge on their own aligned lines. Inline they are a sentence to parse;
+ * stacked, an agent and a human read them the same way.
+ */
+export declare function countRows(i: ResolvedCountLimit, axisLabel: string, planSuffix: string): string[];
+/**
+ * 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.
+ *
+ * `path` is the org-scoped page that shows the axis being refused.
+ */
+export declare function consoleLines(i: ResolvedCountLimit, path: string): string[];
+/**
+ * The published-project ceiling, refused at open-publish or at commit.
+ *
+ * Commit re-checks because two publishes opened in the same org can both be
+ * admitted and race to go live; the loser is refused after its bytes were
+ * uploaded. The api keeps those bytes as a stored version, so the last line
+ * changes to say so and nothing else does.
+ *
+ * "One published project" means ONE LIVE ADDRESS AT A TIME, and the copy says
+ * so, because the other reading — one project ever published — is what makes a
+ * creator believe they have permanently spent their slot on a mistake. Taking a
+ * project offline frees it, and that is the sentence that distinguishes the two.
+ *
+ * It does NOT say the project being published is excluded from the count, even
+ * though it is: a creator refused here is publishing a SECOND project, so the
+ * exclusion never applies on the screen that would explain it.
+ */
+export declare function publishedLimitRefused(i: ResolvedCountLimit, stage?: "open" | "commit"): string[];
+/**
+ * The concurrent-preview ceiling, refused at mint.
+ *
+ * "Still running" is the load-bearing claim and it is stated first among the
+ * facts. A creator whose `vincentt preview` just refused has every reason to
+ * believe it took something down — the command that failed is the command that
+ * starts previews — and B-F10-3's guarantee (a count limit refuses growth and
+ * removes nothing) is invisible unless the refusal says it.
+ */
+export declare function previewLimitRefused(i: ResolvedCountLimit): string[];
+/**
+ * The storage ceiling. It NAMES NO FIGURE, and the asymmetry with the three
+ * count refusals above is deliberate rather than an omission: the ceiling is an
+ * abuse ceiling, not a tier limit. It is flat on every plan, never sold, never
+ * displayed, and its only audience is an operator. A number here would be the
+ * product printing a magnitude a creator cannot act on and was never offered.
+ *
+ * Support is therefore the whole remedy — there is no console page showing this
+ * and no plan that raises it.
+ */
+export declare function storageCeilingRefused(): string[];

package/dist/shared/countLimit.js

@@ -0,0 +1,176 @@
+// The three count-limit refusals — seats, published projects, concurrent live
+// previews — as they reach a creator standing at a ceiling.
+//
+// THE REFUSAL IS THE NOTICE. A count limit is evaluated in the same request as
+// the act it refuses, so no earlier moment exists at which a warning could have
+// been delivered (B-F10-2, as amended). The obligation is discharged by the
+// refusal naming the axis, the current count and the ceiling — which means a
+// refusal rendered without its figures does not discharge it at all. That is the
+// whole reason these arms exist rather than the generic `✗ {message}` default.
+//
+// Two prohibitions govern every string below:
+//   - NO PRICE, and no plan other than the one in force. f16's inherited rule: a
+//     surface tells a creator where they stand, never what to buy.
+//   - NO COMMAND that resolves the refusal. An agent's default response to a
+//     failure is to run the next thing it is handed, and there is no CLI verb
+//     that frees a seat, unpublishes a project or ends someone else's preview.
+//     The copy names the act as a human one, in the console.
+const SUPPORT_EMAIL = "hello@vincentt.studio";
+const DEFAULT_CONSOLE_URL = "https://console.vincentt.studio";
+/**
+ * THE WIRE WINS over the machine's configured active org.
+ *
+ * The API names the org that owns the project being acted on; local config names
+ * whichever org the CLI was last pointed at, and on a machine with more than one
+ * workspace they are routinely different. Naming the local one would print the
+ * wrong workspace on the exact screen that is refusing the creator — and the
+ * refusal's figures are about the org the wire named, so a mismatched heading
+ * makes the numbers read as wrong rather than the name.
+ *
+ * The local values remain as a fallback for a body that carried neither, which
+ * is a refusal from an older api rather than a shape this client accepts.
+ */
+export function resolveCountLimit(detail, local) {
+    return {
+        orgName: detail.orgName ?? local?.name,
+        orgSlug: detail.orgSlug ?? local?.slug,
+        planName: detail.planName,
+        count: detail.count ?? 0,
+        ceiling: detail.ceiling ?? 0,
+        consoleUrl: local?.consoleUrl,
+    };
+}
+/**
+ * `Acme (acme)` — name and slug when they differ, one of them when they do not,
+ * and an empty string when the wire named neither. Matches f10's shipped
+ * plan-limit heading so the four plan refusals read as one family.
+ */
+export function orgLabel(name, slug) {
+    if (name && slug && name !== slug)
+        return `${name} (${slug})`;
+    return name || slug || "";
+}
+/**
+ * The figures, STACKED AND ALIGNED rather than inline. They are a comparison —
+ * the count against the ceiling — and f2's convention puts two values a creator
+ * must judge on their own aligned lines. Inline they are a sentence to parse;
+ * stacked, an agent and a human read them the same way.
+ */
+export function countRows(i, axisLabel, planSuffix) {
+    const rows = [];
+    if (i.orgName || i.orgSlug)
+        rows.push(["Organization", orgLabel(i.orgName, i.orgSlug)]);
+    if (i.planName)
+        rows.push(["Plan", `${i.planName} (${planSuffix})`]);
+    rows.push([axisLabel, `${i.count} of ${i.ceiling} used`]);
+    return alignedRows(rows);
+}
+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.
+ *
+ * `path` is the org-scoped page that shows the axis being refused.
+ */
+export function consoleLines(i, path) {
+    if (!i.orgSlug)
+        return [`  Email ${SUPPORT_EMAIL}.`, ""];
+    const base = (i.consoleUrl ?? DEFAULT_CONSOLE_URL).replace(/\/$/, "");
+    return [`  See ${base}/orgs/${i.orgSlug}/${path}, or email`, `  ${SUPPORT_EMAIL}.`, ""];
+}
+// THERE IS NO SEAT ARM HERE, AND THE ABSENCE IS THE DESIGN.
+//
+// `seat_limit` is refused on `POST /orgs/{slug}/invites`, which the CLI does not
+// call and has no verb for: inviting a person is an act whose authorized actor
+// is a human, so it lives in the console (f15's convention). The seat refusal's
+// copy — including the two ways to free a seat — is the console's to render.
+//
+// A renderer for it added here would be an export with no caller, which is worse
+// than nothing: it reads as coverage and cannot fail.
+/**
+ * The published-project ceiling, refused at open-publish or at commit.
+ *
+ * Commit re-checks because two publishes opened in the same org can both be
+ * admitted and race to go live; the loser is refused after its bytes were
+ * uploaded. The api keeps those bytes as a stored version, so the last line
+ * changes to say so and nothing else does.
+ *
+ * "One published project" means ONE LIVE ADDRESS AT A TIME, and the copy says
+ * so, because the other reading — one project ever published — is what makes a
+ * creator believe they have permanently spent their slot on a mistake. Taking a
+ * project offline frees it, and that is the sentence that distinguishes the two.
+ *
+ * It does NOT say the project being published is excluded from the count, even
+ * though it is: a creator refused here is publishing a SECOND project, so the
+ * exclusion never applies on the screen that would explain it.
+ */
+export function publishedLimitRefused(i, stage = "open") {
+    return [
+        "",
+        "✗ This organization is already publishing as many projects as its plan allows.",
+        "",
+        ...countRows(i, "Published", "published projects are counted per organization"),
+        "",
+        "  The count is projects with a live address right now, not projects that have",
+        "  ever been published. Taking one offline in the console frees the slot, and",
+        "  everything already published stays exactly as it is.",
+        "",
+        ...consoleLines(i, "projects"),
+        stage === "commit"
+            ? "  Your files were uploaded and kept, but nothing went live."
+            : "  Nothing was uploaded.",
+        "",
+    ];
+}
+/**
+ * The concurrent-preview ceiling, refused at mint.
+ *
+ * "Still running" is the load-bearing claim and it is stated first among the
+ * facts. A creator whose `vincentt preview` just refused has every reason to
+ * believe it took something down — the command that failed is the command that
+ * starts previews — and B-F10-3's guarantee (a count limit refuses growth and
+ * removes nothing) is invisible unless the refusal says it.
+ */
+export function previewLimitRefused(i) {
+    return [
+        "",
+        "✗ This organization has as many previews running as its plan allows.",
+        "",
+        ...countRows(i, "Previews", "previews are counted per organization"),
+        "",
+        "  Every preview that was running is still running. This one did not start.",
+        "  A preview stops when whoever started it stops it, or when it reaches its",
+        "  12-hour limit.",
+        "",
+        ...consoleLines(i, "projects"),
+        "  Nothing was started.",
+        "",
+    ];
+}
+/**
+ * The storage ceiling. It NAMES NO FIGURE, and the asymmetry with the three
+ * count refusals above is deliberate rather than an omission: the ceiling is an
+ * abuse ceiling, not a tier limit. It is flat on every plan, never sold, never
+ * displayed, and its only audience is an operator. A number here would be the
+ * product printing a magnitude a creator cannot act on and was never offered.
+ *
+ * Support is therefore the whole remedy — there is no console page showing this
+ * and no plan that raises it.
+ */
+export function storageCeilingRefused() {
+    return [
+        "",
+        "✗ This organization cannot upload more files right now.",
+        "",
+        "  This is not a plan limit and taking a different plan will not change it.",
+        "",
+        `  Email ${SUPPORT_EMAIL} and it can be looked at.`,
+        "",
+        "  Nothing was uploaded.",
+        "",
+    ];
+}

package/dist/shared/http.d.ts

@@ -0,0 +1,23 @@
+/** A request that did not finish inside its deadline. Nothing is known about its outcome. */
+export declare class RequestTimeout extends Error {
+    readonly ms: number;
+    constructor(ms: number);
+}
+export declare const API_DEADLINE_MS = 30000;
+/**
+ * Wrap a fetch so each call is aborted after `ms`. The deadline covers the body
+ * read too: the timer is not cleared when headers arrive, and aborting a request
+ * whose body was already read is a no-op. The timer is unref'd so it never holds
+ * the process open. A caller's own signal still aborts the request.
+ */
+export declare function withDeadline(fetchImpl: typeof fetch, ms: number): typeof fetch;
+/**
+ * The global fetch with the api deadline. Looked up per call, never captured, so
+ * a test that stubs the global still reaches its stub.
+ */
+export declare const apiFetch: typeof fetch;
+/**
+ * A request abandoned by the network or by its deadline, as opposed to a
+ * response the server sent. Its outcome on the server is unknown.
+ */
+export declare function isTransportError(err: unknown): boolean;

package/dist/shared/http.js

@@ -0,0 +1,58 @@
+// The one fetch wrapper with a deadline. Every api call goes through apiFetch, so
+// a stalled server or a dead network ends in a bounded error instead of a hang
+// (including the Ctrl-C path, which ends the preview session with an api call).
+/** A request that did not finish inside its deadline. Nothing is known about its outcome. */
+export class RequestTimeout extends Error {
+    ms;
+    constructor(ms) {
+        super(`the request did not finish within ${Math.round(ms / 1000)}s`);
+        this.ms = ms;
+        this.name = "RequestTimeout";
+    }
+}
+export const API_DEADLINE_MS = 30_000;
+/**
+ * Wrap a fetch so each call is aborted after `ms`. The deadline covers the body
+ * read too: the timer is not cleared when headers arrive, and aborting a request
+ * whose body was already read is a no-op. The timer is unref'd so it never holds
+ * the process open. A caller's own signal still aborts the request.
+ */
+export function withDeadline(fetchImpl, ms) {
+    return (async (input, init = {}) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new RequestTimeout(ms)), ms);
+        timer.unref?.();
+        const outer = init.signal;
+        if (outer) {
+            if (outer.aborted)
+                controller.abort(outer.reason);
+            else
+                outer.addEventListener("abort", () => controller.abort(outer.reason), {
+                    once: true,
+                });
+        }
+        try {
+            return await fetchImpl(input, { ...init, signal: controller.signal });
+        }
+        catch (err) {
+            if (controller.signal.reason instanceof RequestTimeout)
+                throw controller.signal.reason;
+            throw err;
+        }
+    });
+}
+/**
+ * The global fetch with the api deadline. Looked up per call, never captured, so
+ * a test that stubs the global still reaches its stub.
+ */
+export const apiFetch = withDeadline((input, init) => globalThis.fetch(input, init), API_DEADLINE_MS);
+/**
+ * A request abandoned by the network or by its deadline, as opposed to a
+ * response the server sent. Its outcome on the server is unknown.
+ */
+export function isTransportError(err) {
+    if (err instanceof RequestTimeout)
+        return true;
+    // undici reports a refused, reset or unresolvable connection as a TypeError.
+    return err instanceof TypeError || (err instanceof Error && err.name === "AbortError");
+}

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "MIGRATION.md"
   ],
   "exports": {
     "./preview": {
@@ -20,11 +21,14 @@
   "bin": {
     "vincentt": "./dist/cli/index.js"
   },
+  "engines": {
+    "node": ">=18"
+  },
   "dependencies": {
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "1.5.0"
+    "@vincentt-xr/harness": "1.6.0"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",