@vincentt-xr/cli 0.16.0 → 0.18.0

package/dist/lib/settle.js

@@ -0,0 +1,338 @@
+// Settle `vincentt.json` after a joining verb wrote its binding: recognise a
+// template (and stop, printing nothing), else detect, report, optionally prompt,
+// and write the file. Shared by `link` and `create`'s register path so both
+// joining routes end in the same state.
+//
+// Rules this keeps:
+//  - a present file is never overwritten; differences are reported, not applied;
+//  - a report is byte-identical with and without a TTY; the prompt block is the
+//    only TTY difference, and `--json` never prompts;
+//  - nothing is run: detection reads files only (detect.ts).
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { DETECT_MAX_BYTES, detect, } from "./detect.js";
+import { coerceField, describeProblem, fieldOf, parseSettings, readSettingsText, serializeSettings, SETTINGS_FIELDS, SETTINGS_FILE, SettingsError, TEMPLATE_DEFAULTS, } from "./settings.js";
+import { isTemplateProject } from "./template.js";
+import { escapeControl } from "./terminalText.js";
+const FLAG_OF = {
+    "dev.command": "devCommand",
+    "dev.port": "devPort",
+    "build.command": "buildCommand",
+    "build.output": "buildOutput",
+};
+const FLAG_NAME = {
+    "dev.command": "--dev-command",
+    "dev.port": "--dev-port",
+    "build.command": "--build-command",
+    "build.output": "--build-output",
+};
+const LABEL = {
+    "dev.command": "Dev command",
+    "dev.port": "Dev port",
+    "build.command": "Build command",
+    "build.output": "Build output",
+};
+const PLACEHOLDER = {
+    "dev.command": '"<command>"',
+    "dev.port": "<port>",
+    "build.command": '"<command>"',
+    "build.output": '"<folder>"',
+};
+const VERB_REMEDY = {
+    "dev.command": { verb: "preview", run: 'vincentt preview --dev-command "<command>"' },
+    "dev.port": { verb: "preview", run: "vincentt preview --port <port>" },
+    "build.output": { verb: "publish", run: "vincentt publish --dist <folder>" },
+};
+/** The real probes: read-only, capped, and confined to the project's own tree. */
+export function fsProbes(root) {
+    const confined = async (rel) => {
+        const abs = path.join(root, rel);
+        try {
+            const [real, realRoot] = await Promise.all([fs.realpath(abs), fs.realpath(root)]);
+            const inside = path.relative(realRoot, real);
+            if (inside.startsWith("..") || path.isAbsolute(inside))
+                return undefined;
+            return real;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        exists: async (rel) => (await confined(rel)) !== undefined,
+        readText: async (rel) => {
+            const real = await confined(rel);
+            if (!real)
+                return { missing: true };
+            const stat = await fs.stat(real).catch(() => undefined);
+            if (!stat)
+                return { missing: true };
+            // Never open anything but a regular file: a FIFO or a device would block.
+            if (!stat.isFile())
+                return { notFile: true };
+            if (stat.size > DETECT_MAX_BYTES)
+                return { tooLarge: true };
+            return { text: await fs.readFile(real, "utf8") };
+        },
+    };
+}
+function wordCount(n) {
+    return ["No", "One", "Two", "Three", "Four"][n] ?? String(n);
+}
+function snippet(field, written) {
+    const section = field.startsWith("dev.") ? "dev" : "build";
+    const parts = [];
+    for (const f of SETTINGS_FIELDS) {
+        if (!f.startsWith(`${section}.`))
+            continue;
+        const key = f.split(".")[1];
+        if (f === field)
+            parts.push(`"${key}": ${PLACEHOLDER[f]}`);
+        else if (written[f] !== undefined)
+            parts.push(`"${key}": ${JSON.stringify(written[f])}`);
+    }
+    return `"${section}": { ${parts.join(", ")} }`;
+}
+function tableLines(rows) {
+    const values = SETTINGS_FIELDS.map((f) => rows[f].value === undefined ? "not found" : String(rows[f].value));
+    const width = Math.max(17, ...values.map((v) => v.length + 2));
+    const out = [];
+    SETTINGS_FIELDS.forEach((f, i) => {
+        const sentences = rows[f].evidence.split(/(?<=\.) (?=[A-Z])/);
+        out.push(`  ${LABEL[f].padEnd(16)}${values[i].padEnd(width)}${sentences[0]}`);
+        for (const s of sentences.slice(1))
+            out.push(`${" ".repeat(2 + 16 + width)}${s}`);
+    });
+    return out;
+}
+function readingLine(read) {
+    const line = `→ Reading how this app runs: ${read.join(", ")}.`;
+    return line.length + " Nothing was run.".length <= 80
+        ? [`${line} Nothing was run.`]
+        : [line, "  Nothing was run."];
+}
+async function hasLfs(probes) {
+    const r = await probes.readText(".gitattributes");
+    return "text" in r && r.text.includes("filter=lfs");
+}
+function lfsAdvisory() {
+    return [
+        "",
+        "! This repo stores assets in Git LFS. Run `git lfs pull` before a build you mean",
+        "  to publish, or the build will hold pointer files instead of the assets.",
+    ];
+}
+export async function settleSettings(root, binding, flags, io) {
+    const state = { reported: false };
+    const json = await settle(root, binding, flags, io, state);
+    return { json, reported: state.reported };
+}
+async function settle(root, binding, flags, io, state) {
+    const out = {
+        settings: {
+            template: false,
+            written: false,
+            file: SETTINGS_FILE,
+            fields: {},
+            missing: [],
+            differs: [],
+        },
+        advisories: [],
+    };
+    if (await isTemplateProject(root, binding)) {
+        out.settings.template = true;
+        return out;
+    }
+    // Every line here can carry repository text (script bodies, config paths,
+    // file values), so the one sink escapes control characters.
+    const print = io.json
+        ? () => undefined
+        : (line) => io.print(escapeControl(line));
+    const probes = io.probes ?? fsProbes(root);
+    // A folder with no package.json is not an app to detect (an empty folder
+    // linked before `init .`, most often). Writing a file there would make the
+    // template scaffolded into it later refuse its own preview.
+    if (!(await probes.exists("package.json"))) {
+        out.settings.missing = SETTINGS_FIELDS.map((field) => ({
+            field,
+            reason: "there is no package.json",
+        }));
+        return out;
+    }
+    const detected = await detect(probes);
+    // Flags over detection, each through the schema.
+    const rows = {};
+    for (const f of SETTINGS_FIELDS) {
+        const flagValue = flags[FLAG_OF[f]];
+        const found = detected.fields[f];
+        const reason = detected.missing.find((m) => m.field === f)?.reason ?? "not found";
+        if (flagValue !== undefined) {
+            const coerced = coerceField(f, flagValue);
+            rows[f] = coerced.ok
+                ? { value: coerced.value, source: "flag", evidence: `from ${FLAG_NAME[f]}` }
+                : { evidence: `${FLAG_NAME[f]} ${coerced.message}` };
+        }
+        else if (found) {
+            rows[f] = { value: found.value, source: "detected", evidence: found.evidence };
+        }
+        else {
+            rows[f] = { evidence: reason };
+        }
+    }
+    for (const f of SETTINGS_FIELDS) {
+        const r = rows[f];
+        if (r.value !== undefined && (r.source === "detected" || r.source === "flag")) {
+            out.settings.fields[f] = { value: r.value, source: r.source, evidence: r.evidence };
+        }
+    }
+    const lfs = await hasLfs(probes);
+    if (lfs)
+        out.advisories.push("git_lfs");
+    state.reported = true;
+    print("");
+    for (const l of readingLine(detected.read))
+        print(l);
+    // A present file is the creator's decision: never rewritten, only compared.
+    const settingsPath = path.join(root, SETTINGS_FILE);
+    // Bounded and non-blocking: a symlink to /dev/zero or a FIFO is refused
+    // before any read. Anything present but unusable is reported, never rewritten.
+    let existing;
+    try {
+        existing = { text: await readSettingsText(settingsPath) };
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            existing = undefined;
+        else if (err instanceof SettingsError)
+            existing = { error: err };
+        else
+            existing = { error: new SettingsError({ kind: "not_file" }) };
+    }
+    if (existing !== undefined) {
+        print("");
+        try {
+            if ("error" in existing)
+                throw existing.error;
+            const file = parseSettings(existing.text);
+            for (const f of SETTINGS_FIELDS) {
+                const inFile = fieldOf(file, f);
+                const r = rows[f];
+                if (inFile === undefined || r.value === undefined || inFile === r.value)
+                    continue;
+                out.settings.differs.push({
+                    field: f,
+                    file: inFile,
+                    folder: r.value,
+                    evidence: r.evidence,
+                });
+            }
+            if (out.settings.differs.length === 0) {
+                print("  Using vincentt.json. It matches this folder.");
+            }
+            else {
+                const n = out.settings.differs.length;
+                print(`! vincentt.json is already here and was left as it is. ${wordCount(n)} setting${n === 1 ? "" : "s"} differ${n === 1 ? "s" : ""} from`);
+                print("  what this folder looks like:");
+                for (const d of out.settings.differs) {
+                    const folder = String(d.folder);
+                    print("");
+                    print(`    ${d.field}`);
+                    print(`      vincentt.json    ${d.file}`);
+                    print(`      this folder      ${folder.padEnd(Math.max(9, folder.length + 2))}${d.evidence}`);
+                }
+                print("");
+                print("  vincentt.json is what preview and publish use. If it is out of date, edit it.");
+            }
+        }
+        catch (err) {
+            if (!(err instanceof SettingsError))
+                throw err;
+            print(`! vincentt.json is already here but can't be read: ${describeProblem(err.problem)}.`);
+            print("  Preview and publish will stop until it is fixed.");
+        }
+        if (lfs)
+            for (const l of lfsAdvisory())
+                print(l);
+        return out;
+    }
+    print("");
+    for (const l of tableLines(rows))
+        print(l);
+    const matchesDefaults = rows["dev.command"].value === TEMPLATE_DEFAULTS.devCommand &&
+        rows["dev.port"].value === TEMPLATE_DEFAULTS.devPort &&
+        rows["build.output"].value === TEMPLATE_DEFAULTS.buildOutput;
+    if (matchesDefaults) {
+        print("");
+        print("  This app runs like the Vincentt template, so no vincentt.json is needed.");
+        if (lfs)
+            for (const l of lfsAdvisory())
+                print(l);
+        return out;
+    }
+    print("");
+    print("  This app does not run like the Vincentt template, so these go in vincentt.json.");
+    if (io.ask && !io.json) {
+        print("  Press Enter to keep a value, or type a new one.");
+        print("");
+        for (const f of SETTINGS_FIELDS) {
+            const r = rows[f];
+            if (r.source === "flag")
+                continue;
+            const fallback = r.value === undefined ? "" : String(r.value);
+            const prompt = fallback ? `  ${LABEL[f]} (${fallback}): ` : `  ${LABEL[f]}: `;
+            for (let attempt = 0; attempt < 2; attempt++) {
+                const answer = (await io.ask(escapeControl(prompt), fallback)).trim();
+                if (answer === "" || answer === fallback)
+                    break;
+                const coerced = coerceField(f, answer);
+                if (coerced.ok) {
+                    rows[f] = {
+                        value: coerced.value,
+                        source: "typed",
+                        evidence: "typed at the prompt",
+                    };
+                    break;
+                }
+                print(`  ${LABEL[f]} ${coerced.message}.`);
+                if (attempt === 1)
+                    rows[f] = { evidence: `${LABEL[f].toLowerCase()} ${coerced.message}` };
+            }
+        }
+        print("");
+    }
+    const values = {};
+    for (const f of SETTINGS_FIELDS)
+        if (rows[f].value !== undefined)
+            values[f] = rows[f].value;
+    const count = Object.keys(values).length;
+    const write = io.writeFile ??
+        ((abs, text) => fs.writeFile(abs, text, { encoding: "utf8", flag: "wx" }));
+    await write(settingsPath, serializeSettings(values));
+    out.settings.written = true;
+    if (!io.ask || io.json)
+        print("");
+    print(count === SETTINGS_FIELDS.length
+        ? "✓ Wrote vincentt.json"
+        : `✓ Wrote vincentt.json with ${count} of 4 settings.`);
+    print("  Commit it, so every clone of this repo previews and publishes the same way.");
+    for (const f of SETTINGS_FIELDS) {
+        if (values[f] !== undefined)
+            continue;
+        const remedy = VERB_REMEDY[f];
+        const reason = rows[f].evidence;
+        if (!remedy) {
+            out.settings.missing.push({ field: f, reason });
+            continue;
+        }
+        const edit = snippet(f, values);
+        out.settings.missing.push({ field: f, reason, remedy: { edit, flag: remedy.run } });
+        print("");
+        print(`! vincentt.json has no ${f}, so \`vincentt ${remedy.verb}\` will stop until it is set.`);
+        print(`  Add it to vincentt.json:   ${edit}`);
+        print(`  Or pass it for one run:    ${remedy.run}`);
+    }
+    if (lfs)
+        for (const l of lfsAdvisory())
+            print(l);
+    return out;
+}

package/dist/lib/template.d.ts

@@ -0,0 +1,19 @@
+import type { ProjectBinding } from "../shared/config.js";
+export declare const TEMPLATE_MARKER = ".vincentt-template.json";
+export interface PackageJsonShape {
+    scripts?: Record<string, unknown>;
+    dependencies?: Record<string, unknown>;
+    devDependencies?: Record<string, unknown>;
+}
+export interface TemplateIo {
+    readText: (p: string) => Promise<string | undefined>;
+    exists: (p: string) => Promise<boolean>;
+}
+export declare const fsTemplateIo: TemplateIo;
+/** The parsed package.json, or undefined when absent, too large or unparseable. */
+export declare function readPackageJson(root: string, io?: TemplateIo): Promise<PackageJsonShape | undefined>;
+/** `dependencies` or `devDependencies` names the package. */
+export declare function listsDependency(pkg: PackageJsonShape | undefined, name: string): boolean;
+export declare function isTemplateProject(root: string, binding: Pick<ProjectBinding, "template"> | undefined, io?: TemplateIo): Promise<boolean>;
+/** The static no-diagnostics check: does package.json list the harness? */
+export declare function listsHarness(root: string, io?: TemplateIo): Promise<boolean>;

package/dist/lib/template.js

@@ -0,0 +1,73 @@
+// Is this folder a Vincentt template project? A LOCAL classification, like
+// `looksLikeVincenttApp`; the platform holds no notion of template versus
+// outside app.
+//
+// Both legs are required: `package.json` lists `@vincentt-xr/sdk`, AND the
+// committed zone manifest `.vincentt-template.json` sits at the root or the
+// binding records a scaffolded template version. The marker is what recognises a
+// fresh clone (no binding yet); the SDK leg keeps a stray marker from switching
+// detection off for an app that is not the template.
+//
+// Reads only: one existence check and one package.json read. Nothing is run.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+export const TEMPLATE_MARKER = ".vincentt-template.json";
+const PACKAGE_JSON_MAX_BYTES = 256 * 1024;
+export const fsTemplateIo = {
+    readText: async (p) => {
+        try {
+            const stat = await fs.stat(p);
+            if (!stat.isFile() || stat.size > PACKAGE_JSON_MAX_BYTES)
+                return undefined;
+            return await fs.readFile(p, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    },
+    exists: async (p) => {
+        try {
+            await fs.access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+};
+/** The parsed package.json, or undefined when absent, too large or unparseable. */
+export async function readPackageJson(root, io = fsTemplateIo) {
+    const text = await io.readText(path.join(root, "package.json"));
+    if (text === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `dependencies` or `devDependencies` names the package. */
+export function listsDependency(pkg, name) {
+    if (!pkg)
+        return false;
+    const has = (deps) => typeof deps === "object" &&
+        deps !== null &&
+        Object.prototype.hasOwnProperty.call(deps, name);
+    return has(pkg.dependencies) || has(pkg.devDependencies);
+}
+export async function isTemplateProject(root, binding, io = fsTemplateIo) {
+    const pkg = await readPackageJson(root, io);
+    if (!listsDependency(pkg, "@vincentt-xr/sdk"))
+        return false;
+    if (binding?.template?.version)
+        return true;
+    return io.exists(path.join(root, TEMPLATE_MARKER));
+}
+/** The static no-diagnostics check: does package.json list the harness? */
+export async function listsHarness(root, io = fsTemplateIo) {
+    return listsDependency(await readPackageJson(root, io), "@vincentt-xr/harness");
+}

package/dist/lib/terminalText.d.ts

@@ -0,0 +1,3 @@
+export declare const CONTROL_CHARS: RegExp;
+/** Each C0/C1 control character as a visible `\uXXXX`, so nothing is hidden or redrawn. */
+export declare function escapeControl(text: string): string;

package/dist/lib/terminalText.js

@@ -0,0 +1,10 @@
+// Repository-derived text on its way to the creator's terminal. A carriage
+// return or an ANSI sequence in a script body, a config value or a file name
+// could redraw a line the creator is trusting, such as the disclosure of the dev
+// command that is about to run. Every such string passes through here.
+export const CONTROL_CHARS = /[\u0000-\u001f\u007f-\u009f]/;
+const CONTROL_CHARS_G = /[\u0000-\u001f\u007f-\u009f]/g;
+/** Each C0/C1 control character as a visible `\uXXXX`, so nothing is hidden or redrawn. */
+export function escapeControl(text) {
+    return text.replace(CONTROL_CHARS_G, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}

package/dist/lib/version.js

@@ -2,11 +2,11 @@
 // talk to.
 //
 // The second half is the point. A creator can have the right CLI pointed at the
-// wrong API (a leftover VINCENTT_API_URL, a machine config written months ago,
-// or the localhost default on a fresh install), and every failure that follows
-// reads like a server outage rather than a misconfiguration. So this reports the
-// resolved host AND its provenance, using the same decideApiUrl the real verbs
-// use — a version command that re-derived the URL could disagree with them.
+// wrong API (a leftover VINCENTT_API_URL or a machine config written months
+// ago), and every failure that follows reads like a server outage rather than a
+// misconfiguration. So this reports the resolved host AND its provenance, using
+// the same decideApiUrl the real verbs use; a version command that re-derived
+// the URL could disagree with them.
 import { enablementLine, loadEnablement } from "../dx/enablement.js";
 import { decideApiUrl, loadMachineConfig, locateProjectBinding, } from "../shared/config.js";
 /**
@@ -60,12 +60,6 @@ export function renderVersion(r) {
         `  api     ${r.apiUrl}`,
         `          from ${r.apiSource}`,
     ];
-    // A localhost default on a machine that never configured anything is the
-    // single most confusing state to be in: every verb fails with a connection
-    // error that looks like the platform is down.
-    if (r.isDefault && /localhost|127\.0\.0\.1/.test(r.apiUrl)) {
-        out.push("", "  !  Nothing is configured, so this points at a local backend.", "     Set VINCENTT_API_URL, or run `vincentt login` to save one.");
-    }
     if (r.ignoredBindingApiUrl) {
         out.push("", `  !  This folder's binding names a different API (${r.ignoredBindingApiUrl})`, "     and was ignored. Re-run with --allow-custom-api to use it.");
     }

package/dist/lib/whoami.js

@@ -6,21 +6,28 @@
 // holds if the command actually answers, so its correctness is load-bearing for
 // f2's hardest copy rather than cosmetic.
 import { resolveActiveOrg } from "./org.js";
+import { authExpiredLines, isAuthRefused } from "../shared/authError.js";
+import { EXIT } from "./exitCodes.js";
 export async function whoamiCommand(deps) {
     const cfg = await deps.config();
     if (!cfg) {
         deps.print("Not signed in. Run `vincentt login`.");
-        return 1;
+        return EXIT.NOT_AUTHENTICATED;
     }
     let me;
     try {
         me = await deps.getMe(cfg);
     }
     catch (err) {
+        if (isAuthRefused(err)) {
+            for (const l of authExpiredLines())
+                deps.print(l);
+            return EXIT.NOT_AUTHENTICATED;
+        }
         // Reserved for a GENUINE transport failure. The two lines a creator can act on
         // are named, because "unverified" alone tells someone who does not know who
         // they are that we do not either.
-        deps.print(`!  Could not reach ${cfg.apiUrl} — your token is present but unverified.`);
+        deps.print(`!  Could not reach ${cfg.apiUrl}. Your token is present but unverified.`);
         deps.print("   Check your connection, or `vincentt login` if you believe it expired.");
         void err;
         return 1;
@@ -32,7 +39,7 @@ export async function whoamiCommand(deps) {
     // from a bug on exactly the path where the creator is already confused.
     deps.print(org
         ? `  Active workspace:  ${org.name} (${org.slug})`
-        : "  Active workspace:  none — pass --org <slug>");
+        : "  Active workspace:  none (pass --org <slug>)");
     deps.print(`  API:         ${cfg.apiUrl}`);
     return 0;
 }

package/dist/library/assetsCommand.js

@@ -229,7 +229,7 @@ async function runDownload(deps, records, opts) {
             deps.err("");
             deps.err(`✗ Couldn't download ${a.id}.`);
             deps.err("");
-            deps.err("  The URLs above are correct and still work — reference them directly");
+            deps.err("  The URLs above are correct and still work; reference them directly");
             deps.err("  instead, or try --download again in a moment.");
             deps.err("");
             if (written.length > 0) {

package/dist/library/client.js

@@ -13,7 +13,11 @@
 // (D-add-prints-urls degraded the no-invented-URLs rule from prevention to
 // detection, and this is the one arm that stayed prevention).
 import { clientHeaders } from "../shared/clientHeader.js";
+import { authFailureMessage } from "../shared/authError.js";
+import { apiFetch, withDeadline } from "../shared/http.js";
 import { parseBatchResponse, parseFetchResponse, parseSearchResponse, } from "./wire.js";
+// An asset file can be tens of megabytes, so its download gets longer than an api call.
+const downloadFetch = withDeadline((input, init) => globalThis.fetch(input, init), 5 * 60_000);
 /** The API said no, with a code we can act on. */
 export class LibraryError extends Error {
     status;
@@ -65,7 +69,7 @@ export function httpLibraryClient(cfg) {
     const auth = { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
     const call = async (pathname, init) => {
         try {
-            return await fetch(`${base}${pathname}`, {
+            return await apiFetch(`${base}${pathname}`, {
                 ...init,
                 headers: { ...(init?.headers ?? {}), ...auth },
             });
@@ -75,7 +79,8 @@ export function httpLibraryClient(cfg) {
         }
     };
     const fail = async (res, what) => {
-        throw new LibraryError(`${what} failed (${res.status})`, res.status, await errorCode(res));
+        // A 401 keeps its status: assetsCommand maps it to the sign-in screen and exit 4.
+        throw new LibraryError(authFailureMessage(`${what} failed`, res.status, ""), res.status, await errorCode(res));
     };
     return {
         async search(params) {
@@ -124,7 +129,7 @@ export function httpLibraryClient(cfg) {
             }
             let res;
             try {
-                res = await fetch(url);
+                res = await downloadFetch(url);
             }
             catch (err) {
                 throw new LibraryUnreachableError(err);

package/dist/library/render.js

@@ -16,7 +16,9 @@ export function contractLine(a) {
 }
 /** `pumpkin · prop · 1:1 · 1024x1024 · alpha` — `add`'s confirmation line (byte facts). */
 export function byteFactsLine(a) {
-    const dims = a.width !== undefined && a.height !== undefined ? `${a.width}x${a.height}` : undefined;
+    const dims = a.width !== undefined && a.height !== undefined
+        ? `${a.width}x${a.height}`
+        : undefined;
     const parts = [
         a.subject,
         a.kind,
@@ -74,9 +76,9 @@ export function searchRecordLines(a) {
     const description = a.description;
     if (subject !== undefined && description !== undefined) {
         // The description is lowercased at the join only when it starts a sentence
-        // after the em-less "subject — " lead, matching the approved transcript.
+        // after the "subject: " lead, matching the approved transcript.
         const d = description.charAt(0).toLowerCase() + description.slice(1);
-        out.push(...wrap(`${subject} — ${d}`, 72, "    "));
+        out.push(...wrap(`${subject}: ${d}`, 72, "    "));
     }
     else if (subject !== undefined) {
         out.push(`    ${subject}`);
@@ -225,7 +227,7 @@ export function showLines(a) {
         // that a project already references it, and the useful instruction is to do
         // nothing.
         out.push("! This asset is no longer in search results. The URL below keeps working");
-        out.push("  forever — if you are already using it, nothing needs to change.");
+        out.push("  forever. If you are already using it, nothing needs to change.");
         out.push("");
     }
     if (a.subject !== undefined)
@@ -272,7 +274,7 @@ export function unreachableLines(kind, retry) {
             "✗ You're not signed in.",
             "",
             "  The library is a platform call, so it needs an account. Your project is",
-            "  unaffected — build, preview and publish don't use the library.",
+            "  unaffected: build, preview and publish don't use the library.",
             "",
             "  Sign in:  vincentt login",
             "",
@@ -296,7 +298,7 @@ export function unreachableLines(kind, retry) {
         "",
         "✗ Can't reach the asset library.",
         "",
-        "  Your project is unaffected — build, preview and publish don't use the",
+        "  Your project is unaffected: build, preview and publish don't use the",
         "  library. Any library URL you already have keeps working.",
         "",
         `  Try again in a moment:  ${retry}`,

package/dist/login/authBackend.js

@@ -8,6 +8,7 @@
 //   GET  /me            Bearer <PAT>                    → identity + orgs (confirm)
 import { authFailureMessage } from "../shared/authError.js";
 import { clientHeaders } from "../shared/clientHeader.js";
+import { apiFetch } from "../shared/http.js";
 class AuthError extends Error {
     status;
     constructor(message, status) {
@@ -29,7 +30,7 @@ export function httpAuthBackend(apiBase) {
     const base = apiBase.replace(/\/$/, "");
     return {
         async exchange(code, codeVerifier) {
-            const res = await fetch(`${base}/access-tokens/exchange`, {
+            const res = await apiFetch(`${base}/access-tokens/exchange`, {
                 method: "POST",
                 headers: { ...clientHeaders(), "content-type": "application/json" },
                 body: JSON.stringify({ code, code_verifier: codeVerifier }),
@@ -43,7 +44,7 @@ export function httpAuthBackend(apiBase) {
             return body.token;
         },
         async me(pat) {
-            const res = await fetch(`${base}/me`, {
+            const res = await apiFetch(`${base}/me`, {
                 headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
             });
             if (!res.ok) {

package/dist/login/ensure.d.ts

@@ -5,6 +5,12 @@ export interface EnsureLoginDeps {
     runLogin: () => Promise<void>;
     /** Surface a line to the user (stderr, so it never pollutes machine-readable stdout). */
     notify: (message: string) => void;
+    /** Whether a person is at a terminal who can approve a browser sign-in. */
+    interactive: boolean;
 }
-/** No-op when a token is already present; otherwise log-and-login before returning. */
-export declare function ensureLoggedIn(deps: EnsureLoginDeps): Promise<void>;
+/**
+ * True when a token is present, or a login at the terminal produced one. False
+ * after printing the not-signed-in lines: the caller exits EXIT.NOT_AUTHENTICATED.
+ * A login that throws (cancelled, timed out) propagates.
+ */
+export declare function ensureLoggedIn(deps: EnsureLoginDeps): Promise<boolean>;