@vincentt-xr/cli 0.15.2 → 0.17.0

package/dist/domain/command.js

@@ -0,0 +1,467 @@
+// `vincentt domain <attach|list|verify|detach>` — Flows C1-C7.
+//
+// The IO boundary (print, config, binding, org, the four API calls, confirm) is
+// injected, so every branch is testable with no API, no HOME and no network.
+//
+// THE VERB SET, and the aliases:
+//   attach  (alias: add)     — claim a name and print the three records
+//   list                     — this workspace's domains, and the count
+//   verify                   — re-check now, and diagnose what is observed
+//   detach  (alias: remove)  — stop serving the name
+//
+// THE ALIASES ARE SILENT. `add` produces `attach`'s transcript and `remove`
+// produces `detach`'s, WITH NOTHING PRINTED ABOUT THE ALIAS — no "did you mean",
+// no deprecation notice, and no echo of the canonical name (D-45, CLI convention
+// 6). f2's *a warning about a decision already taken reports it; it does not ask*
+// has a quieter cousin here: THERE IS NO DECISION TO REPORT. The creator got what
+// they wanted, and a correction on a working command is the product being
+// pedantic about its own vocabulary at the one moment the creator is not
+// interested in it. Help, docs and every error string say `attach` / `detach`,
+// which is where the vocabulary is actually taught.
+import { EXIT } from "../lib/exitCodes.js";
+import { VALIDATION_RECORD_GONE } from "./wire.js";
+import { DomainApiError } from "./api.js";
+import { localRefusal, normalizeArgument } from "./hostname.js";
+import * as copy from "./copy.js";
+/** The canonical subcommands. */
+export const DOMAIN_SUBCOMMANDS = ["attach", "list", "verify", "detach"];
+/**
+ * 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 const DOMAIN_ALIASES = {
+    add: "attach",
+    remove: "detach",
+};
+/**
+ * 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 function resolveSub(typed) {
+    if (typed === undefined)
+        return undefined;
+    if (DOMAIN_SUBCOMMANDS.includes(typed)) {
+        return typed;
+    }
+    return DOMAIN_ALIASES[typed];
+}
+const NOT_SIGNED_IN = [
+    "",
+    "✗ You're not signed in.",
+    "",
+    "  Attaching a domain needs an account.",
+    "",
+    "  Sign in:  vincentt login",
+    "",
+];
+const NO_PROJECT = [
+    "",
+    "✗ This folder isn't linked to a project.",
+    "",
+    "  A custom domain attaches to one published project.",
+    "",
+    "  Link it:  vincentt link <project-id>",
+    "  Or list your projects:  vincentt projects",
+    "",
+];
+/**
+ * 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 async function domainCommand(deps, sub, opts = {}) {
+    const cfg = await deps.config();
+    if (!cfg) {
+        // A platform call needed an account and the command did not answer for it.
+        // The NAMED constant, never the literal — B-F12-1 is enforceable only when
+        // the code is a symbol a reader can follow to its meaning.
+        for (const l of NOT_SIGNED_IN)
+            deps.print(l);
+        return EXIT.NOT_AUTHENTICATED;
+    }
+    switch (sub) {
+        case "attach":
+            return attachVerb(deps, cfg, opts);
+        case "list":
+            return listVerb(deps, cfg, opts);
+        case "verify":
+            return verifyVerb(deps, cfg, opts);
+        case "detach":
+            return detachVerb(deps, cfg, opts);
+    }
+}
+/** The hostname argument is required on three of the four verbs. */
+function requireHostname(deps, opts, verb) {
+    const raw = opts.hostname;
+    if (!raw) {
+        deps.print("");
+        deps.print(`✗ Which domain? \`vincentt domain ${verb} <domain>\``);
+        deps.print("");
+        return undefined;
+    }
+    return normalizeArgument(raw);
+}
+/**
+ * Flow C1 — attach.
+ *
+ * NO PROMPT anywhere: attaching asks nothing irreversible.
+ *
+ * The two local refusals fire with NO NETWORK CALL, because their copy is a fact
+ * about the creator's own registrar rather than about our state. Everything else
+ * is the server's judgement.
+ */
+async function attachVerb(deps, cfg, opts) {
+    const hostname = requireHostname(deps, opts, "attach");
+    if (hostname === undefined)
+        return 1;
+    const refusal = localRefusal(hostname);
+    if (refusal === "platform_host") {
+        for (const l of copy.refusedPlatformHost())
+            deps.print(l);
+        return 1;
+    }
+    if (refusal === "root_domain") {
+        for (const l of copy.refusedRootDomain(hostname))
+            deps.print(l);
+        return 1;
+    }
+    if (refusal === "empty") {
+        for (const l of copy.refusedRootDomain(""))
+            deps.print(l);
+        return 1;
+    }
+    const binding = await deps.binding();
+    if (!binding) {
+        for (const l of NO_PROJECT)
+            deps.print(l);
+        return 1;
+    }
+    let result;
+    try {
+        result = await deps.attach(cfg, binding.projectId, hostname);
+    }
+    catch (err) {
+        return printAttachError(deps, err, hostname);
+    }
+    if (opts.json) {
+        deps.print(JSON.stringify({ domain: result.domain }, null, 2));
+        return 0;
+    }
+    // EVERY rendered hostname comes from `result.domain.domain` — the normalized
+    // form the API returned — never from `hostname`, the value we sent. A client
+    // sending `AR.Acme.COM.` gets `ar.acme.com` back and MUST display what it got.
+    for (const l of copy.attachSuccess({
+        domain: result.domain.domain,
+        records: result.domain.records,
+        roles: result.roles,
+        permanentAddress: result.domain.permanentAddress,
+        projectName: result.domain.projectName,
+    })) {
+        deps.print(l);
+    }
+    return 0;
+}
+function printAttachError(deps, err, hostname) {
+    if (!(err instanceof DomainApiError)) {
+        deps.print("");
+        deps.print(`✗ Couldn't reach Vincentt to attach ${hostname}.`);
+        deps.print("");
+        deps.print(copy.NOTHING_WAS_CLAIMED);
+        deps.print("");
+        return 1;
+    }
+    // The refusals, each by the server's own code. The ceiling figure and the plan
+    // name come from the API — the CLI holds no plan ladder.
+    switch (err.code) {
+        case "domain_limit_reached":
+            for (const l of copy.refusedAtCeiling(err.detail.limit ?? 0))
+                deps.print(l);
+            return 1;
+        case "domain_taken":
+            // BYTE-IDENTICAL whether the holder is this workspace or a stranger. The
+            // CLI passes no holder information because the API sends none.
+            for (const l of copy.refusedAlreadyAttached(hostname))
+                deps.print(l);
+            return 1;
+        case "platform_hostname":
+            for (const l of copy.refusedPlatformHost())
+                deps.print(l);
+            return 1;
+        case "root_domain_unsupported":
+            for (const l of copy.refusedRootDomain(hostname))
+                deps.print(l);
+            return 1;
+        case "no_entitlement":
+            for (const l of copy.refusedNoEntitlement(err.detail.planName))
+                deps.print(l);
+            return 1;
+        default:
+            break;
+    }
+    if (err.status === 429) {
+        for (const l of copy.refusedTooSoon(err.retryAfterSec))
+            deps.print(l);
+        return 1;
+    }
+    deps.print("");
+    deps.print(`✗ ${err.message}`);
+    deps.print("");
+    deps.print(copy.NOTHING_WAS_CLAIMED);
+    deps.print("");
+    return 1;
+}
+/**
+ * Flow L43 — list. A listing verb REPORTS; it never asks and never picks.
+ *
+ * Reads the ORG route, not the project one: the count is against the workspace's
+ * entitlement and a creator checking whether they hold a name needs every one.
+ */
+async function listVerb(deps, cfg, opts) {
+    const org = await deps.org();
+    if (!org.ok) {
+        deps.print(org.message);
+        return 1;
+    }
+    let view;
+    try {
+        view = await deps.listOrg(cfg, org.org.slug);
+    }
+    catch (err) {
+        deps.print("");
+        deps.print(err instanceof DomainApiError
+            ? `✗ ${err.message}`
+            : "✗ Couldn't reach Vincentt to list domains.");
+        deps.print("");
+        return 1;
+    }
+    if (opts.json) {
+        deps.print(JSON.stringify(view, null, 2));
+        return 0;
+    }
+    if (view.domains.length === 0) {
+        for (const l of copy.listEmpty(view.planName))
+            deps.print(l);
+        return 0;
+    }
+    deps.print("");
+    for (const l of copy.listRows(view.domains))
+        deps.print(l);
+    deps.print("");
+    for (const l of copy.entitlementLine(view.count ?? view.domains.length, view.limit, view.planName)) {
+        deps.print(l);
+    }
+    deps.print("");
+    deps.print("  vincentt domain verify <domain>   to check one now");
+    deps.print("");
+    return 0;
+}
+/**
+ * Flow C2 — verify, and the diagnosis that is the differentiation.
+ *
+ * THE EXIT CODE FOLLOWS THE GLYPH, NOT THE COUNT. The mapping is
+ * `exitCodeForFindings`, called on the findings alone, from one place — so a
+ * report of ten advisories exits 0 and a report of one blocking finding exits 1.
+ */
+async function verifyVerb(deps, cfg, opts) {
+    const hostname = requireHostname(deps, opts, "verify");
+    if (hostname === undefined)
+        return 1;
+    const binding = await deps.binding();
+    if (!binding) {
+        for (const l of NO_PROJECT)
+            deps.print(l);
+        return 1;
+    }
+    deps.print("");
+    deps.print(copy.verifyReading(hostname));
+    let result;
+    try {
+        result = await deps.verify(cfg, binding.projectId, hostname);
+    }
+    catch (err) {
+        if (err instanceof DomainApiError && err.status === 404) {
+            for (const l of copy.notAttached(hostname))
+                deps.print(l);
+            return 1;
+        }
+        if (err instanceof DomainApiError && err.status === 429) {
+            for (const l of copy.refusedTooSoon(err.retryAfterSec))
+                deps.print(l);
+            return 1;
+        }
+        deps.print("");
+        deps.print(err instanceof DomainApiError
+            ? `✗ ${err.message}`
+            : `✗ Couldn't reach Vincentt to check ${hostname}.`);
+        deps.print("");
+        deps.print(copy.NOTHING_WAS_CHANGED);
+        deps.print("");
+        return 1;
+    }
+    const view = result.domain;
+    if (opts.json) {
+        deps.print(JSON.stringify({ domain: view }, null, 2));
+        return copy.exitCodeForFindings(view.findings);
+    }
+    return renderVerify(deps, view, result.roles);
+}
+/**
+ * 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 function renderVerify(deps, view, roles) {
+    // cert_failed is a STATE, not an error: it is customer-actionable, and the
+    // domain is proven theirs. It names a different actor than any other state.
+    if (view.state === "cert_failed") {
+        for (const l of copy.verifyCertFailed(view.domain, view.findings, view.permanentAddress)) {
+            deps.print(l);
+        }
+        return 1;
+    }
+    // `failing` gets its OWN arm, before the serving one, because the serving copy
+    // is false here: it opens by confirming the TXT record matches, which sat
+    // directly above "we can't find the TXT record". A failing domain is serving on
+    // a record we can no longer see, so nothing about its DNS is confirmed — and
+    // the record values are re-printed, which QA-F16-C1 requires for this state.
+    if (view.state === "failing") {
+        for (const l of copy.verifyFailing(view.domain, view.findings, view.holdsAt, view.permanentAddress)) {
+            deps.print(l);
+        }
+        if (view.records.length > 0) {
+            for (const l of copy.allRecordBlocks(view.records, view.domain, roles)) {
+                deps.print(l);
+            }
+        }
+        // Still serving, but the creator must act: a non-zero exit is what tells an
+        // agent this needs attention while the address is still up.
+        return 1;
+    }
+    const serving = view.state === "live";
+    if (serving && view.findings.length > 0) {
+        // Serving WITH findings. When they are all advisory this EXITS 0 — the
+        // D-44 case, and QA-F16-C2's assertion. The record block is re-printed only
+        // when the certificate validation record is the missing one, because that
+        // state's entire cause is a record the creator tidied away.
+        const certGone = view.findings.some((f) => f.code === VALIDATION_RECORD_GONE);
+        const reprint = certGone ? certRecords(view, roles) : { records: [], roles: [] };
+        for (const l of copy.verifyServingWithAdvisories(view.domain, view.findings, reprint.records, reprint.roles)) {
+            deps.print(l);
+        }
+        // THE GLYPH, NOT THE COUNT. All-advisory ⇒ 0, however many there are.
+        return copy.exitCodeForFindings(view.findings);
+    }
+    if (serving) {
+        for (const l of copy.verifyLive(view.domain, view.permanentAddress, undefined)) {
+            deps.print(l);
+        }
+        return 0;
+    }
+    // Not serving: pending, verified, held, detached, or an unknown state.
+    //
+    // THE EXIT CODE HERE IS 1, and it is NOT the findings mapping. That mapping
+    // answers "do the observed findings block?"; this arm answers "is the domain
+    // serving?", and the answer is no. A `pending` domain with zero findings — the
+    // records simply have not propagated yet — is not ready, and an agent that read
+    // exit 0 there would move on to sharing an address that does not resolve.
+    //
+    // The all-advisory exit-0 rule (QA-F16-C2) governs a report about a SERVING
+    // domain, which is the arm above. Applying the glyph mapping here would make a
+    // domain that has never resolved exit 0 whenever its only finding is a proxy
+    // observation, which is the opposite of what the creator needs to know.
+    for (const l of copy.verifyNotReady(view.domain, view.findings, view.permanentAddress)) {
+        deps.print(l);
+    }
+    // The record values are re-printed for the states where a creator returns to
+    // re-read them (QA-F16-C1: pending, failing, held) — a creator whose brand is
+    // dark should not have to navigate to find the values again.
+    if (needsRecordsReprinted(view) && view.records.length > 0) {
+        for (const l of copy.allRecordBlocks(view.records, view.domain, roles)) {
+            deps.print(l);
+        }
+    }
+    return 1;
+}
+/** The certificate record alone, for the D-44 re-print. */
+function certRecords(view, roles) {
+    const records = [];
+    const outRoles = [];
+    view.records.forEach((r, i) => {
+        if (roles[i] === "certificate") {
+            records.push(r);
+            outRoles.push(roles[i]);
+        }
+    });
+    return { records, roles: outRoles };
+}
+/**
+ * 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 function needsRecordsReprinted(view) {
+    return view.state === "pending" || view.state === "failing" || view.state === "held";
+}
+/**
+ * Flow C7 — detach.
+ *
+ * `[y/N]`. The default tracks whether an accidental Enter would be EXPENSIVE, of
+ * which irreversibility is one cause and IMMEDIATE PUBLIC VISIBILITY is another.
+ * Detaching is fully reversible and still takes a client's advertised address
+ * dark mid-campaign.
+ *
+ * DECLINING IS EXIT 0 WITH ZERO NETWORK CALLS beyond the reads already made.
+ * Declining is not a failure; it is the prompt working.
+ */
+async function detachVerb(deps, cfg, opts) {
+    const hostname = requireHostname(deps, opts, "detach");
+    if (hostname === undefined)
+        return 1;
+    const binding = await deps.binding();
+    if (!binding) {
+        for (const l of NO_PROJECT)
+            deps.print(l);
+        return 1;
+    }
+    // A non-TTY with no explicit flag REFUSES. A pipe cannot consent, and assuming
+    // yes on a public-visibility act is the failure the convention exists to stop.
+    if (!deps.isTTY && !opts.yes) {
+        for (const l of copy.detachNeedsConsent(hostname))
+            deps.print(l);
+        return 1;
+    }
+    if (!opts.yes) {
+        for (const l of copy.detachDisclosure(hostname, undefined))
+            deps.print(l);
+        const ok = await deps.confirm(copy.detachPrompt(hostname), false);
+        if (!ok) {
+            for (const l of copy.detachDeclined(hostname))
+                deps.print(l);
+            return 0;
+        }
+    }
+    try {
+        await deps.detach(cfg, binding.projectId, hostname);
+    }
+    catch (err) {
+        deps.print("");
+        deps.print(err instanceof DomainApiError
+            ? `✗ ${err.message}`
+            : `✗ Couldn't reach Vincentt to detach ${hostname}.`);
+        deps.print("");
+        deps.print(copy.NOTHING_WAS_CHANGED);
+        deps.print("");
+        return 1;
+    }
+    for (const l of copy.detachDone(hostname))
+        deps.print(l);
+    return 0;
+}