@vincentt-xr/cli 0.15.2 → 0.17.0

package/dist/cli/args.js

@@ -41,6 +41,7 @@ export const BOOLEAN_FLAGS = new Set([
     "--allow-custom-api",
     "--yes",
     "--download",
+    "--no-context",
     "--help",
     "-h",
 ]);

package/dist/cli/index.js

@@ -38,7 +38,8 @@ import { httpRelayClient } from "../lib/diagnostics.js";
 import { readLivePreview, relayInfoDir } from "../lib/relayInfo.js";
 import { attachedToRunning, mintRateLimited, notSignedIn, previewConflict, startBlock, } from "../preview/copy.js";
 import { renderTerminalQr, shouldRenderQr } from "../preview/qr.js";
-import { PreviewConflictError, PreviewRateLimitedError } from "../preview/api.js";
+import { PreviewConflictError, PreviewLimitError, PreviewRateLimitedError, } from "../preview/api.js";
+import { previewLimitRefused, resolveCountLimit, } from "../shared/countLimit.js";
 import { fetchNext, readCursor, writeCursor } from "../lib/feedback.js";
 import * as feedbackCopy from "../lib/feedbackCopy.js";
 import { record as recordInvocation } from "../dx/journal.js";
@@ -51,6 +52,10 @@ import { nudgeFor } from "../dx/nudge.js";
 import { FETCH_TIMEOUT_MS, isFresh, updateNotice } from "../dx/updateCheck.js";
 import { fetchLatest, loadCache, saveCache } from "../dx/updateCheckIo.js";
 import { verbOf } from "../dx/skeleton.js";
+import { outdatedCommand } from "../platform/command.js";
+import { behindFooterLines, needsRefresh, refreshReleaseCache } from "../platform/footer.js";
+import { loadReleaseCache } from "../platform/releaseCache.js";
+import { resolveBuiltWith } from "../platform/resolve.js";
 import { createDirCollision, createSourceFlagRefusal, fromFlagConflict, isHelpInvocation, isVersionInvocation, positionalArgs, refusedFlag, } from "./args.js";
 import { parseSourceRef } from "../lib/sourceRef.js";
 import { printCreateSourceFlagRefusal, printFlagConflict, printSourceRefFailure, } from "../lib/sourceRefCopy.js";
@@ -401,6 +406,29 @@ async function projects() {
         store: fileLocationStore,
     }, { json: has("--json") });
 }
+/**
+ * `vincentt outdated` — what this project is behind on.
+ *
+ * NEEDS NO ACCOUNT and never prompts for one: the endpoint it reads is public,
+ * and a creator with no login is exactly the population this verb exists to
+ * serve. It is a listing verb, so it reports and never asks, and its output is
+ * routinely piped.
+ */
+async function outdated() {
+    const cwd = projectDir();
+    process.exitCode = await outdatedCommand({
+        print: (l) => console.log(l),
+        cwd,
+        now: () => Date.now(),
+        apiUrl: async () => process.env.VINCENTT_API_URL ?? (await loadMachineConfig()).apiUrl ?? DEFAULT_API_URL,
+        inProject: async () => (await locateProjectBinding(cwd)) !== undefined,
+        projectLine: async () => {
+            const name = await projectDisplayName(cwd);
+            const org = await activeOrgName();
+            return org ? `${name} · ${org}` : name;
+        },
+    });
+}
 /**
  * `vincentt publish` — Flows L22-L31.
  *
@@ -557,7 +585,11 @@ async function preview() {
         }
     }
     catch (err) {
-        for (const l of previewFailureLines(err))
+        // The local org is the FALLBACK only. A count refusal names the org that
+        // owns this project, and the wire's name wins over this one wherever both
+        // exist — see resolveCountLimit.
+        const localOrg = await localOrgIdentity();
+        for (const l of previewFailureLines(err, localOrg))
             console.log(l);
         process.exitCode = 1;
         return;
@@ -679,6 +711,18 @@ async function activeOrgName() {
         (await loadMachineConfig()).activeOrg ??
         "");
 }
+/**
+ * The org this machine is pointed at, for a refusal whose body named none.
+ *
+ * `activeOrg` is a SLUG, so it fills the slug slot and not the name slot. The
+ * display name is the API's to give; inventing one from the slug would put a
+ * fabricated workspace name on a refusal.
+ */
+async function localOrgIdentity() {
+    const slug = await activeOrgName();
+    const { consoleUrl } = await resolveAuthUrls();
+    return { slug: slug || undefined, consoleUrl };
+}
 /** The binding's name is a HINT for display only; the API is the authority. */
 async function projectDisplayName(cwd) {
     const located = await locateProjectBinding(cwd);
@@ -717,9 +761,15 @@ async function projectConsoleUrl(cwd, sessionId) {
  * creator never has to read a second, and none of them names the edge, the API
  * or an outage — a creator cannot act on that.
  */
-function previewFailureLines(err) {
+function previewFailureLines(err, local) {
     if (err instanceof PreviewRateLimitedError)
         return mintRateLimited(err.retryAfterSec);
+    // The ceiling is the second 409 on the mint route, and it is a DIFFERENT
+    // creator situation from the conflict below: nothing is running, nothing was
+    // taken down, and the organization is full.
+    if (err instanceof PreviewLimitError) {
+        return previewLimitRefused(resolveCountLimit(err.detail, local));
+    }
     if (err instanceof PreviewConflictError)
         return previewConflict();
     if (err instanceof ProjectUnreachableError) {
@@ -1032,6 +1082,9 @@ async function dx() {
         // first two have not already allowed the send, and allowed to throw — a /me that
         // is unreachable falls back to the other two arms rather than blocking.
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+        // `--dir`-or-cwd, the same resolution every other verb uses, so `--dir`
+        // works on a send as it does everywhere else.
+        cwd: projectDir(),
     }, options);
 }
 // ---- report -----------------------------------------------------------------
@@ -1070,6 +1123,9 @@ async function report() {
         interactive,
         enablement: () => enablement,
         accountConsent: (auth) => httpConsentBackend().read(auth.apiUrl, auth.pat, now),
+        // `--dir`-or-cwd, the same resolution every other verb uses, so `--dir`
+        // works on a report as it does everywhere else.
+        cwd: projectDir(),
     }, parseReportOptions(argv.slice(1)));
 }
 // ---- assets (f5) ------------------------------------------------------------
@@ -1153,6 +1209,77 @@ async function assets() {
         dir: flag("--dir"),
     });
 }
+// ---- custom domains (f16) ---------------------------------------------------
+/**
+ * `vincentt domain <attach|list|verify|detach>` — Flows C1-C7.
+ *
+ * The aliases `add` and `remove` resolve inside `resolveSub` and NOTHING IS
+ * PRINTED ABOUT THEM: no "did you mean", no deprecation, no echo of the canonical
+ * name. `resolveSub` returns only the canonical verb, so this function cannot
+ * tell an alias was used — which is the structural form of the rule.
+ *
+ * `renew` gets a FACT rather than a redirect, because the honest answer is that
+ * the act does not exist: certificates renew on their own.
+ */
+async function domain() {
+    const { domainCommand, resolveSub, } = await import("../domain/command.js");
+    const domainCopy = await import("../domain/copy.js");
+    const api = await import("../domain/api.js");
+    const sub = positional(1);
+    if (sub === undefined) {
+        console.error("Usage: vincentt domain <attach|list|verify|detach> [domain]");
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === "renew") {
+        for (const l of domainCopy.noRenewVerb())
+            console.log(l);
+        process.exitCode = 1;
+        return;
+    }
+    const resolved = resolveSub(sub);
+    if (resolved === undefined) {
+        for (const l of domainCopy.unknownDomainSub(sub))
+            console.log(l);
+        process.exitCode = 1;
+        return;
+    }
+    const cwd = projectDir();
+    const machine = await loadMachineConfig();
+    const config = async () => {
+        const apiUrl = process.env.VINCENTT_API_URL ?? machine.apiUrl ?? DEFAULT_API_URL;
+        const pat = process.env.VINCENTT_PAT ?? machine.pat;
+        return pat ? { apiUrl: apiUrl.replace(/\/$/, ""), pat } : undefined;
+    };
+    process.exitCode = await domainCommand({
+        print: (l) => console.log(l),
+        config,
+        binding: async () => {
+            const located = await locateProjectBinding(cwd);
+            return located
+                ? { projectId: located.binding.projectId, slug: located.binding.slug }
+                : undefined;
+        },
+        org: async () => {
+            const cfg = await config();
+            if (!cfg)
+                return { ok: false, message: "Not signed in. Run `vincentt login`." };
+            return resolveOrgForCommand(cfg, { flag: flag("--org") });
+        },
+        attach: api.attachDomain,
+        verify: api.verifyDomain,
+        listOrg: api.listOrgDomains,
+        detach: api.detachDomain,
+        confirm: stdinConfirm(),
+        isTTY: Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY),
+    }, resolved, {
+        // The hostname is the bare argument after the subcommand. `list` takes
+        // none and ignores it rather than erroring: a listing verb reports.
+        hostname: positional(2),
+        json: has("--json"),
+        yes: has("--yes"),
+    });
+}
 // ---- servers ----------------------------------------------------------------
 async function relay() {
     const { startRelay } = await import("../relay/server.js");
@@ -1189,6 +1316,19 @@ async function main() {
         // to answer a question it knows the answer to.
         if (cmd !== undefined && isConsoleOnlyVerb(cmd))
             return consoleOnly(cmd);
+        // f16: `domains`, `dns`, `custom-domain` are the plausible spellings of the
+        // real verb. An agent that gets "unknown command" retries or guesses a
+        // neighbour; naming the command terminates.
+        if (cmd !== undefined) {
+            const { isDomainRoutedVerb } = await import("../domain/routedVerbs.js");
+            if (isDomainRoutedVerb(cmd)) {
+                const { domainVerbRedirect } = await import("../domain/copy.js");
+                for (const l of domainVerbRedirect(cmd))
+                    console.log(l);
+                process.exitCode = 1;
+                return;
+            }
+        }
         console.error(`Unknown command: ${cmd}\n`);
         usage();
         process.exitCode = 1;
@@ -1233,6 +1373,10 @@ async function main() {
             return dx();
         case "report":
             return report();
+        case "outdated":
+            return outdated();
+        case "domain":
+            return domain();
     }
 }
 // Every invocation is journaled here, at the one site that sees all of them —
@@ -1283,6 +1427,57 @@ function journal(exitCode, error) {
     catch {
         // Same rule as the nudge: never break a run over a footnote.
     }
+    // The behind-notice, on the same terms as the two footnotes above: stderr,
+    // after the run it is a footnote to, from the PREVIOUS run's cache, and never
+    // awaited. It rides only on commands a creator initiated — there is no timer
+    // and no background poll anywhere in this feature.
+    //
+    // `preview` is the carrier that matters: it is the command a creator runs many
+    // times a day for the life of a project, which closes the gap where someone
+    // iterates for weeks without publishing and hears nothing.
+    //
+    // NEVER ON `outdated` ITSELF, for the reason the nudge is never printed on
+    // `dx`: appending an unbidden summary of what the creator just asked for and
+    // read in full is noise, and worse than noise here — it would BURN the
+    // once-per-release announcement on a run where the creator was already told
+    // everything, so the next `preview` would stay silent about a release they
+    // saw only because they went looking.
+    if (verbOf(argv) !== "outdated")
+        void announceBehind();
+}
+/**
+ * Print the behind-notice and schedule the refresh.
+ *
+ * Its own function because it needs an await (the version resolve reads a few
+ * small files) while `journal` is synchronous, and because every fault here must
+ * be swallowed: the worst outcome of this whole surface going dark is that
+ * nobody is told they are behind, which is exactly where they were before it
+ * existed. `preview` must not acquire a new way to look broken.
+ */
+async function announceBehind() {
+    try {
+        const cwd = projectDir();
+        const builtWith = await resolveBuiltWith(cwd);
+        if (builtWith !== undefined) {
+            for (const l of behindFooterLines({
+                installed: { packages: builtWith.packages, template: builtWith.template },
+                now: () => Date.now(),
+            })) {
+                console.error(l);
+            }
+        }
+        if (needsRefresh(loadReleaseCache(), Date.now())) {
+            refreshReleaseCache({
+                apiUrl: process.env.VINCENTT_API_URL ??
+                    (await loadMachineConfig()).apiUrl ??
+                    DEFAULT_API_URL,
+                now: () => Date.now(),
+            });
+        }
+    }
+    catch {
+        // A footnote that can break a publish is not worth having.
+    }
 }
 /**
  * Refresh the cached `latest` without holding the process open.

package/dist/cli/usage-text.js

@@ -41,6 +41,28 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `  preview            Serve the app at an https link a phone can open\n` +
     `                       [--port <n>] [--tester <id>] [--no-qr] [--stop]\n` +
     `                       Re-running prints the live link; --restart mints a new one.\n\n` +
+    // f16. HELP TEACHES THE CANONICAL VERBS ONLY: `add` and `remove` are accepted
+    // as silent aliases and are deliberately ABSENT here, because help, docs and
+    // every error string are where the vocabulary is actually taught. Listing the
+    // aliases would teach two words for one act, which is the thing D-45 refuses.
+    //
+    // "Detaching stops it serving; the name stays yours" is the load-bearing
+    // clause: a detached custom domain is NOT burned, and a reader who assumed
+    // f4's permanence rule applied would never try the verb.
+    `Custom domains (a paid-plan capability)\n` +
+    `  domain attach <domain>   Claim a domain for this folder's project and print\n` +
+    `                             the three DNS records to create. Prints each name\n` +
+    `                             in both the short and the full form, because\n` +
+    `                             registrars disagree about which they want.\n` +
+    `  domain list              This workspace's domains and the count its plan\n` +
+    `                             carries  [--org <s>] [--json]\n` +
+    `  domain verify <domain>   Check the DNS now and report what was OBSERVED\n` +
+    `                             beside what was expected  [--json]\n` +
+    `                             Exit 0 serving (findings that block nothing may\n` +
+    `                             still be reported); exit 1 not serving yet\n` +
+    `  domain detach <domain>   Stop serving the domain. Asks first; [--yes] to\n` +
+    `                             skip the question. The name stays yours and the\n` +
+    `                             project's vincentt.app address is unaffected.\n\n` +
     `Diagnostics (need a running preview)\n` +
     `  logs [--errors]    Console logs from the device    [--json] [--tester <id>]\n` +
     `  network            fetch/XHR requests              [--json] [--tester <id>]\n` +
@@ -92,6 +114,11 @@ export const USAGE_TEXT = `Vincentt CLI — local-first AR dev loop\n\n` +
     `  relay              Run the diagnostics/annotation relay\n\n` +
     `Meta\n` +
     `  version            CLI version, and the API this machine resolves to\n` +
+    `  outdated           What this project is behind on, and what Vincentt currently\n` +
+    `                       publishes. Reads a public endpoint; no account needed.\n` +
+    `                       Prints the installed and current version of each Vincentt\n` +
+    `                       package, the string to place in package.json, and any\n` +
+    `                       migration note the platform published. Writes nothing.\n` +
     `  dx                 Where this dev loop fought you  [--days <n>] [--json]\n` +
     `                       Reads a local journal of your own runs. Local by default.\n` +
     `                       --send reports the findings to the Vincentt team; it\n` +

package/dist/cli/verb-surface.d.ts

@@ -1,4 +1,4 @@
-export declare const PINNED_VERBS: readonly ["version", "login", "logout", "whoami", "init", "create", "link", "unlink", "publish", "preview", "logs", "network", "trace", "feedback", "relay", "assets", "dx", "projects", "report"];
+export declare const PINNED_VERBS: readonly ["version", "login", "logout", "whoami", "init", "create", "link", "unlink", "publish", "preview", "logs", "network", "trace", "feedback", "relay", "assets", "dx", "projects", "report", "outdated", "domain"];
 export type PinnedVerb = (typeof PINNED_VERBS)[number];
 export declare const VERB_HANDLERS: {
     readonly version: true;
@@ -20,6 +20,8 @@ export declare const VERB_HANDLERS: {
     readonly dx: true;
     readonly projects: true;
     readonly report: true;
+    readonly outdated: true;
+    readonly domain: true;
 };
 export type DispatchVerb = keyof typeof VERB_HANDLERS;
 export declare function resolveVerb(cmd: string | undefined): DispatchVerb | undefined;

package/dist/cli/verb-surface.js

@@ -16,6 +16,16 @@ export const PINNED_VERBS = [
     // and refuses when it finds none; this carries what a creator TYPED, which is
     // the half a journal keyed on exit codes cannot see. Also an addition.
     "report",
+    // Appended: what this project is behind on, and what the platform currently
+    // publishes. Named for the QUESTION and never for the act — `update` and
+    // `upgrade` would imply the CLI performs the upgrade, which it does not, and
+    // an agent reading `vincentt update` in any text will run it.
+    "outdated",
+    // Appended (f16): custom domains. SINGULAR, because every subcommand acts on
+    // one domain (`domain attach ar.acme.com`) and the plural would read as a
+    // collection verb. `domains` is routed to an answer, not accepted as a verb —
+    // see domainVerbRedirect. An addition, so B-F3-8 permits it.
+    "domain",
 ];
 // The dispatch's verb set, as data. `main()` switches over this, so the two can
 // never disagree: a verb added to the CLI is a key added here, and QA-AHG-01
@@ -40,6 +50,8 @@ export const VERB_HANDLERS = {
     dx: true,
     projects: true,
     report: true,
+    outdated: true,
+    domain: true,
 };
 // Answers "is this a verb this CLI accepts" without running it. The
 // console-redirect strings are NOT accepted here: they reach their explanation

package/dist/domain/api.d.ts

@@ -0,0 +1,51 @@
+import type { ResolvedConfig } from "../shared/config.js";
+import { type DomainListView, type DomainView } from "./wire.js";
+export interface DomainApiErrorDetail {
+    /** The plan's ceiling, on a ceiling refusal. */
+    limit?: number;
+    /** The plan in force, when the API names one. */
+    planName?: string;
+    planTier?: string;
+}
+export declare class DomainApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly detail: DomainApiErrorDetail;
+    readonly retryAfterSec?: number | undefined;
+    constructor(status: number, code: string, message: string, detail?: DomainApiErrorDetail, retryAfterSec?: number | undefined);
+}
+/**
+ * The record's role, when the API names one, parallel to `records`.
+ *
+ * The CLI does NOT decide which record is the certificate-validation one: the
+ * caption whose absence is expensive (D-44) must not depend on a client-side
+ * heuristic over a CA hostname. When the API sends no roles the array is empty
+ * and the caption is simply absent — visibly missing rather than wrongly placed.
+ */
+export interface AttachResult {
+    domain: DomainView;
+    roles: (string | undefined)[];
+    droppedFindings: number;
+}
+/** POST /projects/{id}/domains — returns the records to publish. Rate-limited. */
+export declare function attachDomain(cfg: ResolvedConfig, projectId: string, domain: string, fetchImpl?: typeof fetch): Promise<AttachResult>;
+/**
+ * POST /projects/{id}/domains/{domain}/verify — the on-demand re-check.
+ *
+ * Rate-limited per `(org, domain)`, so a 429 here is expected traffic rather than
+ * a defect, and its copy names no limit family.
+ */
+export declare function verifyDomain(cfg: ResolvedConfig, projectId: string, domain: string, fetchImpl?: typeof fetch): Promise<AttachResult>;
+/** GET /projects/{id}/domains — this project's domains with state + findings. */
+export declare function listProjectDomains(cfg: ResolvedConfig, projectId: string, fetchImpl?: typeof fetch): Promise<DomainListView>;
+/**
+ * GET /orgs/{id}/domains — the workspace's whole fleet and the count against the
+ * limit.
+ *
+ * This is what `vincentt domain list` reads, and it is why the anti-oracle
+ * collision copy is safe: a creator who genuinely holds a contested name finds it
+ * here, and this route only ever returns their own.
+ */
+export declare function listOrgDomains(cfg: ResolvedConfig, orgSlug: string, fetchImpl?: typeof fetch): Promise<DomainListView>;
+/** DELETE /projects/{id}/domains/{domain} — detach. The row is never deleted server-side. */
+export declare function detachDomain(cfg: ResolvedConfig, projectId: string, domain: string, fetchImpl?: typeof fetch): Promise<void>;

package/dist/domain/api.js

@@ -0,0 +1,145 @@
+// The f16 domain calls against the Go API, built against implementation.md
+// § API surface.
+//
+// THE ROUTES ARE HOSTNAME-KEYED and normalized in the path. A hostname path
+// segment CONTAINS DOTS, which some routers treat as a file extension — the API
+// side pins a four-label round trip for exactly that reason. Every hostname is
+// `encodeURIComponent`d here, which is what keeps a name with an unexpected
+// character from changing the shape of the path.
+//
+// The project is resolved and authorized FIRST, by the same class check every
+// other project route uses, so a caller who does not hold the project gets the
+// ordinary indistinguishable 404 before the hostname is read at all. The CLI
+// therefore cannot distinguish "no such project" from "not your project" — and
+// must not try.
+import { clientHeaders } from "../shared/clientHeader.js";
+import { parseDomain, parseDomainList, } from "./wire.js";
+export class DomainApiError extends Error {
+    status;
+    code;
+    detail;
+    retryAfterSec;
+    constructor(status, code, message, detail = {}, retryAfterSec) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.detail = detail;
+        this.retryAfterSec = retryAfterSec;
+        this.name = "DomainApiError";
+    }
+}
+async function readError(res) {
+    let body = {};
+    try {
+        body = (await res.json());
+    }
+    catch {
+        // A non-JSON error body is still an error; the status carries the meaning.
+    }
+    const retryAfter = res.headers.get("retry-after");
+    return new DomainApiError(res.status, body.code ?? `http_${res.status}`, body.message ?? `request failed (${res.status})`, body.detail ?? {}, retryAfter ? Number(retryAfter) : undefined);
+}
+function authHeaders(cfg) {
+    return { ...clientHeaders(), authorization: `Bearer ${cfg.pat}` };
+}
+function rolesOf(raw) {
+    const o = typeof raw === "object" && raw !== null ? raw : {};
+    const rows = Array.isArray(o.records) ? o.records : [];
+    return rows.map((r) => {
+        const rec = typeof r === "object" && r !== null ? r : {};
+        return typeof rec.role === "string" ? rec.role : undefined;
+    });
+}
+/** POST /projects/{id}/domains — returns the records to publish. Rate-limited. */
+export async function attachDomain(cfg, projectId, domain, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, {
+        method: "POST",
+        headers: { ...authHeaders(cfg), "content-type": "application/json" },
+        body: JSON.stringify({ domain }),
+    });
+    if (!res.ok)
+        throw await readError(res);
+    const raw = await res.json();
+    const parsed = parseDomain(unwrap(raw));
+    if (!parsed) {
+        throw new DomainApiError(res.status, "malformed_response", "attach: response carried no domain");
+    }
+    return {
+        domain: parsed.domain,
+        roles: rolesOf(unwrap(raw)),
+        droppedFindings: parsed.droppedFindings,
+    };
+}
+/**
+ * POST /projects/{id}/domains/{domain}/verify — the on-demand re-check.
+ *
+ * Rate-limited per `(org, domain)`, so a 429 here is expected traffic rather than
+ * a defect, and its copy names no limit family.
+ */
+export async function verifyDomain(cfg, projectId, domain, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}/verify`, { method: "POST", headers: authHeaders(cfg) });
+    if (!res.ok)
+        throw await readError(res);
+    const raw = await res.json();
+    const parsed = parseDomain(unwrap(raw));
+    if (!parsed) {
+        throw new DomainApiError(res.status, "malformed_response", "verify: response carried no domain");
+    }
+    return {
+        domain: parsed.domain,
+        roles: rolesOf(unwrap(raw)),
+        droppedFindings: parsed.droppedFindings,
+    };
+}
+/** GET /projects/{id}/domains — this project's domains with state + findings. */
+export async function listProjectDomains(cfg, projectId, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains`, { headers: authHeaders(cfg) });
+    if (!res.ok)
+        throw await readError(res);
+    return parseDomainList(await res.json());
+}
+/**
+ * GET /orgs/{id}/domains — the workspace's whole fleet and the count against the
+ * limit.
+ *
+ * This is what `vincentt domain list` reads, and it is why the anti-oracle
+ * collision copy is safe: a creator who genuinely holds a contested name finds it
+ * here, and this route only ever returns their own.
+ */
+export async function listOrgDomains(cfg, orgSlug, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/orgs/${encodeURIComponent(orgSlug)}/domains`, { headers: authHeaders(cfg) });
+    if (!res.ok)
+        throw await readError(res);
+    return parseDomainList(await res.json());
+}
+/** DELETE /projects/{id}/domains/{domain} — detach. The row is never deleted server-side. */
+export async function detachDomain(cfg, projectId, domain, fetchImpl = fetch) {
+    const res = await fetchImpl(`${cfg.apiUrl}/projects/${encodeURIComponent(projectId)}/domains/${encodeURIComponent(domain)}`, { method: "DELETE", headers: authHeaders(cfg) });
+    // 404 is a SILENT RESOLVE on detach: the creator asked for a state the world is
+    // already in. It is not distinguishable from "not your project", and it does
+    // not need to be — either way this project is not serving that name.
+    if (res.status === 404)
+        return;
+    if (!res.ok)
+        throw await readError(res);
+}
+/**
+ * Unwrap a `{domain: {...}}` envelope if the API sends one, else treat the body as
+ * the row.
+ *
+ * Tolerating both is NOT the legacy-tolerance anti-pattern `backend.ts` removed:
+ * that one accepted two spellings of a FIELD (`_id` vs `id`), where silently
+ * accepting the old shape hides a contract break. This tolerates an ENVELOPE,
+ * where both readings name the same field set and the ambiguity is resolved by
+ * looking for `domain` as a string — the row's own required field.
+ */
+function unwrap(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return raw;
+    const o = raw;
+    if (typeof o.domain === "string")
+        return o;
+    if (typeof o.domain === "object" && o.domain !== null)
+        return o.domain;
+    return o;
+}

package/dist/domain/command.d.ts

@@ -0,0 +1,75 @@
+import type { ResolvedConfig } from "../shared/config.js";
+import { type DomainListView, type DomainView } from "./wire.js";
+import type { AttachResult } from "./api.js";
+/** The canonical subcommands. */
+export declare const DOMAIN_SUBCOMMANDS: readonly ["attach", "list", "verify", "detach"];
+export type DomainSub = (typeof DOMAIN_SUBCOMMANDS)[number];
+/**
+ * The silent aliases. `add`→`attach`, `remove`→`detach`.
+ *
+ * A map, not a chain of `if`s, so the pair is data a test can enumerate and the
+ * set cannot drift from what `resolveSub` accepts.
+ */
+export declare const DOMAIN_ALIASES: Readonly<Record<string, DomainSub>>;
+/**
+ * Resolve a typed subcommand to its canonical verb, or undefined.
+ *
+ * RETURNS ONLY THE CANONICAL VERB. It deliberately does not report whether an
+ * alias was used: a caller that cannot tell cannot print a correction, which is
+ * the structural form of "the aliases are silent". Making the alias invisible at
+ * the type level is stronger than remembering not to print it.
+ */
+export declare function resolveSub(typed: string | undefined): DomainSub | undefined;
+export interface DomainDeps {
+    print: (line: string) => void;
+    config: () => Promise<ResolvedConfig | undefined>;
+    /** The linked project for this folder, or undefined when nothing is linked. */
+    binding: () => Promise<{
+        projectId: string;
+        slug: string;
+    } | undefined>;
+    /** The workspace to list. Resolved by the caller's own precedence chain. */
+    org: () => Promise<{
+        ok: true;
+        org: {
+            slug: string;
+            name: string;
+        };
+    } | {
+        ok: false;
+        message: string;
+    }>;
+    attach: (cfg: ResolvedConfig, projectId: string, domain: string) => Promise<AttachResult>;
+    verify: (cfg: ResolvedConfig, projectId: string, domain: string) => Promise<AttachResult>;
+    listOrg: (cfg: ResolvedConfig, orgSlug: string) => Promise<DomainListView>;
+    detach: (cfg: ResolvedConfig, projectId: string, domain: string) => Promise<void>;
+    confirm: (prompt: string, defaultYes: boolean) => Promise<boolean>;
+    isTTY: boolean;
+}
+export interface DomainOptions {
+    /** The hostname argument, as typed. */
+    hostname?: string;
+    json?: boolean;
+    /** `--yes` — the explicit non-interactive consent for detach. */
+    yes?: boolean;
+}
+/**
+ * The dispatch. Returns the process exit code.
+ *
+ * Every arm returns explicitly rather than falling through to a shared tail: an
+ * exit code assembled at the end of a long function is an exit code a later
+ * branch changes by accident, and the exit code is the thing an agent branches
+ * on.
+ */
+export declare function domainCommand(deps: DomainDeps, sub: DomainSub, opts?: DomainOptions): Promise<number>;
+/**
+ * The verify render, split out so the state→transcript mapping is one readable
+ * table and the exit code is computed in exactly one place per arm.
+ */
+export declare function renderVerify(deps: Pick<DomainDeps, "print">, view: DomainView, roles: readonly (string | undefined)[]): number;
+/**
+ * The states where a creator returns to re-read the record values: pending,
+ * failing and held (QA-F16-C1). A creator whose brand is dark should not have to
+ * navigate to find the values again.
+ */
+export declare function needsRecordsReprinted(view: Pick<DomainView, "state">): boolean;