@vincentt-xr/cli 0.17.0 → 0.18.0

package/dist/preview/runner.js

@@ -13,21 +13,33 @@
 // Returns the public URL plus a `stop()` that reaps everything. A failure at any
 // step tears down what was already started, so the caller never leaks a child
 // process or a live session.
-import { spawn } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { realpath } from "node:fs/promises";
 import { createServer } from "node:http";
 import { TunnelClient, resolveForwardTarget, } from "@vincentt-xr/harness/tunnel";
 import { startRelay } from "../relay/server.js";
-import { proxyWeb, proxyWs } from "./proxy.js";
+import { isHiddenAppPath, proxyWeb, proxyWs, relayRoute } from "./proxy.js";
 import { getFreePort, isPortListening, waitForApp } from "./net.js";
 import { endPreviewSession, heartbeatPreviewSession, mintPreviewSession, workingTreeKey, PreviewEndedError, } from "./api.js";
+import { withoutCliCredentials } from "../shared/config.js";
 import { ProjectUnreachableError } from "../lib/backend.js";
+import { AuthExpiredError } from "../shared/authError.js";
+import { apiFetch } from "../shared/http.js";
+/** The path a 404 advisory names: the request's own path, without its query. */
+export function requestPathOf(url) {
+    const raw = (url ?? "/").split("?")[0] ?? "/";
+    // Control characters never reach the terminal from a request line.
+    return raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, "");
+}
 export async function startPreview(opts) {
-    const { projectCwd, projectRoot = projectCwd, config, projectId, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", appReadyTimeoutMs = 8_000, onLog = () => undefined, fetchImpl = fetch, } = opts;
+    const { projectCwd, projectRoot = projectCwd, config, projectId, harnessPath = "/__harness", devCommand = ["npm", "run", "dev"], appStdio = "ignore", appReadyTimeoutMs = 8_000, onLog = () => undefined, fetchImpl = apiFetch, } = opts;
     const appPort = opts.appPort ?? 5173;
     const relayPort = opts.relayPort ?? (await getFreePort());
     const frontPort = opts.frontPort ?? (await getFreePort());
     const reuseApp = await isPortListening(appPort);
+    const hiddenRoot = await realpath(projectRoot).catch(() => projectRoot);
     let app;
+    let killApp;
     let relay;
     let front;
     let tunnel;
@@ -41,7 +53,13 @@ export async function startPreview(opts) {
         if (heartbeat !== undefined)
             clearInterval(heartbeat);
         tunnel?.close();
-        app?.kill();
+        if (killApp) {
+            process.removeListener("exit", killApp);
+            killApp();
+        }
+        else {
+            app?.kill();
+        }
         front?.close();
         if (relay)
             await relay.close();
@@ -64,13 +82,59 @@ export async function startPreview(opts) {
             onLog(`reusing the dev server already on :${appPort}`);
         }
         else {
-            app = spawn(devCommand[0], devCommand.slice(1), {
-                cwd: projectCwd,
-                env: { ...process.env, PORT: String(appPort) },
-                stdio: appStdio,
-                // Windows: npm/pnpm are .cmd shims — spawn needs a shell to resolve them.
-                shell: process.platform === "win32",
-            });
+            // The dev command runs where the binding lives, and its environment carries
+            // no CLI credential: the command is repo-controlled and arrives by pull
+            // request. The machine config file stays readable to it (a recorded limit).
+            const env = { ...withoutCliCredentials(process.env), PORT: String(appPort) };
+            // A shell command such as `a && npm run serve` puts the dev server one or
+            // more processes below the shell, so signalling the shell alone orphans it.
+            // On POSIX the shell leads its own process group and stop() signals the
+            // group. Its stdin is never the terminal: a background group reading the
+            // terminal would be stopped by SIGTTIN.
+            const grouped = typeof devCommand === "string" && process.platform !== "win32";
+            app =
+                typeof devCommand === "string"
+                    ? spawn(devCommand, {
+                        cwd: projectRoot,
+                        env,
+                        stdio: appStdio === "inherit" ? ["ignore", "inherit", "inherit"] : "ignore",
+                        shell: true,
+                        detached: grouped,
+                    })
+                    : spawn(devCommand[0], devCommand.slice(1), {
+                        cwd: projectRoot,
+                        env,
+                        stdio: appStdio,
+                        // Windows: npm/pnpm are .cmd shims — spawn needs a shell to resolve them.
+                        shell: process.platform === "win32",
+                    });
+            if (grouped && app.pid !== undefined) {
+                const pid = app.pid;
+                killApp = () => {
+                    try {
+                        process.kill(-pid, "SIGTERM");
+                    }
+                    catch {
+                        app?.kill();
+                    }
+                };
+                // Best effort for an exit that skips stop(); a SIGKILL of this process
+                // still orphans the group, as it always orphaned the dev server.
+                process.once("exit", killApp);
+            }
+            else if (process.platform === "win32" && app.pid !== undefined) {
+                // On Windows the dev server runs under a cmd.exe shim, and killing the
+                // shim leaves the server running. taskkill /T ends the whole tree.
+                const pid = app.pid;
+                killApp = () => {
+                    const r = spawnSync("taskkill", ["/pid", String(pid), "/T", "/F"], {
+                        stdio: "ignore",
+                    });
+                    if (r.status !== 0)
+                        app?.kill();
+                };
+                process.once("exit", killApp);
+            }
         }
         relay = startRelay({
             port: relayPort,
@@ -85,8 +149,22 @@ export async function startPreview(opts) {
             onCapReached: opts.onCapReached,
             onAnnotation: opts.onAnnotation,
         });
+        // Fixed here, from the server-computed URL, and never from a request.
+        const previewOrigin = new URL(minted.url).origin;
         front = createServer((req, res) => {
-            const toRelay = req.url?.startsWith(harnessPath) === true;
+            const route = relayRoute(req.url ?? "/", harnessPath, "http");
+            if (route === "refuse") {
+                res.writeHead(404, { "content-type": "text/plain", "cache-control": "no-store" });
+                res.end("Not found");
+                return;
+            }
+            const toRelay = route === "relay";
+            if (!toRelay && isHiddenAppPath(req.url ?? "/", hiddenRoot)) {
+                opts.onHiddenPath?.(requestPathOf(req.url));
+                res.writeHead(404, { "content-type": "text/plain", "cache-control": "no-store" });
+                res.end("Not found");
+                return;
+            }
             // Recovery is signalled by normal output resuming, so the re-arm has to
             // happen on a SUCCESSFUL response rather than on a timer. A relay request
             // is not the creator's app and must not clear an app failure.
@@ -98,8 +176,22 @@ export async function startPreview(opts) {
             }
             proxyWeb(req, res, toRelay ? relayPort : appPort, () => opts.onOriginError?.("", "origin_unreachable"));
         });
-        front.on("upgrade", (req, socket, head) => proxyWs(req, socket, head, req.url?.startsWith(harnessPath) ? relayPort : appPort));
-        await new Promise((resolve) => front.listen(frontPort, resolve));
+        front.on("upgrade", (req, socket, head) => {
+            const route = relayRoute(req.url ?? "/", harnessPath, "upgrade");
+            if (route === "relay") {
+                proxyWs(req, socket, head, relayPort);
+                return;
+            }
+            if (route === "refuse" || isHiddenAppPath(req.url ?? "/", hiddenRoot)) {
+                if (route === "app")
+                    opts.onHiddenPath?.(requestPathOf(req.url));
+                socket.end("HTTP/1.1 404 Not Found\r\nconnection: close\r\ncontent-length: 0\r\n\r\n");
+                return;
+            }
+            proxyWs(req, socket, head, appPort, { rewriteOriginFrom: previewOrigin });
+        });
+        // Loopback only: the tunnel client on this machine is the one intended caller.
+        await new Promise((resolve) => front.listen(frontPort, "127.0.0.1", resolve));
         // ONE configured target, captured HERE from the creator's own config and
         // never from a request (2.15.4 rule 1). The loopback assertion runs at
         // start and is re-checked at every connect.
@@ -138,8 +230,15 @@ export async function startPreview(opts) {
         // RequireMembership on the API side, so a project transferred out from
         // under a live preview, or a member removed from the org, ends it on the
         // next beat rather than at the 12-hour ceiling.
+        // One beat in flight at a time: a slow api must not stack up requests.
+        let beating = false;
         heartbeat = setInterval(() => {
-            void runHeartbeat(config, minted.sessionId, fetchImpl, opts.onEnded);
+            if (beating)
+                return;
+            beating = true;
+            void runHeartbeat(config, minted.sessionId, fetchImpl, opts.onEnded).finally(() => {
+                beating = false;
+            });
         }, minted.heartbeatSec * 1000);
         // Node must not be held alive by the heartbeat alone — the tunnel and the
         // relay are what keep the process up, and a stray interval would outlive a
@@ -147,7 +246,7 @@ export async function startPreview(opts) {
         heartbeat.unref?.();
         const appReady = reuseApp ? true : await waitForApp(appPort, appReadyTimeoutMs);
         if (!appReady) {
-            onLog(`app on :${appPort} isn't responding yet — the URL may be blank until it builds`);
+            onLog(`app on :${appPort} isn't responding yet; the URL may be blank until it builds`);
         }
         return {
             url: minted.url,
@@ -205,7 +304,8 @@ export function refusalToReason(status) {
 /**
  * One heartbeat. A 410 is the session ending on the server's terms; a 404/403
  * is authorization lost. They are DELIBERATELY NOT MERGED, because the remedies
- * differ: one is "find out who you are", the other is "try again".
+ * differ: one is "find out who you are", the other is "try again". A 401 is the
+ * token itself refused, and its remedy is signing in again.
  *
  * A transport failure is neither — the API being briefly unreachable must not
  * end a healthy preview, because the edge already fails closed on its own
@@ -217,17 +317,19 @@ export function refusalToReason(status) {
  * superseded, or stopped elsewhere, all answer 410, and the hard-max screen is a
  * `✓` telling the creator the preview did exactly what it promised over 12 hours.
  *
- * The API's 410 body carries ONE opaque code (`preview_session_ended`) for every
- * terminal reason — verified against the running stack: an `abandoned` row and an
- * `expired` row return byte-identical bodies — so the CLI CANNOT tell them apart
- * and must not guess. `session_ended` is the honest, cause-free rendering until
- * the wire carries the discriminator. See the note on PreviewEndedError.
+ * The API's 410 carries the terminal reason under `detail.endReason`, and each
+ * reason maps to its own screen. A 410 with no reason gets the cause-free
+ * ending. See the note on PreviewEndedError.
  */
 export async function runHeartbeat(config, sessionId, fetchImpl, onEnded) {
     try {
         await heartbeatPreviewSession(config, sessionId, fetchImpl);
     }
     catch (err) {
+        if (err instanceof AuthExpiredError) {
+            onEnded?.("auth_expired");
+            return;
+        }
         if (err instanceof ProjectUnreachableError) {
             onEnded?.("authz_revoked");
             return;
@@ -242,10 +344,9 @@ export async function runHeartbeat(config, sessionId, fetchImpl, onEnded) {
 /**
  * The API's `endReason` → the CLI's ending screen.
  *
- * `hard_max` is returned ONLY for an explicit `expired`. An UNLABELLED 410 —
- * which is every 410 the API sends today — maps to `grace_exhausted`, the one
- * ending whose copy states only what is actually known: the preview has ended
- * and the link no longer works. It asserts no cause.
+ * `hard_max` is returned ONLY for an explicit `expired`. An UNLABELLED 410 maps
+ * to `grace_exhausted`, the one ending whose copy states only what is actually
+ * known: the preview has ended and the link no longer works. It asserts no cause.
  *
  * That default is the conservative choice and it is deliberate. `hard_max` is a
  * `✓` claiming the preview ran its full 12 hours; rendering it for a session the

package/dist/preview/viewers.js

@@ -171,7 +171,7 @@ export class ViewerRoster {
             return undefined;
         return [
             `! A connection that reconnects gets a new label. If ${gone.label} came back,`,
-            `  it is ${label} now — labels last one connection. Testers survive a refresh.`,
+            `  it is ${label} now. Labels last one connection. Testers survive a refresh.`,
         ];
     }
     disconnect(label, now) {

package/dist/publish/api.d.ts

@@ -1,12 +1,22 @@
 import type { ResolvedConfig } from "../shared/config.js";
 import type { ManifestEntry } from "./manifest.js";
 import type { BuiltWith } from "../platform/resolve.js";
+/**
+ * The api's publish states, `domain.PublishState*`. apiPublishStates.test.ts
+ * checks this list against the committed api capture, so a state the api adds
+ * fails the suite on the next capture refresh instead of reaching a checklist
+ * that has no arm for it.
+ */
+export declare const PUBLISH_STATES: readonly ["never", "live", "unpublished", "not_serving", "held_by_platform"];
+export type PublishState = (typeof PUBLISH_STATES)[number];
+/** A state outside PUBLISH_STATES reads as `unknown`, never as a guess at a known one. */
+export declare function parsePublishState(raw: string | null): PublishState | "unknown";
 export interface PublishProject {
     id: string;
     slug: string;
     name: string;
     liveUrl: string;
-    publishState: "never" | "live" | "unpublished" | "not_serving";
+    publishState: PublishState | "unknown";
     firstPublishedAt: string | null;
     liveVersion: number | null;
     highestVersion: number | null;
@@ -31,14 +41,21 @@ export interface OpenedUpload {
     uploads: UploadTarget[];
     expiresAt: string;
 }
+/** The api's `commitResponse`. apiPublishStates.test.ts checks these keys against the capture. */
 export interface CommitResult {
     version: number;
-    liveVersion: number;
-    highestVersion: number;
+    liveVersion: number | null;
+    highestVersion: number | null;
     liveUrl: string;
     publishedAt: string;
-    /** Response-side name of the request's `note`. The asymmetry is deliberate. */
-    releaseNote?: string;
+}
+/**
+ * The api answered 2xx to a commit but the body is not a commit response. The
+ * version may well be live, so this is never reported as "unchanged".
+ */
+export declare class MalformedCommitResponse extends Error {
+    readonly reason: string;
+    constructor(reason: string);
 }
 export interface ApiErrorDetail {
     /**

package/dist/publish/api.js

@@ -1,11 +1,73 @@
 // The three-call publish transaction against the Go API, built against
-// implementation.md §2.7's contract table — every wire field named canonically
-// once, and the deliberate asymmetry (request `note`, response `releaseNote`)
-// carried as written.
+// implementation.md §2.7's contract table, every wire field named canonically
+// once. The request's `note` comes back as `releaseNote` on the version list,
+// never on the commit response.
 //
 // The bytes do NOT transit the API. Open returns one presigned PUT per file,
 // each signed for one exact key; the CLI PUTs direct to S3 and then commits.
 import { clientHeaders } from "../shared/clientHeader.js";
+import { rejectAuthExpired } from "../shared/authError.js";
+import { apiFetch } from "../shared/http.js";
+/**
+ * The api's publish states, `domain.PublishState*`. apiPublishStates.test.ts
+ * checks this list against the committed api capture, so a state the api adds
+ * fails the suite on the next capture refresh instead of reaching a checklist
+ * that has no arm for it.
+ */
+export const PUBLISH_STATES = [
+    "never",
+    "live",
+    "unpublished",
+    "not_serving",
+    "held_by_platform",
+];
+/** A state outside PUBLISH_STATES reads as `unknown`, never as a guess at a known one. */
+export function parsePublishState(raw) {
+    if (raw === null)
+        return "never";
+    return PUBLISH_STATES.includes(raw)
+        ? raw
+        : "unknown";
+}
+/**
+ * The api answered 2xx to a commit but the body is not a commit response. The
+ * version may well be live, so this is never reported as "unchanged".
+ */
+export class MalformedCommitResponse extends Error {
+    reason;
+    constructor(reason) {
+        super(`commit: ${reason}`);
+        this.reason = reason;
+        this.name = "MalformedCommitResponse";
+    }
+}
+function parseCommitResult(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new MalformedCommitResponse("response is not an object");
+    }
+    const r = raw;
+    const intOrNull = (k) => {
+        const v = r[k];
+        if (v === null || v === undefined)
+            return null;
+        if (typeof v === "number" && Number.isInteger(v))
+            return v;
+        throw new MalformedCommitResponse(`${k} is not an integer`);
+    };
+    if (typeof r.version !== "number" || !Number.isInteger(r.version)) {
+        throw new MalformedCommitResponse("version is not an integer");
+    }
+    if (typeof r.liveUrl !== "string" || r.liveUrl === "") {
+        throw new MalformedCommitResponse("liveUrl is missing");
+    }
+    return {
+        version: r.version,
+        liveVersion: intOrNull("liveVersion"),
+        highestVersion: intOrNull("highestVersion"),
+        liveUrl: r.liveUrl,
+        publishedAt: typeof r.publishedAt === "string" ? r.publishedAt : "",
+    };
+}
 export class PublishApiError extends Error {
     status;
     code;
@@ -20,7 +82,9 @@ export class PublishApiError extends Error {
         this.name = "PublishApiError";
     }
 }
+/** Rejects with AuthExpiredError on a 401; every other status becomes a PublishApiError. */
 async function readError(res) {
+    rejectAuthExpired(res);
     let body = {};
     try {
         body = (await res.json());
@@ -35,7 +99,7 @@ function authHeaders(cfg) {
     return { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
 }
 /** The ONE call before the checklist. liveVersion + livePublishedAt ride it, by design. */
-export async function readProject(cfg, projectId, fetchImpl = fetch) {
+export async function readProject(cfg, projectId, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}`, {
         headers: authHeaders(cfg),
     });
@@ -49,7 +113,7 @@ export async function readProject(cfg, projectId, fetchImpl = fetch) {
         slug: String(raw.slug ?? ""),
         name: typeof raw.name === "string" ? raw.name : String(raw.slug ?? ""),
         liveUrl: str("liveUrl") ?? "",
-        publishState: (str("publishState") ?? "never"),
+        publishState: parsePublishState(str("publishState")),
         firstPublishedAt: str("firstPublishedAt"),
         liveVersion: num("liveVersion"),
         highestVersion: num("highestVersion"),
@@ -72,7 +136,7 @@ export async function readProject(cfg, projectId, fetchImpl = fetch) {
  * an empty object. `{}` means "resolution ran and found nothing", a different
  * and specific fact.
  */
-export async function openUpload(cfg, projectId, files, note, fetchImpl = fetch, builtWith) {
+export async function openUpload(cfg, projectId, files, note, fetchImpl = apiFetch, builtWith) {
     const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes`, {
         method: "POST",
         headers: { ...authHeaders(cfg), "content-type": "application/json" },
@@ -94,14 +158,21 @@ export async function openUpload(cfg, projectId, files, note, fetchImpl = fetch,
         expiresAt: body.expiresAt ?? "",
     };
 }
-export async function commitUpload(cfg, projectId, uploadId, fetchImpl = fetch) {
+export async function commitUpload(cfg, projectId, uploadId, fetchImpl = apiFetch) {
     const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}/commit`, { method: "POST", headers: authHeaders(cfg) });
     if (!res.ok)
         throw await readError(res);
-    return (await res.json());
+    let raw;
+    try {
+        raw = await res.json();
+    }
+    catch {
+        throw new MalformedCommitResponse("response is not JSON");
+    }
+    return parseCommitResult(raw);
 }
 /** Abandon an open upload. Idempotent server-side; a failure here must never mask the real error. */
-export async function abandonUpload(cfg, projectId, uploadId, fetchImpl = fetch) {
+export async function abandonUpload(cfg, projectId, uploadId, fetchImpl = apiFetch) {
     try {
         await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/publishes/${encodeURIComponent(uploadId)}`, { method: "DELETE", headers: authHeaders(cfg) });
     }

package/dist/publish/command.d.ts

@@ -1,5 +1,6 @@
 import type { ResolvedConfig } from "../shared/config.js";
 import { type BuiltWith } from "../platform/resolve.js";
+import { type VincenttJson } from "../lib/settings.js";
 export interface PublishDeps {
     print: (line: string) => void;
     /** Raw write, for the redrawn progress line only. */
@@ -8,10 +9,14 @@ export interface PublishDeps {
     confirm: (prompt: string, defaultYes: boolean) => Promise<boolean>;
     cwd: string;
     config: () => Promise<ResolvedConfig>;
+    /** `dir` is the directory holding the binding; absent, the working directory stands in. */
     binding: () => Promise<{
         projectId: string;
         slug: string;
+        dir?: string;
     } | undefined>;
+    /** Injected for tests. Defaults to reading `<root>/vincentt.json`. */
+    readSettings?: (root: string) => Promise<VincenttJson | undefined>;
     /** Absent means not signed in — the gate is LOCAL and nothing is attempted. */
     token: () => Promise<string | undefined>;
     isTTY: boolean;
@@ -31,10 +36,30 @@ export interface PublishDeps {
      * mechanical proof there is one resolver and not two that drifted.
      */
     builtWith?: () => Promise<BuiltWith | undefined>;
+    /** Fetch for the post-commit probe of the public address. Defaults to fetchImpl, then the global. */
+    probeFetch?: typeof fetch;
+    /** Where the --json document goes (stdout). Defaults to print. */
+    emit?: (line: string) => void;
 }
 export interface PublishOptions {
     distDir?: string;
     note?: string;
     yes?: boolean;
+    /** Print one JSON document at the end; the caller routes `print` elsewhere. */
+    json?: boolean;
 }
+/**
+ * The --json document. `live` means the address served the new index.html;
+ * `committed_not_visible` means the commit succeeded but the wait ran out;
+ * `failed` covers every other ending, with the human copy on stderr.
+ */
+export type PublishReport = {
+    state: "live" | "committed_not_visible";
+    version: number;
+    liveUrl: string;
+    waitedMs: number;
+} | {
+    state: "failed";
+    exitCode: number;
+};
 export declare function publishCommand(deps: PublishDeps, opts?: PublishOptions): Promise<number>;