@vincentt-xr/cli 0.15.1 → 0.16.0

package/dist/domain/copy.d.ts

@@ -0,0 +1,334 @@
+import { type DnsRecord, type DomainView, type Finding } from "./wire.js";
+import { type NamePair } from "./names.js";
+/**
+ * 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 declare function stateWord(view: Pick<DomainView, "state" | "rawState">): string;
+/** Is the domain serving right now? Drives the alias-stance line. */
+export declare function isServing(view: Pick<DomainView, "state">): boolean;
+/**
+ * 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 declare function recordLabel(record: DnsRecord, role?: string): string;
+/**
+ * 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 declare function carriesKeepCaption(role?: string): boolean;
+/**
+ * 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 declare function keepCaption(): string[];
+/**
+ * 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 declare function recordBlock(record: DnsRecord, pair: NamePair, role?: string): string[];
+/**
+ * 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 declare function twoFormParagraph(zone: string): string[];
+/**
+ * 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 declare function allRecordBlocks(records: readonly DnsRecord[], domain: string, roles?: readonly (string | undefined)[]): string[];
+/**
+ * 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 declare function aliasStance(domain: string, permanentAddress: string | undefined, serving: boolean): string[];
+/** The same fact for a domain that WAS serving and stopped. */
+export declare function aliasStanceStopped(permanentAddress: string | undefined): string[];
+export type Severity = "blocking" | "advisory";
+/**
+ * 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 declare function findingSeverity(code: string, wireSeverity?: string): Severity;
+export declare function severityGlyph(s: Severity): string;
+/**
+ * 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 declare function findingLines(f: Finding, domain: string): string[];
+/**
+ * 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 declare function findingsReport(findings: readonly Finding[], domain: string): string[];
+/**
+ * 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 declare function exitCodeForFindings(findings: readonly Finding[]): 0 | 1;
+/** f4's after-a-non-zero-exit rule. An agent's most expensive failure is retrying against a half-applied state. */
+export declare const NOTHING_WAS_CHANGED = "  Nothing was changed.";
+export declare const NOTHING_WAS_CLAIMED = "  Nothing was claimed.";
+/**
+ * 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 declare function refusedAtCeiling(limit: number): string[];
+/**
+ * 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 declare function refusedAlreadyAttached(domain: string): string[];
+/** A platform address. */
+export declare function refusedPlatformHost(): string[];
+/**
+ * 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 declare function refusedRootDomain(domain: string): string[];
+/** Not on a plan that carries custom domains. Names the plan they are on and nothing else. */
+export declare function refusedNoEntitlement(planName: string | undefined): string[];
+/**
+ * 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 declare function refusedTooSoon(retryAfterSec: number | undefined): string[];
+/**
+ * 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 declare function notAttached(domain: string): string[];
+/**
+ * Flow C1 — the transcript the whole feature turns on.
+ *
+ * NO PROMPT and no progress bar. Attaching asks nothing irreversible, so a prompt
+ * would be ceremony. The three records are fenced together once as SECTION rules
+ * rather than f4's `─── FIRST PUBLISH ───` block, which f4 reserves for the
+ * irreversible.
+ */
+export interface AttachRendered {
+    projectName?: string;
+    orgName?: string;
+    domain: string;
+    records: readonly DnsRecord[];
+    roles?: readonly (string | undefined)[];
+    permanentAddress?: string;
+}
+export declare function attachSuccess(i: AttachRendered): string[];
+export declare function verifyReading(domain: string): string;
+/**
+ * Not ready. Every finding names what was actually observed.
+ *
+ * The remedy is THE EXACT COMMAND, last. Not "try again", not a URL.
+ */
+export declare function verifyNotReady(domain: string, findings: readonly Finding[], permanentAddress: string | undefined): string[];
+/**
+ * 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 declare function verifyLive(domain: string, permanentAddress: string | undefined, liveVersion: number | undefined): string[];
+/**
+ * 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 declare function verifyServingWithAdvisories(domain: string, findings: readonly Finding[], reprint: readonly DnsRecord[], roles: readonly (string | undefined)[]): string[];
+/**
+ * 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 declare function verifyFailing(domain: string, findings: readonly Finding[], holdsAt: string | undefined, permanentAddress: string | undefined): string[];
+/**
+ * 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 declare function verifyCertFailed(domain: string, findings: readonly Finding[], permanentAddress: string | undefined): string[];
+export declare function shortDate(iso: string | undefined): string;
+export declare function listRows(domains: readonly DomainView[]): string[];
+/**
+ * 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 declare function entitlementLine(count: number | undefined, limit: number | undefined, planName: string | undefined): string[];
+export declare function listEmpty(planName: string | undefined): string[];
+/**
+ * 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 declare function detachDisclosure(domain: string, permanentAddress: string | undefined): string[];
+export declare function detachPrompt(domain: string): string;
+export declare function detachDone(domain: string): string[];
+/** Declined. Exit 0, ZERO network calls. Declining is not a failure; it is the prompt working. */
+export declare function detachDeclined(domain: string): string[];
+/**
+ * Already detached — a SILENT RESOLVE, not an error. The creator asked for a
+ * state the world is already in.
+ */
+export declare function detachAlready(domain: string): string[];
+/**
+ * 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 declare function detachNeedsConsent(domain: string): string[];
+/**
+ * `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 declare function noRenewVerb(): string[];
+export declare function unknownDomainSub(sub: string): string[];
+/** `vincentt domains` / `custom-domain` / `dns` — plausible verbs, answered. */
+export declare function domainVerbRedirect(typed: string): string[];