ninepm 0.81.0 → 0.85.0

package/README.md

@@ -163,6 +163,8 @@ Delete an app, its managed database, managed container app, and retained image:
 
 The app's address goes with it: creating an app again under the same slug gives it a new address, so printed links and QR codes stop working. `9pm delete` prints this warning before it deletes anything.
 
+For a static or Worker app with no custom domain, `9pm delete` also prints `Its address stops serving the app within about a minute.` It prints nothing about timing for a container app or an app with a custom domain: how long those keep serving after a delete has not been measured, so check the address yourself.
+
 ## Access Modes
 
 Apps are public by default.
@@ -267,9 +269,34 @@ 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
+`_cf-custom-hostname` ownership record (`--json` prints the API's answer). Each may be deleted only
+while it still has the value shown; a different value at that name is not ours. The list is checked
+against the certificate provider when you run the command: a value the provider still asks for is
+never in it, a domain that is not live lists nothing, and if the provider cannot be read, or the
+domain changes while it is being checked, the command fails and lists nothing; run it again. Only values the API issued are candidates, never anything read from public
+DNS. `9pm domains status` on a live domain prints the command. `9pm domains remove` lists these values
+with the rest of the domain's records, since once the domain is removed none of them is needed.
+After `9pm domains restart`, the values it says no longer count are worded the same way. Against a
+server without the route, `cleanup` says it can't list any and exits `1`. Values replaced before the
+server kept them cannot be listed.
 
 `9pm domains move <hostname> --to <app>` moves a domain to another app of the same account. It keeps
 its certificate and the DNS records already published, so nothing is validated again. Without a
@@ -317,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 {
@@ -112,6 +113,8 @@ export interface DeletedSiteResult {
     customDomainsReleasing?: unknown;
     containerApplications?: number;
     containerImages?: number;
+    flyTeardownsQueued?: number;
+    workerScripts?: unknown;
     accessApps: number;
     serviceTokens: number;
     databases: number;
@@ -120,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;
@@ -130,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.81.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;
@@ -355,6 +358,8 @@ export declare function listSites(options: ApiOptions & {
     owner?: string;
 }): Promise<ListSitesResult>;
 export declare function deleteWarningLines(slug: string): string[];
+export declare const DELETE_SERVING_BOUND_LINE = "Its address stops serving the app within about a minute.";
+export declare function deletedAppStopsServingQuickly(deleted: Pick<DeletedSiteResult, "workerScripts" | "containerApplications" | "flyTeardownsQueued" | "customDomains" | "customDomainsReleasing" | "errors">): boolean;
 export declare function deleteSite(options: DeleteSiteOptions): Promise<DeletedSiteResult>;
 export interface DeviceAuthFeedbackOptions {
     progressStream?: NodeJS.WriteStream;
@@ -528,6 +533,7 @@ type CliCommand = {
     confirmSlug: string;
     apiUrl: string;
     token: string;
+    apiUrlFrom?: ApiUrlSource;
 } | {
     kind: "apps";
     apiUrl: string;
@@ -624,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;
@@ -648,6 +665,11 @@ type CliCommand = {
         kind: "restart";
         site: string;
         hostname: string;
+    } | {
+        kind: "cleanup";
+        site: string;
+        hostname: string;
+        json: boolean;
     } | {
         kind: "remove";
         site: string;
@@ -659,6 +681,10 @@ type CliCommand = {
         hostname: string;
         to: string;
         json: boolean;
+    } | {
+        kind: "removed";
+        json: boolean;
+        hostname?: string;
     };
     apiUrl: string;
     token: string;
@@ -866,7 +892,24 @@ export interface DomainCleanup {
 }
 export declare function parseDomainCleanup(value: unknown): DomainCleanup | null;
 export declare function domainCleanupLines(cleanup: DomainCleanup): string[];
+export declare function getDomainSetupCleanup(options: DomainCommandOptions & {
+    hostname: string;
+}): Promise<unknown>;
+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;
@@ -909,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;