ninepm 0.83.0 → 0.87.0

package/dist/index.js

@@ -8,9 +8,10 @@ import path from "node:path";
 import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, openAsBlob, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { once } from "node:events";
-import { createGzip, gzipSync } from "node:zlib";
+import { createGzip, deflateSync, gzipSync } from "node:zlib";
 import { Agent, fetch as undiciFetch } from "undici";
 import { MAX_DEPLOY_DESCRIPTION_LENGTH, normalizeDeployDescription } from "./deploy-description.js";
+import { qrMatrix, qrMinimumWidthMm, qrSvg, qrTerminal } from "./qr-code.js";
 import { managedHostnamesIn, siblingCallWarning, siblingsOf } from "./sibling-hostnames.js";
 import { MAX_STATIC_ASSET_FILE_BYTES, MAX_WORKER_ENTRY_COMPRESSED_BYTES, MAX_WORKER_SCRIPT_COMPRESSED_BYTES, WORKER_ENTRY_COMPRESSED_WARN_BYTES, assetFileTooLargeMessage, formatMebibytes, formatMegabytes, oversizedAssets, workerBundleNearLimitMessage, workerBundleTooLargeMessage, workerEntryNearLimitMessage, workerEntryTooLargeMessage, } from "./deploy-limits.js";
 import { guessZoneApex, relativeRecordName, zoneApexFor } from "./dns-host.js";
@@ -56,7 +57,7 @@ export function deployDatabaseClause(databases) {
 // says each removed one used, under the same value-conditional rule as `domains remove`, and the
 // ones still being released, which get no deletion advice. Never throws: the delete has already
 // happened, so a malformed entry costs that entry's advice, not the command.
-export function deletedDomainLines(deleted) {
+export function deletedDomainLines(deleted, options = {}) {
     const lines = [];
     try {
         const releasing = Array.isArray(deleted.customDomainsReleasing)
@@ -70,15 +71,26 @@ export function deletedDomainLines(deleted) {
             lines.push(...domainCleanupLines(cleanup));
         }
         for (const hostname of releasing) {
-            lines.push(`${hostname} has stopped serving, but removing it upstream is still finishing; it finishes on its own. ${DOMAIN_RELEASE_NO_CLEANUP}`);
+            lines.push(`${hostname} has stopped serving, but removing it upstream is still finishing; it finishes on its own. ${releaseNoCleanupLine(options)}`);
+        }
+        // The consequence is said for the domains whose removal finished; one still releasing is
+        // told to leave its records alone, which repointing them would contradict.
+        const finished = [];
+        const names = Array.isArray(deleted.customDomainNames) ? deleted.customDomainNames : [];
+        for (const hostname of [...names, ...cleanups.map((cleanup) => cleanup?.hostname)]) {
+            if (typeof hostname !== "string" || hostname === "" || releasing.includes(hostname) || finished.includes(hostname))
+                continue;
+            finished.push(hostname);
         }
+        if (finished.length > 0)
+            lines.push(...domainRemovedConsequenceLines(finished, options));
     }
     catch {
         return lines;
     }
     return lines;
 }
-export const CLI_VERSION = "0.83.0";
+export const CLI_VERSION = "0.87.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -2707,6 +2719,9 @@ export function parseArgs(argv) {
     if (command === "domains") {
         return parseDomainsArgs(argv.slice(1));
     }
+    if (command === "qr") {
+        return parseQrArgs(argv.slice(1));
+    }
     if (command === "logs") {
         return parseLogsArgs(argv.slice(1));
     }
@@ -2981,7 +2996,7 @@ function parseDeleteArgs(argv) {
     if (!confirmSlug) {
         throw new Error("Missing delete confirmation. Pass --confirm <slug> matching the app slug.");
     }
-    return { kind: "delete", ...base, site, confirmSlug };
+    return { kind: "delete", ...base, apiUrlFrom: apiUrlSource(flags), site, confirmSlug };
 }
 function parseFilesArgs(argv) {
     const subcommand = argv[0];
@@ -3871,20 +3886,161 @@ export function setupCleanupLines(hostname, records) {
         "If one of these names now holds a different value, that record is not ours: leave it. Keep the record that points the domain at 9pm.",
     ];
 }
-// Said wherever a removal is left to finish in the background: only the API's own cleanup may
-// name records to delete, and a removal that finishes there produces none.
-const DOMAIN_RELEASE_NO_CLEANUP = "Leave its DNS records in place for now. The CLI cannot list which DNS records to delete for a removal that finishes in the background.";
+// The public guide's section on moving a domain off 9pm, on the site beside the control plane
+// this command talked to, so a staging run links staging's copy of the guide.
+export function customDomainMoveOffGuideUrl(options = {}) {
+    const dashboard = options.target ? dashboardUrlForApiUrl(options.target.apiUrl) : PUBLIC_DASHBOARD_URL;
+    return `${dashboard.replace(/\/dashboard$/, "")}/docs/custom-domains#move-off`;
+}
+// Said once a removal has finished (#2089): 9pm no longer holds the hostname, so while DNS
+// still points here a visitor reaches nothing that can answer for it. Which error they see is
+// not ours to promise. It names no record: what may be deleted is only the cleanup list above
+// it, which carries its own value condition, so this adds no deletion advice of its own. The
+// order is the one the staging rehearsal demonstrated for a move to another host (#2182,
+// scenario 2). A move to the owner's own Cloudflare zone was not rehearsed, so it gets no order.
+export function domainRemovedConsequenceLines(hostnames, options = {}) {
+    const subject = hostnames.length === 1 ? hostnames[0] : hostnames.join(", ");
+    return [
+        `After removal, visitors may see a TLS or routing error while DNS for ${subject} still points at 9pm.`,
+        `Moving a domain to another host? Point its DNS at the new host, wait for the DNS TTL to pass, then remove the domain from 9pm. While caches update, some visitors may still reach 9pm, or briefly see an error from the new host until it is set up for the name. Once DNS points away, 9pm may show the domain as failed; that is expected, so remove it. Guide: ${customDomainMoveOffGuideUrl(options)}`,
+    ];
+}
+// The command that lists what a removal finished in the background frees (#2068), aimed at the
+// same account and control plane as the command that printed it. Never a token.
+function domainsRemovedCommand(options, hostname) {
+    const owner = options.owner ? ` --owner ${quoteSiteArg(options.owner)}` : "";
+    return `9pm domains removed${hostname ? ` --hostname ${hostname}` : ""}${owner}${apiUrlFlagFor(options.target)}`;
+}
+// Said wherever a removal is left to finish in the background: nothing is deletable until it
+// has finished, and only the API's own list may name what is then. The background path keeps
+// that list for the owner (#2068), so the line points at the command that reads it.
+function releaseNoCleanupLine(options) {
+    return `Leave its DNS records in place until the removal has finished. Once it has, this lists the ones you may delete: ${domainsRemovedCommand(options)}`;
+}
 // A removal that has stopped serving but is still finishing upstream: nothing is called removed
-// and no record is offered for deletion. A removal the background sweep finishes deletes the row
-// and returns no cleanup to anyone, so no later command is promised to list the records either.
+// and no record is offered for deletion here.
 export function domainRemovalPendingLines(hostname, app, options) {
     const owner = options.owner ? ` --owner ${quoteSiteArg(options.owner)}` : "";
     return [
         `${app} no longer serves ${hostname}, but removing it upstream is taking longer than usual. It finishes on its own.`,
         `Once ${hostname} is no longer in this list, it has stopped serving from 9pm: 9pm domains list ${quoteSiteArg(app)}${owner}${apiUrlFlagFor(options.target)}`,
-        DOMAIN_RELEASE_NO_CLEANUP,
+        releaseNoCleanupLine(options),
     ];
 }
+// The server asks the certificate provider about at most ten removals per page and returns a
+// `next` cursor while more remain; this reads the pages in turn, up to this many, and merges
+// them. An older server sends no cursor, so its one page is the whole answer.
+export const FINISHED_REMOVAL_PAGES_PER_COMMAND = 20;
+export async function getFinishedDomainRemovals(options) {
+    const hostname = options.hostname ? normalizeDomainArg(options.hostname) : null;
+    let merged = null;
+    let after = null;
+    for (let page = 0; page < FINISHED_REMOVAL_PAGES_PER_COMMAND; page += 1) {
+        const query = new URLSearchParams();
+        if (options.owner)
+            query.set("owner", options.owner);
+        if (hostname)
+            query.set("hostname", hostname);
+        if (after)
+            query.set("after", after);
+        const body = await domainsRequest(options, `/v1/domains/finished-removals${query.size > 0 ? `?${query}` : ""}`);
+        const fields = body && typeof body === "object" ? body : null;
+        // Not a list at all: handed on as it came, so the printer says it couldn't read it.
+        if (!fields || !Array.isArray(fields.removals))
+            return merged ?? body;
+        const unchecked = Array.isArray(fields.unchecked) ? fields.unchecked : [];
+        const previous = merged;
+        merged = previous
+            ? { ...previous, removals: [...previous.removals, ...fields.removals], unchecked: [...previous.unchecked, ...unchecked] }
+            : { ...fields, removals: [...fields.removals], unchecked: [...unchecked] };
+        const next = !hostname && typeof fields.next === "string" && fields.next !== "" ? fields.next : null;
+        merged.next = next;
+        if (!next)
+            break;
+        after = next;
+    }
+    // An older server ignores `hostname` and answers with every removal; keep only the one asked.
+    if (merged && hostname) {
+        const named = (entry) => {
+            const fields = entry && typeof entry === "object" ? entry : null;
+            return typeof fields?.hostname === "string" && normalizeDomainArg(fields.hostname) === hostname;
+        };
+        merged = { ...merged, removals: merged.removals.filter(named), unchecked: merged.unchecked.filter(named) };
+    }
+    return merged;
+}
+// The server's `removals`, kept only as far as each entry is well formed: an entry without a
+// readable cleanup list is dropped, never guessed at, and a body without a list is null.
+export function parseFinishedDomainRemovals(body) {
+    try {
+        const removals = body && typeof body === "object" ? body.removals : null;
+        if (!Array.isArray(removals))
+            return null;
+        const kept = [];
+        for (const entry of removals) {
+            if (!entry || typeof entry !== "object")
+                continue;
+            const fields = entry;
+            const cleanup = parseDomainCleanup(fields.cleanup);
+            if (!cleanup || cleanup.records.length === 0)
+                continue;
+            const finishedAt = typeof fields.finishedAt === "string" && Number.isFinite(Date.parse(fields.finishedAt)) ? fields.finishedAt : null;
+            kept.push({ hostname: cleanup.hostname, finishedAt, cleanup });
+        }
+        return kept;
+    }
+    catch {
+        return null;
+    }
+}
+// The hostnames the server withheld because it could not check them; anything malformed is
+// dropped, since it names nothing to delete either way.
+function uncheckedFinishedRemovals(value) {
+    if (!Array.isArray(value))
+        return [];
+    const hostnames = [];
+    for (const entry of value) {
+        const hostname = entry && typeof entry === "object" ? entry.hostname : null;
+        if (typeof hostname === "string" && hostname !== "" && !hostnames.includes(hostname))
+            hostnames.push(hostname);
+    }
+    return hostnames;
+}
+// What `9pm domains removed` prints. Never throws, and never calls anything deletable that the
+// server did not list: an unreadable answer says so rather than reading as "nothing to delete".
+export function finishedDomainRemovalLines(body, options = {}) {
+    try {
+        const removals = parseFinishedDomainRemovals(body);
+        if (removals === null)
+            return ["Couldn't read which DNS records removed domains left behind, so none is listed for deletion."];
+        const fields = body;
+        const days = typeof fields.retentionDays === "number" && Number.isInteger(fields.retentionDays) && fields.retentionDays > 0 ? fields.retentionDays : null;
+        const window = days ? ` in the last ${days} days` : "";
+        const unchecked = uncheckedFinishedRemovals(fields.unchecked);
+        if (removals.length === 0 && unchecked.length === 0) {
+            return [`No domain removal that finished in the background${window} has DNS records to list.`];
+        }
+        const lines = [];
+        for (const removal of removals) {
+            lines.push(removal.finishedAt ? `Removing ${removal.hostname} finished at ${removal.finishedAt}.` : `Removing ${removal.hostname} has finished.`);
+            lines.push(...domainCleanupLines(removal.cleanup));
+        }
+        // The server lists a removal only after checking the shared provider holds no hostname for
+        // it (another environment may have added it again); one it could not check is withheld.
+        for (const hostname of unchecked) {
+            lines.push(`Couldn't check whether ${hostname} has been connected again elsewhere, so its records aren't listed. Leave them in place and run this again in a minute: ${domainsRemovedCommand(options, hostname)}`);
+        }
+        // More pages than one run reads: say so rather than let the list look complete.
+        if (typeof fields.next === "string" && fields.next !== "") {
+            lines.push(`There are more removals than one run lists. Ask about one domain at a time: ${domainsRemovedCommand(options, "<hostname>")}`);
+        }
+        lines.push(`A removal is listed here${days ? ` for ${days} days after it finishes` : " for a limited time after it finishes"}, and not at all once its domain is added again.`);
+        return lines;
+    }
+    catch {
+        return ["Couldn't read which DNS records removed domains left behind, so none is listed for deletion."];
+    }
+}
 export async function moveDomain(options) {
     const hostname = normalizeDomainArg(options.hostname);
     const body = await domainsRequest(options, siteDomainsRoute(options, hostname, "move"), {
@@ -4082,7 +4238,7 @@ export async function waitForDomain(options) {
         await sleepFn(Math.min(options.intervalMs, remaining));
     }
 }
-const DOMAINS_VALUE_FLAGS = new Set(["token", "api-url", "owner", "timeout", "interval", "confirm", "to"]);
+const DOMAINS_VALUE_FLAGS = new Set(["token", "api-url", "owner", "timeout", "interval", "confirm", "to", "hostname"]);
 const DOMAINS_BOOLEAN_FLAGS = new Set(["json"]);
 function domainsPositionals(argv) {
     const positionals = [];
@@ -4111,6 +4267,7 @@ const DOMAINS_USAGE = {
     cleanup: "9pm domains cleanup <app> <hostname> [--owner <organisation>] [--json]  (setup records a live domain no longer needs)",
     remove: "9pm domains remove <app> <hostname> --confirm <hostname> [--owner <organisation>] [--json]",
     move: "9pm domains move [<app>] <hostname> --to <app> [--owner <organisation>] [--json]",
+    removed: "9pm domains removed [--hostname <hostname>] [--owner <organisation>] [--json]  (DNS records you may delete after a removal that finished in the background)",
 };
 function parseDomainsArgs(argv) {
     const subcommand = argv[0] === "ls" ? "list" : argv[0] === "rm" ? "remove" : argv[0];
@@ -4138,6 +4295,12 @@ function parseDomainsArgs(argv) {
         const site = positionals[0];
         return withBase({ kind: "list", json, ...(site ? { site } : {}) });
     }
+    if (subcommand === "removed") {
+        if (positionals.length > 0)
+            throw new Error(`Usage: ${usage}`);
+        const hostname = readStringFlag(flags, "hostname");
+        return withBase({ kind: "removed", json, ...(hostname ? { hostname } : {}) });
+    }
     if (subcommand === "move") {
         const to = readStringFlag(flags, "to");
         const [first, second] = positionals;
@@ -4208,6 +4371,28 @@ async function runDomainsCommand(command) {
         await runDomainMove(action, base, format);
         return;
     }
+    if (action.kind === "removed") {
+        let body;
+        try {
+            body = await getFinishedDomainRemovals({ ...base, ...(action.hostname ? { hostname: action.hostname } : {}) });
+        }
+        catch (error) {
+            // A server from before #2068 has no such route; it keeps no list, so none is printed.
+            if (error instanceof DomainsApiError && error.status === 404 && error.code === "not_found") {
+                console.error("This server can't list the DNS records of removals that finished in the background yet, so none is listed. Leave the records in place.");
+                process.exitCode = 1;
+                return;
+            }
+            throw error;
+        }
+        if (action.json) {
+            console.log(JSON.stringify(body, null, 2));
+            return;
+        }
+        for (const line of finishedDomainRemovalLines(body, format))
+            console.log(line);
+        return;
+    }
     const target = { ...base, site: action.site, hostname: action.hostname };
     if (action.kind === "add") {
         const added = await addDomain(target);
@@ -4311,6 +4496,8 @@ async function runDomainsCommand(command) {
         for (const line of domainCleanupLines(removal.cleanup))
             console.log(line);
     }
+    for (const line of domainRemovedConsequenceLines([removal.hostname], format))
+        console.log(line);
 }
 async function runDomainMove(action, base, format) {
     const hostname = normalizeDomainArg(action.hostname);
@@ -4470,6 +4657,208 @@ async function runLogsCommand(command) {
         ? "No detailed logs were captured for this failure."
         : "No logs recorded. Logs are captured when a deployment fails to come up.");
 }
+// `9pm qr` (#2160, _specs/app-qr-codes.md): a printable QR code for an app's address. The
+// control plane decides which addresses the code may encode (GET /v1/sites/:id/qr); this
+// only draws one of them, with the settings the dashboard uses (../shared/qr-code.ts).
+const QR_USAGE = "9pm qr <app> [--owner <organisation>] [--address <host>] [--format svg|png] [--out <file>] [--terminal] [--json]";
+const QR_VALUE_FLAGS = new Set(["owner", "address", "format", "out", "api-url", "token"]);
+const QR_BOOLEAN_FLAGS = new Set(["terminal", "json"]);
+// Pixels per module in the PNG: 16 keeps the typical code (37 modules with its border) near
+// 600 dpi at the 25 mm minimum print width. The dashboard's download uses the same figure.
+export const QR_PNG_PIXELS_PER_MODULE = 16;
+/**
+ * The minimum width in centimetres, rounded UP to the millimetre: it is a floor, so rounding
+ * to nearest would print a 26.5 mm minimum as "2.6 cm", below what the code needs.
+ */
+export function qrMinimumWidthCmText(minimumWidthMm) {
+    return String(Math.ceil(minimumWidthMm) / 10);
+}
+export const QR_ACCESS_NOTE = "This app is private. Scanning the code doesn't grant access: people still have to sign in and be allowed in.";
+export function qrCustomDomainNote(hostname) {
+    return `This code opens ${hostname}. If that domain later moves to another app or is removed, printed codes follow the domain, not this app.`;
+}
+const QR_UNAVAILABLE_MESSAGES = {
+    not_published: "There's no QR code yet: one appears after the app's first successful deploy.",
+    disabled: "This app is disabled, so there is no QR code to share.",
+    service_access: "This app only accepts service credentials, which a phone camera can't present, so there is no QR code.",
+};
+function parseQrArgs(argv) {
+    if (argv[0] === "help" || argv[0] === "--help")
+        throw new UsageError();
+    const flags = parseFlags(argv);
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index] ?? "";
+        if (!arg.startsWith("--")) {
+            positionals.push(arg);
+            continue;
+        }
+        const name = arg.slice(2);
+        if (!QR_VALUE_FLAGS.has(name) && !QR_BOOLEAN_FLAGS.has(name))
+            throw new Error(`Unknown flag for 9pm qr: --${name}`);
+        if (QR_VALUE_FLAGS.has(name))
+            index += 1;
+    }
+    // A value flag given without a value would otherwise fall back to its default, which for
+    // --owner silently picks the personal account's app instead of the organisation's.
+    for (const name of QR_VALUE_FLAGS) {
+        if (flags.has(name) && !readStringFlag(flags, name))
+            throw new Error(`--${name} needs a value.`);
+    }
+    const [site] = positionals;
+    if (!site || positionals.length > 1)
+        throw new Error(`Usage: ${QR_USAGE}`);
+    const format = readStringFlag(flags, "format") ?? "svg";
+    if (format !== "svg" && format !== "png")
+        throw new Error("--format must be svg or png.");
+    const owner = readStringFlag(flags, "owner");
+    const address = readStringFlag(flags, "address");
+    const out = readStringFlag(flags, "out");
+    return {
+        kind: "qr",
+        ...readBaseApiOptions(flags),
+        site,
+        format,
+        terminal: flags.has("terminal"),
+        json: flags.has("json"),
+        ...(owner ? { owner } : {}),
+        ...(address ? { address } : {}),
+        ...(out ? { out } : {}),
+    };
+}
+/**
+ * The returned address `--address` names, or an error listing the valid ones. The value is
+ * normalized first - a bare hostname gets `https://`, case is ignored, a trailing `/` is
+ * allowed - and must then match an address the server offered: no other host, path, query,
+ * fragment, credentials, port or scheme. The CLI never encodes a URL the server did not offer.
+ */
+export function pickQrAddress(addresses, requested) {
+    const fallback = addresses.find((address) => address.isDefault) ?? addresses[0];
+    if (!fallback)
+        throw new Error("The server offered no address for this app's QR code.");
+    if (requested === undefined)
+        return fallback;
+    const valid = addresses.map((address) => address.hostname).join(", ");
+    const refuse = (why) => {
+        throw new Error(`${why} Use one of: ${valid}.`);
+    };
+    const raw = requested.trim();
+    const withScheme = /^[a-z][a-z0-9+.-]*:/i.test(raw) ? raw : `https://${raw}`;
+    let parsed;
+    try {
+        parsed = new URL(withScheme);
+    }
+    catch {
+        return refuse(`--address ${requested} is not a hostname or URL.`);
+    }
+    if (parsed.protocol !== "https:")
+        return refuse(`--address must be an https address.`);
+    if (parsed.username || parsed.password || parsed.port)
+        return refuse(`--address must be a plain hostname.`);
+    if ((parsed.pathname !== "/" && parsed.pathname !== "") || parsed.search || parsed.hash) {
+        return refuse(`--address must be a hostname, with no path, query or fragment.`);
+    }
+    const match = addresses.find((address) => address.hostname.toLowerCase() === parsed.hostname.toLowerCase());
+    return match ?? refuse(`${parsed.hostname} is not an address of this app.`);
+}
+// CRC-32 as PNG chunks use it (ISO 3309 polynomial, reflected).
+const PNG_CRC_TABLE = (() => {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n += 1) {
+        let c = n;
+        for (let k = 0; k < 8; k += 1)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        table[n] = c >>> 0;
+    }
+    return table;
+})();
+function pngChunk(type, data) {
+    const typed = Buffer.concat([Buffer.from(type, "ascii"), data]);
+    let crc = 0xffffffff;
+    for (const byte of typed)
+        crc = (PNG_CRC_TABLE[(crc ^ byte) & 0xff] ?? 0) ^ (crc >>> 8);
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(data.length);
+    const checksum = Buffer.alloc(4);
+    checksum.writeUInt32BE((crc ^ 0xffffffff) >>> 0);
+    return Buffer.concat([length, typed, checksum]);
+}
+/** An 8-bit greyscale PNG of a module matrix (quiet zone included), black on white. */
+export function encodeQrPng(modules, scale = QR_PNG_PIXELS_PER_MODULE) {
+    const side = modules.length * scale;
+    const header = Buffer.alloc(13);
+    header.writeUInt32BE(side, 0);
+    header.writeUInt32BE(side, 4);
+    header[8] = 8; // bit depth
+    header[9] = 0; // greyscale
+    const raw = Buffer.alloc(side * (side + 1), 0xff);
+    for (let y = 0; y < side; y += 1) {
+        const rowStart = y * (side + 1);
+        raw[rowStart] = 0; // filter: none
+        const moduleRow = modules[Math.floor(y / scale)] ?? [];
+        for (let x = 0; x < side; x += 1) {
+            if (moduleRow[Math.floor(x / scale)])
+                raw[rowStart + 1 + x] = 0;
+        }
+    }
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        pngChunk("IHDR", header),
+        pngChunk("IDAT", deflateSync(raw)),
+        pngChunk("IEND", Buffer.alloc(0)),
+    ]);
+}
+function qrFileStem(site) {
+    return site.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "app";
+}
+async function runQrCommand(command) {
+    const route = `/v1/sites/${encodeURIComponent(command.site)}/qr${ownerQuery(command.owner)}`;
+    let qr;
+    try {
+        qr = await domainsRequest({ apiUrl: command.apiUrl, token: command.token }, route);
+    }
+    catch (error) {
+        if (error instanceof DomainsApiError && error.status === 404 && error.code === "not_found") {
+            console.error("This server can't make QR codes yet.");
+            process.exitCode = 1;
+            return;
+        }
+        if (error instanceof DomainsApiError && error.status === 404 && (error.code === "project_not_found" || error.code === "organisation_not_found")) {
+            console.error(`App not found: ${command.site}. Check the name, or pass --owner <organisation> for an organisation's app.`);
+            process.exitCode = 1;
+            return;
+        }
+        throw error;
+    }
+    if (!qr.available) {
+        console.error(QR_UNAVAILABLE_MESSAGES[qr.reason] ?? `There is no QR code for this app (${qr.reason}).`);
+        process.exitCode = 1;
+        return;
+    }
+    const address = pickQrAddress(qr.addresses, command.address);
+    const file = command.out ?? `${qrFileStem(command.site)}-qr.${command.format}`;
+    const bytes = command.format === "svg" ? qrSvg(address.url) : encodeQrPng(qrMatrix(address.url).modules);
+    writeFileSync(file, bytes);
+    const minimumWidthMm = qrMinimumWidthMm(address.url);
+    const accessNote = qr.accessMode === "private_otp" || qr.accessMode === "private_idp" ? QR_ACCESS_NOTE : null;
+    const customDomainNote = address.kind === "custom_domain" ? qrCustomDomainNote(address.hostname) : null;
+    if (command.json) {
+        console.log(JSON.stringify({ url: address.url, hostname: address.hostname, kind: address.kind, file, format: command.format, minimumWidthMm, accessMode: qr.accessMode, accessNote, customDomainNote }, null, 2));
+        return;
+    }
+    console.log(`Saved ${file}`);
+    console.log(`It opens ${address.url}`);
+    console.log(`Print it at least ${qrMinimumWidthCmText(minimumWidthMm)} cm wide, and larger if people will scan it from further away.`);
+    if (customDomainNote)
+        console.log(customDomainNote);
+    if (accessNote)
+        console.log(accessNote);
+    if (command.terminal) {
+        console.log("");
+        for (const line of qrTerminal(address.url))
+            console.log(line);
+    }
+}
 function parseLogsArgs(argv) {
     const site = argv[0];
     if (!site || site.startsWith("--")) {
@@ -5970,7 +6359,7 @@ async function main() {
             if (deleted.customDomainNames && deleted.customDomainNames.length > 0) {
                 console.log(`Removed custom domain(s): ${deleted.customDomainNames.join(", ")}.`);
             }
-            for (const line of deletedDomainLines(deleted))
+            for (const line of deletedDomainLines(deleted, { target: { apiUrl: command.apiUrl, apiUrlFrom: command.apiUrlFrom ?? "default" } }))
                 console.log(line);
             // #722: a partial external-cleanup failure never fails the delete, and used to be
             // silently discarded here — visible only in the raw JSON, if a caller happened to
@@ -6020,6 +6409,10 @@ async function main() {
             await runDomainsCommand(command);
             return;
         }
+        if (command.kind === "qr") {
+            await runQrCommand(command);
+            return;
+        }
         if (command.kind === "logs") {
             await runLogsCommand(command);
             return;
@@ -6364,6 +6757,8 @@ function printUsage() {
   9pm deployments ls <app> [--json]
   9pm deployments rm <deployment-id>
   9pm logs <app> [--lines <n>] [--json]
+  9pm qr <app> [--owner <organisation>] [--address <host>] [--format svg|png] [--out <file>] [--terminal] [--json]
+                                                 save a printable QR code for the app's address (SVG by default)
   9pm delete <site> --confirm <slug>
   9pm domains list [<app>] [--owner <organisation>] [--json]
   9pm domains add <app> <hostname> [--json]        connect a domain you own; prints the DNS records to publish
@@ -6374,6 +6769,7 @@ function printUsage() {
   9pm domains cleanup <app> <hostname> [--json]    on a live domain: setup records 9pm no longer needs, checked with the provider now
   9pm domains remove <app> <hostname> --confirm <hostname> [--json]   prints the DNS records you can then delete
   9pm domains move [<app>] <hostname> --to <app> [--json]           to another app of the same account; keeps its certificate and records
+  9pm domains removed [--hostname <h>] [--json]    DNS records you may delete after a removal that finished in the background
   9pm access show <site>
   9pm access public <site> [--switch-mode]
   9pm access otp <site> [--switch-mode]

package/dist/qr-code.d.ts

@@ -0,0 +1,48 @@
+/** White border on every side, in modules: the QR standard's required quiet zone. */
+export declare const QR_QUIET_ZONE_MODULES = 4;
+/** Smallest printed width we promise scans, border included (spec: release-gated by print tests). */
+export declare const QR_MIN_WIDTH_MM = 25;
+/**
+ * Our chosen product floor for one module, in millimetres - not a universal scanning
+ * threshold. The printed scan fixtures are what justify it; re-measure before changing it.
+ */
+export declare const QR_MIN_MODULE_MM = 0.5;
+export interface QrMatrix {
+    /** Modules per side INCLUDING the quiet zone. */
+    size: number;
+    /** Modules per side of the symbol alone. */
+    symbolSize: number;
+    /** `modules[y][x]`, true = dark, quiet zone included. */
+    modules: boolean[][];
+}
+export type ProjectQrUnavailableReason = "not_published" | "disabled" | "service_access";
+export interface ProjectQrAddress {
+    url: string;
+    hostname: string;
+    kind: "custom_domain" | "platform";
+    isDefault: boolean;
+}
+export type ProjectQrResponse = {
+    available: true;
+    accessMode: string;
+    addresses: ProjectQrAddress[];
+} | {
+    available: false;
+    accessMode: string;
+    reason: ProjectQrUnavailableReason;
+};
+export declare function qrMatrix(url: string): QrMatrix;
+/** max(25 mm, 0.5 mm × (symbol modules per side + 8)): the 8 is the two four-module borders. */
+export declare function qrMinimumWidthMm(url: string): number;
+/**
+ * Black on white, sized only by its viewBox (one unit per module), so it prints at
+ * whatever physical width the owner chooses without resampling.
+ */
+export declare function qrSvg(url: string): string;
+/**
+ * Two module rows per text line using half blocks. LIGHT modules are drawn and dark ones
+ * left blank, so on the usual dark-background terminal the code reads dark-on-light, the
+ * polarity phone cameras expect. The size is always odd, so the last line's lower half lies
+ * past the matrix and is drawn light: a little more quiet zone, never a missing module.
+ */
+export declare function qrTerminal(url: string): string[];