@vincentt-xr/cli 0.17.0 → 0.18.1

package/dist/relay/server.d.ts

@@ -1,9 +1,16 @@
+import { type IncomingMessage } from "node:http";
 import { EventStore } from "./store.js";
 import { TesterRegistry } from "./testers.js";
 import { AnnotationStore } from "./annotations.js";
 import type { DiagEvent } from "@vincentt-xr/harness/events";
 export interface RelayOptions {
     port?: number;
+    /**
+     * The interface to listen on. Loopback by default and in every caller: the
+     * phone reaches the relay only through the tunnel client on this machine,
+     * which dials loopback, and `/query` and `feedback/next` are local-only.
+     */
+    host?: string;
     /** WS path the client connects to (default matches HarnessProvider). */
     path?: string;
     capacity?: number;
@@ -92,6 +99,20 @@ export declare function startRelay(opts?: RelayOptions): RelayHandle;
  * does not match is not a label, and the events simply carry no viewer.
  */
 export declare function readViewerLabel(raw: string | string[] | undefined): string | undefined;
+/**
+ * Whether a request arrived through the preview tunnel. The tunnel client stamps
+ * `x-vincentt-viewer` on EVERY request it forwards, after it has sanitised the
+ * viewer's headers, so a viewer cannot remove it; a local CLI never sends it.
+ * Any value counts, including a malformed or duplicated one: presence is the
+ * signal, and a viewer adding a second copy only makes it more present.
+ */
+export declare function cameThroughTunnel(req: IncomingMessage): boolean;
+/**
+ * A raw request path the relay refuses before `URL` normalises it: a `.` or `..`
+ * segment, or an encoded dot or separator. Without this, `/__harness/../query`
+ * normalises onto a local-only route.
+ */
+export declare function isUnsafeRelayPath(rawUrl: string): boolean;
 /**
  * Clamp the hold to `[0, MAX]`, explicitly, with `0` meaning ANSWER NOW.
  *

package/dist/relay/server.js

@@ -117,7 +117,8 @@ export function startRelay(opts = {}) {
         });
         ws.on("close", () => log("client disconnected"));
     });
-    http.listen(port, () => log(`relay listening on :${port} (ws ${wsPath}, http /query)`));
+    const host = opts.host ?? "127.0.0.1";
+    http.listen(port, host, () => log(`relay listening on ${host}:${port} (ws ${wsPath}, http /query)`));
     return {
         store,
         annotations,
@@ -140,9 +141,42 @@ export function readViewerLabel(raw) {
         return undefined;
     return VIEWER_LABEL_RE.test(raw) ? raw : undefined;
 }
+/**
+ * Whether a request arrived through the preview tunnel. The tunnel client stamps
+ * `x-vincentt-viewer` on EVERY request it forwards, after it has sanitised the
+ * viewer's headers, so a viewer cannot remove it; a local CLI never sends it.
+ * Any value counts, including a malformed or duplicated one: presence is the
+ * signal, and a viewer adding a second copy only makes it more present.
+ */
+export function cameThroughTunnel(req) {
+    return req.headers[VIEWER_STAMP_HEADER] !== undefined;
+}
+/**
+ * A raw request path the relay refuses before `URL` normalises it: a `.` or `..`
+ * segment, or an encoded dot or separator. Without this, `/__harness/../query`
+ * normalises onto a local-only route.
+ */
+export function isUnsafeRelayPath(rawUrl) {
+    const raw = rawUrl.split("?")[0] ?? "";
+    if (/%(2e|2f|5c)/i.test(raw) || raw.includes("\\"))
+        return true;
+    return raw.split("/").some((s) => s === "." || s === "..");
+}
 function handleHttp(req, res, ctx) {
+    if (isUnsafeRelayPath(req.url ?? "/")) {
+        res.writeHead(404).end();
+        return;
+    }
     const url = new URL(req.url ?? "/", "http://localhost");
     const p = url.pathname;
+    // Local-only: the diagnostics read and the reverse-channel drain belong to
+    // the creator's own CLI. A link holder reaches the relay only through the
+    // tunnel, and is refused here even if a route to it were ever opened.
+    const localOnly = p === "/query" || p === `${ctx.wsPath}/feedback/next`;
+    if (localOnly && cameThroughTunnel(req)) {
+        res.writeHead(404).end();
+        return;
+    }
     if (p === "/query") {
         handleQuery(req, res, url, ctx);
         return;

package/dist/shared/authError.d.ts

@@ -1 +1,28 @@
+export declare const AUTH_EXPIRED_MESSAGE = "Your Vincentt access token is no longer valid. Run `vincentt login` to sign in again.";
 export declare function authFailureMessage(label: string, status: number, detail: string): string;
+/**
+ * The api refused the token. Distinct from every other refusal because the
+ * remedy is the same wherever it happens and it is not a retry: a command that
+ * reads it prints authExpiredLines() and exits EXIT.NOT_AUTHENTICATED.
+ */
+export declare class AuthExpiredError extends Error {
+    readonly status = 401;
+    constructor();
+}
+/**
+ * Every authenticated api client calls this on a non-OK response before it
+ * reads the error body. authPaths.test.ts drives each client with a 401 and
+ * fails if one reaches its own error arm instead.
+ */
+export declare function rejectAuthExpired(res: Response): void;
+export declare function authExpiredLines(): string[];
+export declare const NOT_SIGNED_IN_LINES: readonly string[];
+/** No token on this machine. Thrown where a verb needs one and cannot ask for it. */
+export declare class NotSignedInError extends Error {
+    constructor();
+}
+/**
+ * The api refused the token, in either shape a client reports it: the shared
+ * AuthExpiredError, or a client error carrying the 401 status.
+ */
+export declare function isAuthRefused(err: unknown): boolean;

package/dist/shared/authError.js

@@ -2,10 +2,54 @@
 // universal first-run state: every existing `vct_` token was invalidated, so the raw
 // "(401): <body>" is unactionable noise for every user at once. Name the cause and give
 // the one instruction that fixes it. Any other status keeps its existing "(<n>): <body>"
-// shape — a 500/timeout is a different problem and must not be mislabeled a stale token.
+// shape: a 500/timeout is a different problem and must not be mislabeled a stale token.
+export const AUTH_EXPIRED_MESSAGE = "Your Vincentt access token is no longer valid. Run `vincentt login` to sign in again.";
 export function authFailureMessage(label, status, detail) {
-    if (status === 401) {
-        return "Your Vincentt access token is no longer valid — run `vincentt login` to sign in again.";
-    }
+    if (status === 401)
+        return AUTH_EXPIRED_MESSAGE;
     return `${label} (${status})${detail ? `: ${detail}` : ""}`;
 }
+/**
+ * The api refused the token. Distinct from every other refusal because the
+ * remedy is the same wherever it happens and it is not a retry: a command that
+ * reads it prints authExpiredLines() and exits EXIT.NOT_AUTHENTICATED.
+ */
+export class AuthExpiredError extends Error {
+    status = 401;
+    constructor() {
+        super(AUTH_EXPIRED_MESSAGE);
+        this.name = "AuthExpiredError";
+    }
+}
+/**
+ * Every authenticated api client calls this on a non-OK response before it
+ * reads the error body. authPaths.test.ts drives each client with a 401 and
+ * fails if one reaches its own error arm instead.
+ */
+export function rejectAuthExpired(res) {
+    if (res.status === 401)
+        throw new AuthExpiredError();
+}
+export function authExpiredLines() {
+    return ["", `✗ ${AUTH_EXPIRED_MESSAGE}`, ""];
+}
+export const NOT_SIGNED_IN_LINES = [
+    "✗ You're not signed in.",
+    "  Run `vincentt login` to connect this machine to your Vincentt account.",
+];
+/** No token on this machine. Thrown where a verb needs one and cannot ask for it. */
+export class NotSignedInError extends Error {
+    constructor() {
+        super(NOT_SIGNED_IN_LINES.join("\n"));
+        this.name = "NotSignedInError";
+    }
+}
+/**
+ * The api refused the token, in either shape a client reports it: the shared
+ * AuthExpiredError, or a client error carrying the 401 status.
+ */
+export function isAuthRefused(err) {
+    if (err instanceof AuthExpiredError)
+        return true;
+    return err instanceof Error && err.status === 401;
+}

package/dist/shared/config.d.ts

@@ -117,7 +117,27 @@ export interface ResolvedConfig {
     apiUrl: string;
     pat: string;
 }
-export declare 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 declare const CLI_CREDENTIAL_ENV: readonly string[];
+export declare function withoutCliCredentials(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare 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 declare function configuredApiUrl(input: {
+    flagApiUrl?: string;
+    envApiUrl?: string;
+    machineApiUrl?: string;
+}): string;
+/** configuredApiUrl from this process's environment and a machine config already read. */
+export declare function machineApiUrl(machine: Partial<MachineConfig>, flagApiUrl?: string): string;
 export interface ResolveConfigOptions {
     /** Honor a binding's apiUrl override (the `--allow-custom-api` flag). */
     allowCustomApi?: boolean;

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

@@ -74,7 +74,12 @@ export declare function countRows(i: ResolvedCountLimit, axisLabel: string, plan
  */
 export declare function consoleLines(i: ResolvedCountLimit, path: string): string[];
 /**
- * The published-project ceiling, refused at open-publish.
+ * 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
@@ -85,7 +90,7 @@ export declare function consoleLines(i: ResolvedCountLimit, path: string): strin
  * 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): string[];
+export declare function publishedLimitRefused(i: ResolvedCountLimit, stage?: "open" | "commit"): string[];
 /**
  * The concurrent-preview ceiling, refused at mint.
  *

package/dist/shared/countLimit.js

@@ -61,7 +61,7 @@ export function countRows(i, axisLabel, planSuffix) {
     if (i.orgName || i.orgSlug)
         rows.push(["Organization", orgLabel(i.orgName, i.orgSlug)]);
     if (i.planName)
-        rows.push(["Plan", `${i.planName} — ${planSuffix}`]);
+        rows.push(["Plan", `${i.planName} (${planSuffix})`]);
     rows.push([axisLabel, `${i.count} of ${i.ceiling} used`]);
     return alignedRows(rows);
 }
@@ -92,7 +92,12 @@ export function consoleLines(i, path) {
 // 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.
+ * 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
@@ -103,7 +108,7 @@ export function consoleLines(i, path) {
  * 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) {
+export function publishedLimitRefused(i, stage = "open") {
     return [
         "",
         "✗ This organization is already publishing as many projects as its plan allows.",
@@ -115,7 +120,9 @@ export function publishedLimitRefused(i) {
         "  everything already published stays exactly as it is.",
         "",
         ...consoleLines(i, "projects"),
-        "  Nothing was uploaded.",
+        stage === "commit"
+            ? "  Your files were uploaded and kept, but nothing went live."
+            : "  Nothing was uploaded.",
         "",
     ];
 }
@@ -135,7 +142,7 @@ export function previewLimitRefused(i) {
         "",
         ...countRows(i, "Previews", "previews are counted per organization"),
         "",
-        "  Every preview that was running is still running — this one did not start.",
+        "  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.",
         "",

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.17.0",
+  "version": "0.18.1",
   "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.1"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",