@vincentt-xr/cli 0.15.1 → 0.16.0

package/dist/domain/copy.js

@@ -0,0 +1,952 @@
+// Every line `vincentt domain` prints (how-it-works.md Part 2B, Flows C1-C7).
+// Pure functions returning string arrays, so the transcripts are assertable
+// without a terminal.
+//
+// THE VOCABULARY, fixed before anything else (Part 2B § The vocabulary). Eight
+// words, each refusing a plausible alternative:
+//   - "Attach" / "Detach". `add`/`remove` are SILENT aliases. *Remove* reads as
+//     delete the row, and the row is NEVER deleted — its survival across a detach
+//     IS the takeover defence.
+//   - "Your Vincentt address", never "the default", "the fallback", "the free
+//     address". *Fallback* inverts B-F2-7 in a single word.
+//   - "Serving" / "not serving", never active/inactive, enabled/disabled,
+//     up/down. Serving is the only verb true in every state that blames nobody.
+//   - "DNS changed", never misconfigured/broken/invalid/error. The creator
+//     changed a record they own, which they are entitled to do (B-F1-7).
+//   - "Not connected", never removed/deleted/expired/suspended/offline.
+//     *Offline* is f4's word for a creator's deliberate choice.
+//   - "The value", never token/secret/key. Public in DNS by construction — the
+//     wrong noun makes creators hide it and reviewers think we leaked it.
+//   - "Whoever manages DNS for acme.com", not "your registrar", wherever the
+//     reader may not control the zone.
+//   - "Keep this one", on exactly one record.
+//
+// NEVER PRINTED, in any state: the org id, project id, PAT, distribution id,
+// certificate ARN, KVS key, any resolver hostname of ours, a raw DNS library
+// error, or a stack trace. THE VERIFICATION VALUE IS PRINTED — public by
+// construction — and is never called a token, secret or key.
+import { VALIDATION_RECORD_GONE, } from "./wire.js";
+import { recordNamePairs } from "./names.js";
+/** The section rule. Not f4's fenced `─── FIRST PUBLISH ───`: nothing here is irreversible. */
+const RULE_WIDTH = 74;
+function sectionRule(label) {
+    const head = `  ─── ${label} `;
+    const dashes = Math.max(3, RULE_WIDTH - head.length);
+    return `${head}${"─".repeat(dashes)}`;
+}
+function closingRule() {
+    return `  ${"─".repeat(RULE_WIDTH - 2)}`;
+}
+// ---- the state vocabulary ----------------------------------------------------
+/**
+ * The state words are the console's badge words, LOWERCASED (transcript L43
+ * decision 3). One word set across both surfaces — if the console badge and this
+ * column disagree, the console label is wrong.
+ *
+ * An unrecognized state renders as ITSELF rather than as a plausible neighbour.
+ * A newer API sending an eighth state must not read as `not verified`, which
+ * would tell a creator nothing is wrong when something might be.
+ */
+export function stateWord(view) {
+    switch (view.state) {
+        case "pending":
+            return "not verified";
+        case "verified":
+            return "setting up";
+        case "live":
+            return "live";
+        case "failing":
+            return "dns changed";
+        case "held":
+            return "not connected";
+        case "cert_failed":
+            return "no certificate";
+        case "detached":
+            return "detached";
+        default:
+            return view.rawState || "unknown";
+    }
+}
+/** Is the domain serving right now? Drives the alias-stance line. */
+export function isServing(view) {
+    return view.state === "live" || view.state === "failing";
+}
+// ---- the record block, BOTH NAME FORMS ---------------------------------------
+/**
+ * The label for each name form. It names THE BOX ON THEIR SCREEN, never the DNS
+ * concept (Flow C1 rule 4): *relative* and *fully-qualified* are correct and
+ * useless — a creator who knew those words would not make this mistake.
+ */
+const SHORT_TELL = "← most registrars want this";
+const LONG_TELL_1 = "← only if the field already";
+const LONG_TELL_2 = "shows your full domain";
+/**
+ * The rule label for one record, naming it by WHAT IT IS FOR.
+ *
+ * `CNAME · certificate` is what distinguishes the validation record at a glance
+ * from the pointer CNAME, which is the same type. The label is derived from the
+ * record's ROLE when the API names one and falls back to the bare type — it is
+ * never invented from the record's name, because a name-sniffing heuristic
+ * (`starts with _`) would mislabel a future record.
+ */
+export function recordLabel(record, role) {
+    if (role === "certificate")
+        return `${record.type} · certificate`;
+    return record.type;
+}
+/**
+ * Which record carries the keep-this-one caption?
+ *
+ * The certificate validation record, and ONLY it (Flow C1). Its deletion is the
+ * only fault in this feature with a delayed consequence — every other record
+ * fails immediately and visibly. `"keep this"` beside three records reads as
+ * boilerplate, which is why exactly one carries it.
+ *
+ * Decided from the ROLE the API names, never sniffed from the value. A heuristic
+ * on `acm-validations.aws` would break the day the CA changes, and it would break
+ * silently — into the arm where the caption is ABSENT, which is the expensive
+ * direction.
+ */
+export function carriesKeepCaption(role) {
+    return role === "certificate";
+}
+/**
+ * The keep-this-one caption. The caption NAMES THE DELAY explicitly, because a
+ * creator who reads only the first clause must not conclude they can ignore it.
+ *
+ * It is NOT an alert and carries no tint — a warning colour on a record someone
+ * is being asked to CREATE reads as an incident at the moment of creation.
+ */
+export function keepCaption() {
+    return [
+        "    Keep this one. It is what renews the certificate, on its own, for as long",
+        "    as it is published. Deleting it doesn't break anything today - it stops",
+        "    the renewal months later.",
+    ];
+}
+const NAME_COLUMN = 12;
+const VALUE_COLUMN = 44;
+/**
+ * One record's block, with BOTH NAME FORMS, SHORT FIRST.
+ *
+ * Four rules from Flow C1, and every one of them is load-bearing:
+ *   1. NEVER ONE FORM. Printing the FQDN alone is what every researched platform
+ *      does, and it is why this failure is universal.
+ *   2. NEVER "or". That hands the creator a decision with no basis for making it;
+ *      two labelled lines give them a test they can run against the screen in
+ *      front of them.
+ *   3. THE SHORT FORM IS FIRST — the majority want it, and the first line is what
+ *      a hurrying creator copies. (QA-F16-C1 asserts this.)
+ *   4. Labels name the box on their screen, never the DNS concept.
+ *
+ * When the relative form cannot be derived (see names.ts) only the FQDN prints,
+ * WITHOUT the short-form tell. Printing an underived relative name would be the
+ * wrong-form paste this block exists to prevent, and printing the tell beside a
+ * lone FQDN would claim most registrars want the value on that line.
+ */
+export function recordBlock(record, pair, role) {
+    const out = ["", sectionRule(recordLabel(record, role)), ""];
+    const label = (s) => `    ${s.padEnd(NAME_COLUMN - 4)}`;
+    if (pair.relative !== undefined) {
+        // The tell column is computed from the ACTUAL widths of the two names, never
+        // from a fixed constant. A name longer than the constant used to run into
+        // the `←`, which reads as one token and is exactly the ambiguity this block
+        // exists to remove. The minimum keeps the common case aligned with the value
+        // rows below it.
+        // TWO spaces minimum, not one: at one the longest name and the `←` read as a
+        // single token, which is the ambiguity this block exists to remove.
+        const nameWidth = Math.max(VALUE_COLUMN - NAME_COLUMN, pair.relative.length + 2, pair.fqdn.length + 2);
+        const gutter = " ".repeat(NAME_COLUMN - 4);
+        out.push(`${label("Name")}${pair.relative.padEnd(nameWidth)}${SHORT_TELL}`);
+        out.push(`    ${gutter}${pair.fqdn.padEnd(nameWidth)}${LONG_TELL_1}`);
+        // The continuation of the long tell hangs under its first line, indented to
+        // the tell's own column rather than to the name column.
+        out.push(`    ${gutter}${" ".repeat(nameWidth)}   ${LONG_TELL_2}`);
+    }
+    else {
+        out.push(`${label("Name")}${pair.fqdn}`);
+    }
+    out.push(`${label("Value")}${record.value}`);
+    // The TTL line names no number of ours. A TTL the platform printed becomes a
+    // value a creator tries to match exactly, and registrars offer different sets.
+    out.push(`${label("TTL")}whatever your registrar offers; the lowest is fine`);
+    if (carriesKeepCaption(role)) {
+        out.push("", ...keepCaption());
+    }
+    return out;
+}
+/**
+ * The disambiguating paragraph. PROSE, not a footnote, and it names the VISIBLE
+ * TELL — *"if yours already shows `.acme.com` beside the box"*. That is the one
+ * observation that resolves the ambiguity without teaching DNS, and it is the
+ * sentence that has to survive a skim.
+ */
+export function twoFormParagraph(zone) {
+    return [
+        `  Registrars disagree about this field. If yours already shows ".${zone}"`,
+        "  beside the box, use the short name. If it wants the whole thing, use the",
+        "  long one. Picking the wrong one creates a record that never verifies.",
+    ];
+}
+/**
+ * The whole three-record block, fenced together ONCE.
+ *
+ * `roles` is parallel to `records` and comes from the API. The CLI does not
+ * decide which record is the certificate one.
+ */
+export function allRecordBlocks(records, domain, roles = []) {
+    const pairs = recordNamePairs(records, domain);
+    const out = [];
+    records.forEach((r, i) => out.push(...recordBlock(r, pairs[i], roles[i])));
+    out.push("", closingRule());
+    return out;
+}
+// ---- the alias stance --------------------------------------------------------
+/**
+ * The permanent address, named UNPROMPTED, in every state where the custom domain
+ * is not working (CLI convention 4).
+ *
+ * "Your Vincentt address" — never "the default", "the fallback", "the free
+ * address". The line costs one line and it is the single most valuable thing this
+ * feature does.
+ *
+ * Returns NOTHING when the API did not send a permanent address. A line naming an
+ * address the CLI assembled itself would print the wrong host on staging and dev,
+ * for the reason `liveUrl` is server-computed everywhere else in this CLI.
+ */
+export function aliasStance(domain, permanentAddress, serving) {
+    if (!permanentAddress)
+        return [];
+    if (serving) {
+        return [`  It serves the same version as ${permanentAddress}, which is unchanged.`];
+    }
+    return [
+        `  ${domain} is not serving yet. ${permanentAddress} is, and is`,
+        "  not affected by anything here.",
+    ];
+}
+/** The same fact for a domain that WAS serving and stopped. */
+export function aliasStanceStopped(permanentAddress) {
+    if (!permanentAddress)
+        return [];
+    return [`  ${permanentAddress} is serving, and is not affected.`];
+}
+// ---- the findings, the feature's differentiation -----------------------------
+/**
+ * Severity per finding code. THE GLYPH CARRIES THE DISTINCTION AND THE EXIT CODE
+ * FOLLOWS THE GLYPH, NOT THE COUNT (CLI convention 3).
+ *
+ *   `✗` blocking  = this is why it does not work.
+ *   `!` advisory  = observed, and it blocks nothing.
+ *
+ * PROXY_IN_FRONT is advisory and NEVER blocking: a creator who wants a proxy in
+ * front is making a choice we do not own, the detection is heuristic, and the
+ * register must survive being wrong.
+ *
+ * VALIDATION_RECORD_GONE is advisory (D-44) — the row works and the horizon
+ * is months. Escalating its glyph would teach a creator that `✗` sometimes means
+ * *working fine*, which is how the severity ladder stops carrying information.
+ *
+ * An UNRECOGNIZED code defaults to ADVISORY. That direction is deliberate: a
+ * newer API's unknown finding must not fail a verify that the server considered
+ * successful, because the exit code is what an agent branches on. The finding
+ * still PRINTS in full — nothing is hidden, only its effect on the exit code is
+ * conservative.
+ */
+const BLOCKING_CODES = new Set([
+    "TOKEN_MISSING",
+    "TOKEN_MISMATCH",
+    "WRONG_RECORD_TYPE",
+    "CNAME_WRONG_TARGET",
+    "CONFLICTING_RECORDS",
+    "CAA_BLOCKS_ISSUANCE",
+    "MALFORMED_ZONE",
+]);
+/**
+ * The severity of one finding.
+ *
+ * `wireSeverity` is the API's own classification when it sends one, and it WINS:
+ * the exit code the CLI returns must not disagree with the state the server put
+ * the domain in, and the server is the party that performed the observation.
+ *
+ * The local table is the fallback for an API that sends no severity, and it is
+ * derived from the design record rather than from the producer:
+ *   - PROXY_IN_FRONT is advisory and NEVER blocking (Scenario 4's accepted
+ *     constraint: heuristic, worded as an observation, "never blocking").
+ *   - STALE_ACME_CHALLENGE is advisory ("it blocks nothing; you can delete it").
+ *   - UNEXPECTED_AAAA and TOKEN_STALE_PRESENT are advisory: each is an
+ *     observation beside a row whose failure, if any, is named by another finding.
+ *
+ * KNOWN DIVERGENCE, reported rather than papered over: the producer's
+ * `DomainFinding.Severity()` currently classes ONLY VALIDATION_RECORD_GONE as
+ * advisory, which would make a proxy observation alone exit non-zero and
+ * contradict "an all-advisory report exits 0". Honoring a wire severity means
+ * the CLI tracks the server once that is settled instead of holding a second
+ * opinion in a second language.
+ */
+export function findingSeverity(code, wireSeverity) {
+    if (wireSeverity === "advisory")
+        return "advisory";
+    if (wireSeverity === "fault" || wireSeverity === "blocking")
+        return "blocking";
+    return BLOCKING_CODES.has(code) ? "blocking" : "advisory";
+}
+export function severityGlyph(s) {
+    return s === "blocking" ? "✗" : "!";
+}
+/**
+ * The title and remedy body for each finding code. COPY IS FIXED IN ONE FILE,
+ * KEYED BY THE CLOSED ENUM, so neither surface invents a string.
+ *
+ * Every entry has a title naming THE SPECIFIC FAULT and a body naming the remedy
+ * IN THE CREATOR'S TERMS. Neither ever says "contact support" — that implies a
+ * queue, a state machine and an SLA, none of which exist.
+ */
+const FINDING_COPY = {
+    TOKEN_MISSING: {
+        title: () => "We can't find the TXT record",
+        body: [
+            "Create it exactly as shown above. If you just added it, DNS can take a",
+            "few minutes to publish.",
+        ],
+    },
+    TOKEN_MISMATCH: {
+        title: () => "The TXT record holds a different value",
+        body: ["Usually means it was copied from another workspace or another domain."],
+    },
+    TOKEN_STALE_PRESENT: {
+        title: () => "An older verification value is still published",
+        body: [
+            "There is more than one value at that name. Delete the ones that don't",
+            "match what's shown above.",
+        ],
+    },
+    WRONG_RECORD_TYPE: {
+        title: (d) => `${d} is an A record, not a CNAME`,
+        body: [
+            "An A record points at a fixed address; ours moves. Delete the A record",
+            "and create the CNAME. Most registrars won't let both exist.",
+        ],
+    },
+    CNAME_WRONG_TARGET: {
+        title: () => "The CNAME points somewhere else",
+        body: ["Change it to the value shown above."],
+    },
+    CONFLICTING_RECORDS: {
+        title: (d) => `${d} has both an A record and a CNAME`,
+        body: [
+            "Only one can apply. Delete the A record and keep the CNAME shown above.",
+        ],
+    },
+    UNEXPECTED_AAAA: {
+        title: () => "There's also an AAAA record",
+        body: [
+            "IPv6 visitors will go to that address instead of ours. Delete it unless",
+            "you meant it.",
+        ],
+    },
+    PROXY_IN_FRONT: {
+        // Worded as an OBSERVATION, never a verdict. The mechanism names it heuristic
+        // and never blocking, and the register must survive being wrong. It reports a
+        // proxy when it sees one and NEVER asserts absence.
+        title: () => "The address resolves into another provider's network",
+        body: [
+            "Something is proxying this domain in front of us. That may be",
+            "deliberate and nothing here blocks it - but while it's on, the",
+            "certificate we issue may not be the one your visitors receive.",
+        ],
+    },
+    CAA_BLOCKS_ISSUANCE: {
+        title: () => "A CAA record stops us issuing",
+        body: [
+            "This is often set on the parent domain rather than on this name, and",
+            "often by whoever manages the company's DNS rather than by you.",
+        ],
+    },
+    STALE_ACME_CHALLENGE: {
+        title: () => "An old certificate-validation record is still published",
+        body: ["Left over from a previous host. It blocks nothing; you can delete it."],
+    },
+    VALIDATION_RECORD_GONE: {
+        // D-44. NO DATE, NO DAY COUNT — the remaining-days figure IS on the wire, for
+        // the operator, and the finding shape carries NO NUMERIC SLOT AT ALL, so it
+        // cannot reach this surface. A number converts an act-now into a
+        // schedule-later, and the honest remedy is *put it back now*.
+        //
+        // The reassurance clause is INVERTED here: elsewhere it reassures about the
+        // Vincentt address; here the domain itself is fine, so it reassures about
+        // TODAY and names the delay — in that order.
+        title: () => "The certificate's validation record is gone",
+        body: [
+            "is serving normally and nothing stops today. But that",
+            "record is what renews the certificate, so put it back before the",
+            "current one runs out.",
+        ],
+    },
+    MALFORMED_ZONE: {
+        title: () => "We couldn't read the DNS for this name",
+        body: [
+            "The zone returned more records than we can read, or returned them",
+            "malformed. Whoever manages DNS for this domain can see more than we can.",
+        ],
+    },
+};
+const OBSERVED_LABEL_WIDTH = 10;
+/**
+ * One finding, rendered.
+ *
+ * `expected` / `observed` are STACKED AND COLUMN-ALIGNED, never inline — f2's
+ * rule for two values a creator must judge, and the shape that makes the
+ * difference visible at a glance. This is why f16 beats every researched
+ * competitor, all of whom print only the expected record.
+ *
+ * `observed` IS PRINTED AS THE STRING THE WIRE SENT. It is not parsed, not
+ * re-rendered, and not reformatted. The wire says it is a string and never
+ * structured precisely so a client cannot lose the fidelity that is the point of
+ * the ruling.
+ *
+ * `expected` is omitted when the API sent none — the pair degrades to the
+ * observed line alone rather than printing an invented expectation.
+ */
+export function findingLines(f, domain) {
+    const severity = findingSeverity(f.code, f.severity);
+    const copy = FINDING_COPY[f.code];
+    const glyph = severityGlyph(severity);
+    // An unrecognized code still prints, with the code itself as the title. A
+    // finding the CLI cannot name is strictly better rendered as an opaque title
+    // plus its observed value than dropped — the observed value is the diagnosis.
+    const title = copy ? copy.title(domain) : f.code;
+    const out = [`  ${glyph}  ${title}`];
+    const label = (l) => `       ${l.padEnd(OBSERVED_LABEL_WIDTH)}`;
+    if (f.expected !== undefined)
+        out.push(`${label("expected")}${f.expected}`);
+    out.push(`${label("observed")}${f.observed}`);
+    if (copy) {
+        const indent = "       ";
+        // The certificate advisory's body opens mid-sentence so the domain leads it.
+        const body = f.code === VALIDATION_RECORD_GONE
+            ? [`${domain} ${copy.body[0]}`, ...copy.body.slice(1)]
+            : copy.body;
+        for (const line of body)
+            out.push(`${indent}${line}`);
+    }
+    return out;
+}
+/**
+ * The whole findings report, ORDERED `✗` BEFORE `!`.
+ *
+ * A creator who reads only the first block reads the thing that is actually
+ * stopping them. Within each severity the API's own order is preserved — it
+ * observed them and it orders cause before consequence.
+ */
+export function findingsReport(findings, domain) {
+    const blocking = findings.filter((f) => findingSeverity(f.code, f.severity) === "blocking");
+    const advisory = findings.filter((f) => findingSeverity(f.code, f.severity) === "advisory");
+    const out = [];
+    for (const f of [...blocking, ...advisory]) {
+        out.push("", ...findingLines(f, domain));
+    }
+    return out;
+}
+/**
+ * THE EXIT CODE FOLLOWS THE GLYPH, NEVER THE COUNT (CLI convention 3,
+ * QA-F16-C2).
+ *
+ * An all-advisory report exits 0. A report with ten advisories and no blocking
+ * finding exits 0. A report with one blocking finding exits 1 regardless of how
+ * many advisories sit beside it.
+ *
+ * This is the whole of the mapping and it is deliberately a function of the
+ * findings alone, so it cannot be reached through a code path that also consults
+ * a count.
+ */
+export function exitCodeForFindings(findings) {
+    return findings.some((f) => findingSeverity(f.code, f.severity) === "blocking")
+        ? 1
+        : 0;
+}
+/** f4's after-a-non-zero-exit rule. An agent's most expensive failure is retrying against a half-applied state. */
+export const NOTHING_WAS_CHANGED = "  Nothing was changed.";
+export const NOTHING_WAS_CLAIMED = "  Nothing was claimed.";
+// ---- the refusals ------------------------------------------------------------
+/**
+ * At the ceiling. A LIMIT IS PRINTED AS A NUMBER, NEVER AS A POLICY OR A PLAN
+ * (f4's CLI rule), and the remedy names a HUMAN ROLE per f12's rule that unbidden
+ * output names a fact, never an instruction to buy.
+ *
+ * No price, no plan name other than the one they are on, no URL. Clause 4 reaches
+ * the CLI too.
+ */
+export function refusedAtCeiling(limit) {
+    return [
+        "",
+        `✗ This workspace is using all ${limit} of the custom domains its plan carries.`,
+        "",
+        "  Detach one to attach this:",
+        "    vincentt domain list",
+        "    vincentt domain detach <domain>",
+        "",
+        "  An owner can change the workspace's plan in the console.",
+        "",
+        NOTHING_WAS_CLAIMED,
+        "",
+    ];
+}
+/**
+ * Already attached — THE ANTI-ORACLE ANSWER.
+ *
+ * BYTE-IDENTICAL whether the name is held by this workspace or by a stranger's.
+ * It never says *another workspace*, never says *yours*, never names a project.
+ * f2's slug-collision discipline applied to the second global host namespace.
+ *
+ * The `list` line is safe precisely because `list` only ever shows the caller's
+ * own domains — a creator who genuinely holds the name finds it there.
+ *
+ * IT TAKES NO ARGUMENT BEYOND THE HOSTNAME. A "you already have this"
+ * convenience message is the exact shape that breaks this, and it is the first
+ * thing a tidying PR adds.
+ */
+export function refusedAlreadyAttached(domain) {
+    return [
+        "",
+        `✗ ${domain} is already attached to a project.`,
+        "",
+        "  If it's yours, find it with:",
+        "    vincentt domain list",
+        "",
+        NOTHING_WAS_CLAIMED,
+        "",
+    ];
+}
+/** A platform address. */
+export function refusedPlatformHost() {
+    return [
+        "",
+        "✗ That's already a Vincentt address.",
+        "",
+        "  Custom domains are for names you own at your own registrar.",
+        "",
+        NOTHING_WAS_CLAIMED,
+        "",
+    ];
+}
+/**
+ * A root domain. The reason is one clause and it is ABOUT THE CREATOR'S
+ * REGISTRAR, not about our infrastructure.
+ *
+ * A refusal with no reason gets retried; a refusal whose reason is *"our CDN
+ * doesn't support it"* sounds like something we might fix on request.
+ */
+export function refusedRootDomain(domain) {
+    const zone = domain || "acme.com";
+    return [
+        "",
+        `✗ Root domains aren't supported - use a subdomain like ar.${zone}.`,
+        "",
+        "  A root domain needs a record type that works differently at every",
+        "  registrar. A subdomain uses a plain CNAME, which is the same everywhere.",
+        "",
+        NOTHING_WAS_CLAIMED,
+        "",
+    ];
+}
+/** Not on a plan that carries custom domains. Names the plan they are on and nothing else. */
+export function refusedNoEntitlement(planName) {
+    const plan = planName ? ` This workspace is on ${planName}.` : "";
+    return [
+        "",
+        `✗ Custom domains are part of the paid plans.${plan}`,
+        "",
+        "  An owner can change the workspace's plan in the console.",
+        "",
+        NOTHING_WAS_CLAIMED,
+        "",
+    ];
+}
+/**
+ * A verify refused by the rate limit.
+ *
+ * `Retry-After` says HOW LONG, never WHICH LIMIT. All refusal bodies are
+ * byte-identical across causes, so this copy names no limit family.
+ */
+export function refusedTooSoon(retryAfterSec) {
+    const when = retryAfterSec ? ` Try again in ${approxWait(retryAfterSec)}.` : "";
+    return [
+        "",
+        `✗ That was checked very recently.${when}`,
+        "",
+        "  We also check on our own every few hours.",
+        "",
+        NOTHING_WAS_CHANGED,
+        "",
+    ];
+}
+function approxWait(seconds) {
+    if (seconds < 90)
+        return "about a minute";
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `about ${minutes} minutes`;
+    const hours = Math.round(minutes / 60);
+    return `about ${hours} hour${hours === 1 ? "" : "s"}`;
+}
+/**
+ * The uniform not-found. A hostname not attached to THIS project returns the same
+ * 404 as one that does not exist, one held by a stranger, and a version that does
+ * not exist — so the CLI's copy for it must be equally uniform.
+ */
+export function notAttached(domain) {
+    return [
+        "",
+        `✗ ${domain} isn't attached to this project.`,
+        "",
+        "  See what is:",
+        "    vincentt domain list",
+        "",
+        NOTHING_WAS_CHANGED,
+        "",
+    ];
+}
+export function attachSuccess(i) {
+    const zone = i.domain.slice(i.domain.indexOf(".") + 1);
+    const header = i.projectName
+        ? [i.orgName ? `→ ${i.projectName} · ${i.orgName}` : `→ ${i.projectName}`]
+        : [];
+    return [
+        "",
+        ...header,
+        `✓ Claimed ${i.domain}`,
+        "",
+        `  Create these three records at whoever manages DNS for ${zone}.`,
+        "  All three are required - the CNAME sends visitors here, the TXT proves the",
+        "  domain is yours, and the third keeps the certificate renewing.",
+        ...allRecordBlocks(i.records, i.domain, i.roles ?? []),
+        "",
+        ...twoFormParagraph(zone),
+        "",
+        ...aliasStance(i.domain, i.permanentAddress, false),
+        "",
+        "  Check when the records are in:",
+        `    vincentt domain verify ${i.domain}`,
+        "",
+        "  We also check on our own every few hours.",
+        "",
+    ];
+}
+// ---- verify ------------------------------------------------------------------
+export function verifyReading(domain) {
+    return `→ Reading DNS for ${domain}…`;
+}
+/**
+ * Not ready. Every finding names what was actually observed.
+ *
+ * The remedy is THE EXACT COMMAND, last. Not "try again", not a URL.
+ */
+export function verifyNotReady(domain, findings, permanentAddress) {
+    return [
+        "",
+        `✗ ${domain} isn't ready yet.`,
+        ...findingsReport(findings, domain),
+        "",
+        ...aliasStanceStopped(permanentAddress),
+        "",
+        "  Fix what you can, then:",
+        `    vincentt domain verify ${domain}`,
+        "",
+        NOTHING_WAS_CHANGED,
+        "",
+    ];
+}
+/**
+ * Ready, and live.
+ *
+ * The `!` about hard-coded canonical/og:url sits BELOW the success because the
+ * creator's next act is to share the address, and the advisory is about what
+ * happens when they do. IT IS AN ADVISORY AND NEVER AN EDIT — B-F4-2.
+ */
+export function verifyLive(domain, permanentAddress, liveVersion) {
+    const version = liveVersion === undefined ? "" : ` (v${liveVersion})`;
+    const same = permanentAddress
+        ? [
+            "",
+            `  It serves the same version as ${permanentAddress}${version},`,
+            "  which is unchanged.",
+        ]
+        : [];
+    return [
+        `✓ ${domain} is yours - the TXT record matches.`,
+        "✓ The CNAME points at us.",
+        `✓ Live at https://${domain}`,
+        ...same,
+        "",
+        "! If your build hard-codes its Vincentt address in a canonical or og:url",
+        "  tag, link previews on the new address will still point at the old one.",
+        "  We don't change your files - edit the source and publish again.",
+        "",
+    ];
+}
+/**
+ * Ready, serving, but with advisory findings (D-44's case among them).
+ *
+ * EXIT 0, because every finding is `!` and the domain is serving. The success
+ * lines above are UNCHANGED — escalating the glyph would teach a creator that `✗`
+ * sometimes means *working fine*.
+ *
+ * When the certificate validation record is the missing one, THE RECORD IS
+ * RE-PRINTED: the entire cause of this state is a record the creator tidied away,
+ * and the remedy has to be on the screen rather than a command away. This is the
+ * one place a `verify` success prints a record block.
+ */
+export function verifyServingWithAdvisories(domain, findings, reprint, roles) {
+    const out = [
+        `✓ ${domain} is yours - the TXT record matches.`,
+        "✓ The CNAME points at us.",
+        `✓ Serving at https://${domain}`,
+        ...findingsReport(findings, domain),
+    ];
+    if (reprint.length > 0) {
+        out.push(...allRecordBlocks(reprint, domain, roles));
+    }
+    out.push("");
+    return out;
+}
+/**
+ * Flow C5 — `failing`: STILL SERVING, and the reader can still prevent the stop.
+ *
+ * This arm exists because the serving-with-advisories one is FALSE here. That
+ * one opens *"✓ ar.acme.com is yours — the TXT record matches"*, which sat
+ * directly above *"✗ We can't find the TXT record"* — the screen contradicting
+ * itself in two adjacent lines. A `failing` domain is serving on a record we can
+ * no longer see, so nothing about the DNS may be reported as confirmed.
+ *
+ * The date is ABSOLUTE, never a countdown, and the stop is described BY WHAT A
+ * VISITOR SEES rather than by an internal state — the fact that makes a creator
+ * act. The reassurance clause is mandatory: their first fear on reading this is
+ * that they are losing their work.
+ */
+export function verifyFailing(domain, findings, holdsAt, permanentAddress) {
+    const when = shortDate(holdsAt);
+    const deadline = when
+        ? [
+            `  ${domain} is still serving, and keeps serving until ${when}.`,
+            `  If the record is back before then, nothing happens and this goes away`,
+            "  on its own. If it isn't, visitors see a Vincentt page under your name.",
+        ]
+        : [
+            `  ${domain} is still serving. If the record stays missing it stops, and`,
+            "  visitors see a Vincentt page under your name.",
+        ];
+    return [
+        "",
+        `✗ We can't find ${domain}'s verification record.`,
+        ...findingsReport(findings, domain),
+        "",
+        ...deadline,
+        "",
+        ...aliasStanceStopped(permanentAddress),
+        "",
+        "  Once the record is back:",
+        `    vincentt domain verify ${domain}`,
+        "",
+        NOTHING_WAS_CHANGED,
+        "",
+    ];
+}
+/**
+ * The certificate did not come.
+ *
+ * The one thing this state does that no other does: IT NAMES A DIFFERENT ACTOR.
+ * A CAA record usually lives on the parent zone and is usually somebody else's,
+ * and copy that assumes the reader controls it sends them looking in the wrong
+ * place. It never says "contact support" — that implies a queue this product does
+ * not have.
+ */
+export function verifyCertFailed(domain, findings, permanentAddress) {
+    return [
+        `✓ ${domain} is yours - the TXT record matches.`,
+        "✓ The CNAME points at us.",
+        `✗ We couldn't get a certificate for ${domain}.`,
+        ...findingsReport(findings, domain),
+        "",
+        "  The domain is proven yours; a browser just won't trust it until there",
+        "  is a certificate. We keep retrying on our own.",
+        "",
+        ...aliasStanceStopped(permanentAddress),
+        "",
+        `    vincentt domain verify ${domain}`,
+        "",
+        NOTHING_WAS_CHANGED,
+        "",
+    ];
+}
+// ---- list --------------------------------------------------------------------
+/** The absolute date a creator reads. NEVER "in 13 days", which drifts while a tab is open. */
+const MONTHS = [
+    "Jan", "Feb", "Mar", "Apr", "May", "Jun",
+    "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
+];
+export function shortDate(iso) {
+    if (!iso)
+        return "";
+    const d = new Date(iso);
+    if (Number.isNaN(d.getTime()))
+        return "";
+    return `${d.getUTCDate()} ${MONTHS[d.getUTCMonth()]}`;
+}
+/**
+ * Flow L43 — a listing verb REPORTS; it never asks and never picks.
+ *
+ * A fact longer than a column goes on an INDENTED CONTINUATION LINE at a constant
+ * indent (f2's rule, verbatim). The stop-date and the resume sentence are the two
+ * facts that do not fit a column and must not become a fifth one.
+ *
+ * `list` shows ONLY THIS WORKSPACE'S domains — which is what makes the
+ * anti-oracle collision message safe.
+ */
+const LIST_CONTINUATION = "      ";
+export function listRows(domains) {
+    if (domains.length === 0)
+        return [];
+    const dw = Math.max(6, ...domains.map((d) => d.domain.length));
+    const pw = Math.max(7, ...domains.map((d) => (d.projectName ?? "").length));
+    const sw = Math.max(5, ...domains.map((d) => stateWord(d).length));
+    const out = [
+        `  ${"DOMAIN".padEnd(dw)}  ${"PROJECT".padEnd(pw)}  ${"STATE".padEnd(sw)}  SINCE`,
+    ];
+    for (const d of domains) {
+        out.push(`  ${d.domain.padEnd(dw)}  ${(d.projectName ?? "").padEnd(pw)}  ${stateWord(d).padEnd(sw)}  ${shortDate(d.attachedAt)}`);
+        if (d.state === "failing" && d.holdsAt) {
+            out.push(`${LIST_CONTINUATION}stops serving on ${shortDate(d.holdsAt)} unless the TXT record is back`);
+        }
+        if (d.state === "held") {
+            out.push(`${LIST_CONTINUATION}put the TXT record back and it resumes on its own`);
+        }
+    }
+    return out;
+}
+/**
+ * The entitlement line — A BARE COUNT AND THE PLAN NAME. No price, no ladder, no
+ * *"upgrade for more"*. Clause 4 reaches the CLI too.
+ *
+ * A zero denominator is never rendered, and an absent limit renders the count
+ * alone rather than inventing one.
+ */
+export function entitlementLine(count, limit, planName) {
+    if (count === undefined)
+        return [];
+    const plan = planName ? ` · ${planName} plan` : "";
+    if (limit === undefined || limit <= 0) {
+        return [`  ${count} custom domain${count === 1 ? "" : "s"}${plan}`];
+    }
+    return [`  ${count} of ${limit} custom domains${plan}`];
+}
+export function listEmpty(planName) {
+    const plan = planName ? ` · ${planName} plan` : "";
+    return [
+        "",
+        `  No custom domains${plan}`,
+        "",
+        "  Attach one to a published project:",
+        "    vincentt domain attach ar.example.com",
+        "",
+    ];
+}
+// ---- detach ------------------------------------------------------------------
+/**
+ * Flow C7 — the confirmation.
+ *
+ * `[y/N]`, AND IT IS NOT f4's IRREVERSIBLE CASING BEING MISAPPLIED. Detaching IS
+ * undoable — but the default is No because the act is IMMEDIATELY VISIBLE TO
+ * STRANGERS, and an accidental Enter would take a client's advertised address dark
+ * mid-campaign. The bracket casing tracks *would an accidental Enter be
+ * expensive*, and this one would (shared.md § the refined convention).
+ *
+ * THE COPY DELIBERATELY CONTRADICTS f4's PERMANENCE SENTENCE. A detached custom
+ * domain is NOT burned — the platform has no authority over the creator's
+ * registrar, and copy that "consistently" applied f4's permanence language would
+ * be a false claim about someone else's property. Stated positively: the name
+ * stays yours, and you can delete our three records.
+ *
+ * No fenced block: f4 reserves fencing for the irreversible.
+ */
+export function detachDisclosure(domain, permanentAddress) {
+    const alias = permanentAddress
+        ? [`  ${permanentAddress} is unaffected and keeps serving.`]
+        : [];
+    return [
+        "",
+        `  ${domain} stops serving immediately.`,
+        ...alias,
+        "",
+        "  The name stays yours - point it wherever you like, or attach it again",
+        "  later. You can delete the three Vincentt records at your registrar.",
+        "",
+    ];
+}
+export function detachPrompt(domain) {
+    return `  Detach ${domain}? [y/N] `;
+}
+export function detachDone(domain) {
+    return ["", `✓ Detached ${domain}`, "", "  It no longer serves this project.", ""];
+}
+/** Declined. Exit 0, ZERO network calls. Declining is not a failure; it is the prompt working. */
+export function detachDeclined(domain) {
+    return ["", `  ${domain} is unchanged and still serving.`, ""];
+}
+/**
+ * Already detached — a SILENT RESOLVE, not an error. The creator asked for a
+ * state the world is already in.
+ */
+export function detachAlready(domain) {
+    return ["", `✓ ${domain} is not attached to this project.`, ""];
+}
+/**
+ * A non-TTY detach with no explicit flag. REFUSE; NEVER ASSUME YES.
+ *
+ * A pipe cannot consent. The remedy names the flag, because an agent that reaches
+ * this needs to know the act is available rather than concluding detach is
+ * console-only.
+ */
+export function detachNeedsConsent(domain) {
+    return [
+        "",
+        "✗ Detaching takes a confirmation, and there's no terminal to ask on.",
+        "",
+        `  Re-run with --yes to detach ${domain} without being asked.`,
+        "",
+        NOTHING_WAS_CHANGED,
+        "",
+    ];
+}
+// ---- the routed non-verbs -----------------------------------------------------
+/**
+ * `renew` gets a FACT rather than a redirect, because the honest answer is that
+ * the act does not exist. f4's rule: a creator typing a plausible verb has told us
+ * exactly what they want.
+ */
+export function noRenewVerb() {
+    return [
+        "",
+        "✗ There's no `domain renew` command.",
+        "",
+        "  Certificates renew on their own. There's nothing to run.",
+        "",
+    ];
+}
+export function unknownDomainSub(sub) {
+    return [
+        "",
+        `✗ There's no \`domain ${sub}\` command. You want:`,
+        "    vincentt domain list",
+        "",
+    ];
+}
+/** `vincentt domains` / `custom-domain` / `dns` — plausible verbs, answered. */
+export function domainVerbRedirect(typed) {
+    return [
+        "",
+        `✗ There's no \`${typed}\` command. You want:`,
+        "    vincentt domain list",
+        "",
+    ];
+}