ninepm 0.83.0 → 0.85.0

package/README.md

@@ -269,9 +269,21 @@ another service's certificate check uses `_acme-challenge`) is not ours, so leav
 that sends no such list it prints no deletion advice at all. When the removal is still finishing
 upstream (the API answers `202` with `releasing: true`), it says so, names no record to delete, and
 prints the `9pm domains list` command: once the domain is no longer listed, it has stopped serving
-from 9pm. A removal that finishes in the background returns no record list, so the CLI cannot say
-which DNS records to delete for it. Such a domain shows as `removing`
-in `list` and `status` (`"removing": true` in `--json`), and `wait` on it exits `20`. Since 0.80.0.
+from 9pm. Such a domain shows as `removing` in `list` and `status` (`"removing": true` in `--json`),
+and `wait` on it exits `20`. Since 0.80.0.
+
+Since 0.84.0, `9pm domains removed [--owner <organisation>]` lists the DNS records you may delete
+after a removal that finished in the background: a `remove` that answered `releasing`, or a domain of
+a deleted app, finished later by the platform. It is the same list `remove` prints when it finishes
+itself, under the same rule (delete a record only while it still has the value shown), and the
+printed hint after a still-finishing removal or `9pm delete` points at it, with `--owner` and
+`--api-url` kept. A removal is listed for 30 days after it finishes, only to the account that owned
+the domain, and not at all once the hostname has been added again anywhere: the server checks the
+certificate provider for it when you run the command, and a domain it couldn't check is named without
+its records, with the command to ask about it again. The server checks ten domains per page; the
+command reads up to 20 pages and says so if more remain. `--hostname <hostname>` asks about one
+domain only. `--json` prints the API's answer with its pages merged (`next` is null once every page
+was read). Against a server without the route it says it can't list any, prints no record and exits `1`.
 
 Since 0.83.0, `9pm domains cleanup <app> <hostname>` lists the setup TXT records 9pm issued for a
 live domain and no longer needs, such as an earlier `_acme-challenge` value or the
@@ -332,6 +344,7 @@ and none can be listed for it later.
 9pm domains restart <app> <hostname>          # only after a certificate failed; record values may change
 9pm domains remove <app> <hostname> --confirm <hostname> [--json]
 9pm domains move [<app>] <hostname> --to <app> [--json]
+9pm domains removed [--hostname <hostname>] [--owner <organisation>] [--json]   # records to 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/index.d.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { Agent } from "undici";
+import { type ProjectQrAddress } from "./qr-code.js";
 import { type DomainNext, type DomainReason, type DomainRecordStatus, type DomainState, type DomainStateDnsCheck, type DomainStateDnsInstruction, type DomainStateInput } from "./domain-state.js";
 import type { AccessGrant, AccessGrantType, AccessProviderKey, AppAccessSettings, AppAccessServiceToken, AppAccessToken, AppDatabase, AppRuntime, AppUserFilesUsage, ContainerImageUploadInstruction, ContainerRegion, Deployment, ManagedFileObject, ManagedFileShare, ManagedFileUsage, Project } from "./cli-types.js";
 export interface DeployOptions {
@@ -122,7 +123,7 @@ export interface DeletedSiteResult {
     metadata: boolean;
     errors?: string[];
 }
-export declare function deletedDomainLines(deleted: Pick<DeletedSiteResult, "customDomainCleanup" | "customDomainsReleasing">): string[];
+export declare function deletedDomainLines(deleted: Pick<DeletedSiteResult, "customDomainCleanup" | "customDomainsReleasing">, options?: DomainFormatOptions): string[];
 export interface CreatedRuntimeToken {
     token: string;
     appAccessToken: AppAccessToken;
@@ -132,7 +133,7 @@ export interface CreatedServiceToken {
     clientSecret: string;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-export declare const CLI_VERSION = "0.83.0";
+export declare const CLI_VERSION = "0.85.0";
 type CredentialBackend = "macos-keychain" | "windows-dpapi" | "linux-secret-service" | "file-plaintext" | "none";
 export interface StoredCredentialEntry {
     token: string;
@@ -532,6 +533,7 @@ type CliCommand = {
     confirmSlug: string;
     apiUrl: string;
     token: string;
+    apiUrlFrom?: ApiUrlSource;
 } | {
     kind: "apps";
     apiUrl: string;
@@ -628,6 +630,17 @@ type CliCommand = {
     };
     apiUrl: string;
     token: string;
+} | {
+    kind: "qr";
+    site: string;
+    owner?: string;
+    address?: string;
+    format: "svg" | "png";
+    out?: string;
+    terminal: boolean;
+    json: boolean;
+    apiUrl: string;
+    token: string;
 } | {
     kind: "domains";
     owner?: string;
@@ -668,6 +681,10 @@ type CliCommand = {
         hostname: string;
         to: string;
         json: boolean;
+    } | {
+        kind: "removed";
+        json: boolean;
+        hostname?: string;
     };
     apiUrl: string;
     token: string;
@@ -881,6 +898,18 @@ export declare function getDomainSetupCleanup(options: DomainCommandOptions & {
 export declare function domainSetupCleanupLines(body: unknown, hostname: string): string[];
 export declare function setupCleanupLines(hostname: string, records: DomainCleanupRecord[]): string[];
 export declare function domainRemovalPendingLines(hostname: string, app: string, options: DomainFormatOptions): string[];
+export declare const FINISHED_REMOVAL_PAGES_PER_COMMAND = 20;
+export declare function getFinishedDomainRemovals(options: ApiOptions & {
+    owner?: string;
+    hostname?: string;
+}): Promise<unknown>;
+export interface FinishedDomainRemoval {
+    hostname: string;
+    finishedAt: string | null;
+    cleanup: DomainCleanup;
+}
+export declare function parseFinishedDomainRemovals(body: unknown): FinishedDomainRemoval[] | null;
+export declare function finishedDomainRemovalLines(body: unknown, options?: DomainFormatOptions): string[];
 export interface DomainMove {
     body: unknown;
     hostname: string;
@@ -923,6 +952,23 @@ export declare function waitForDomain(options: DomainCommandOptions & {
     onRetry?: (error: unknown) => void;
 }): Promise<DomainWaitResult>;
 export declare function healthWithReason(status: string | null | undefined, reason: string | null | undefined): string;
+export declare 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 declare function qrMinimumWidthCmText(minimumWidthMm: number): string;
+export declare 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 declare function qrCustomDomainNote(hostname: string): string;
+/**
+ * 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 declare function pickQrAddress(addresses: readonly ProjectQrAddress[], requested: string | undefined): ProjectQrAddress;
+/** An 8-bit greyscale PNG of a module matrix (quiet zone included), black on white. */
+export declare function encodeQrPng(modules: readonly (readonly boolean[])[], scale?: number): Buffer;
 export type ApiUrlSource = "flag" | "env" | "default";
 export declare function workerPublicFiles(paths: readonly string[], serverEntry: string, selection: string | null): Array<{
     path: string;

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,7 +71,7 @@ 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)}`);
         }
     }
     catch {
@@ -78,7 +79,7 @@ export function deletedDomainLines(deleted) {
     }
     return lines;
 }
-export const CLI_VERSION = "0.83.0";
+export const CLI_VERSION = "0.85.0";
 const PUBLIC_DASHBOARD_URL = "https://9pm.ai/dashboard";
 const TOKEN_SERVICE = "9pm";
 const TOKEN_ACCOUNT = "default";
@@ -2707,6 +2708,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 +2985,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 +3875,142 @@ 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 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 +4208,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 +4237,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 +4265,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 +4341,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);
@@ -4470,6 +4625,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 +6327,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 +6377,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 +6725,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 +6737,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]