ninepm 0.68.0 → 0.72.0

package/README.md

@@ -62,6 +62,28 @@ Deploy a static directory:
 9pm deploy . --name my-app --slug my-app
 ```
 
+### How long an app's address stays the same
+
+Check this before printing a link or QR code. The live URL is `<slug>-<suffix>.9pm.ai`, and the suffix comes from the app's internal id, not from the slug:
+
+- Redeploying under the same slug keeps the address.
+- Deleting the app and creating it again under the same slug gives it a **new** address, because the new app gets a new id. Anything printed with the old one stops working.
+- There is no rename: a different address means a different app.
+- A custom domain you own, added on the dashboard's Domains page, gives the app an address of your own. Not every plan includes custom domains.
+
+### Pages that do not exist
+
+A static site or `--entry` worker app answers a path that has no file in one of two ways. Every deploy prints which, as a `Missing pages:` line.
+
+- `--no-spa` (the default for new apps): the path returns status 404, with the deploy's own `404.html` when it has one. `/` still serves `index.html`, and extensionless links work: `/menu` serves `menu.html`, or redirects to `/menu/` when only `menu/index.html` exists, and `/menu/` serves `menu/index.html`. Right for a multi-page site, where a removed or mistyped page should say "not found" rather than show the homepage.
+- `--spa`: every path with no file serves `index.html`, so a single-page app that routes in the browser loads on a deep link or a refresh. That includes dotted paths such as `/users/jane.smith` and missing files such as `/missing.json`, which get the app's shell rather than a 404.
+
+```sh
+9pm deploy ./dist --name my-spa --spa
+```
+
+The app remembers the choice: a deploy without either flag keeps it, and a deploy that fails to publish leaves the previous choice in place. Apps created before this choice existed keep serving `index.html` for every unmatched path until a deploy passes one of the flags. A worker app's own `Response`, a 404 included, is always returned as it is. The flags do not apply to `--bundle` or container apps.
+
 Deploy a built framework output directory:
 
 ```sh
@@ -137,16 +159,20 @@ Delete an app, its managed database, managed container app, and retained image:
 9pm delete my-app --confirm my-app
 ```
 
+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.
+
 ## Access Modes
 
 Apps are public by default.
 
+Changing an app's access mode needs `--switch-mode`. Without it the command changes nothing and prints what the change would do (who loses access, what happens to the app's custom domains) and the command to re-run. Service-token mode locks every person out and removes the app's custom domains; leaving it sets them up again with new DNS records to publish. Creating another service token on an app already in service-token mode needs no flag.
+
 One-time PIN with email/domain allowlist:
 
 ```sh
 9pm access allow email my-app dev@example.com
 9pm access allow domain my-app example.com
-9pm access otp my-app
+9pm access otp my-app --switch-mode
 9pm access revoke email my-app dev@example.com
 9pm access revoke domain my-app example.com
 ```
@@ -154,19 +180,19 @@ One-time PIN with email/domain allowlist:
 Identity provider access:
 
 ```sh
-9pm access idp my-app --provider google
+9pm access idp my-app --provider google --switch-mode
 ```
 
 Machine access:
 
 ```sh
-9pm access service create my-app --name backend
+9pm access service create my-app --name backend --switch-mode
 ```
 
 Return to public:
 
 ```sh
-9pm access public my-app
+9pm access public my-app --switch-mode
 ```
 
 Create an app-scoped runtime token for server-side allowlist management:
@@ -178,11 +204,40 @@ Create an app-scoped runtime token for server-side allowlist management:
 Use `9pm_app_...` runtime tokens only from server-side code. They can list, add, and remove email/domain grants for one app. They cannot deploy, create databases, create API keys, or manage another app.
 Service token secrets returned by `access service create` are also server-side secrets.
 
+## Custom Domains
+
+Connect a domain you own to an app:
+
+```sh
+9pm domains add my-app www.example.com
+```
+
+This prints the DNS records to publish at your DNS provider, with names relative to your
+domain (`www`, `_acme-challenge.www`) and what DNS shows for each right now. When a TXT value
+is missing, add it as its own TXT record; other TXT values on that name can stay. The root of
+your domain (`@`) cannot hold a CNAME, so a root domain is shown as an `ALIAS` record: add it as
+ALIAS or ANAME (or a CNAME your provider flattens). A correct ALIAS answers with addresses, which
+cannot be compared from outside, so that row follows the platform's own routing check. Then:
+
+```sh
+9pm domains wait my-app www.example.com
+```
+
+`wait` exits `0` once the domain is live, `10` if it timed out while a record is missing or could
+not be checked, `11` if it timed out with every record checked and found (the platform is still
+finishing; wait again), `20` if the domain failed or expired, and `1` on a usage, sign-in or API
+error. `9pm domains status <app> <hostname> --json` prints `{hostname, app, state, routing, tls,
+provider, nameservers, records, error, expiresAt, checkedAt}`, where `state` is `live`,
+`waiting_for_dns`, `dns_unverified` (routing is active but the records could not be checked),
+`issuing_certificate`, `failed` or `expired`. Each record's `ok` is `null` when the check cannot
+say, and its `check` says why (`not_checked`, or `apex_addresses`). `list`, `status` and `wait`
+only read; `add`, `check`, `restart` and `remove` need permission to configure the app.
+
 ## Commands
 
 ```sh
 9pm --version
-9pm deploy [directory] --name <name> [--slug <slug>] [--with-db]
+9pm deploy [directory] --name <name> [--slug <slug>] [--spa | --no-spa] [--with-db]
 9pm deploy [directory] --check [--runtime worker --entry <path> (--assets <dir> | --no-assets)]
 9pm deploy [directory] --runtime container --port 8080 [--health-path /health] [--region auto] [--with-db]
 9pm signup
@@ -197,17 +252,24 @@ Service token secrets returned by `access service create` are also server-side s
 9pm files get <file-id> [--output <path>] [--project <site>]
 9pm files share <file-id> [--expires 24h] [--public] [--project <site>]
 9pm files delete <file-id> [--project <site>]
-9pm deploy [directory] --runtime worker --entry <path> (--assets <dir> | --no-assets) [--with-db]
+9pm deploy [directory] --runtime worker --entry <path> (--assets <dir> | --no-assets) [--spa | --no-spa] [--with-db]
 9pm delete <site> --confirm <slug>
+9pm domains list [<app>] [--owner <organisation>] [--json]
+9pm domains add <app> <hostname> [--json]
+9pm domains status <app> <hostname> [--json]
+9pm domains check <app> <hostname> [--json]
+9pm domains wait <app> <hostname> [--timeout 30m] [--interval 20s] [--json]
+9pm domains restart <app> <hostname>
+9pm domains remove <app> <hostname> --confirm <hostname>
 9pm access show <site>
-9pm access public <site>
-9pm access otp <site>
-9pm access idp <site> [--provider google|github|entra]
+9pm access public <site> [--switch-mode]
+9pm access otp <site> [--switch-mode]
+9pm access idp <site> [--provider google|github|entra] [--switch-mode]
 9pm access allow email <site> <email>
 9pm access allow domain <site> <domain>
 9pm access revoke email <site> <email>
 9pm access revoke domain <site> <domain>
-9pm access service create <site> [--name <name>] [--duration 8760h]
+9pm access service create <site> [--name <name>] [--duration 8760h] [--switch-mode]
 9pm access service revoke <site> <service-token-id>
 9pm access token create <site> [--name <name>]
 9pm access token revoke <site> <token-id>
@@ -229,6 +291,8 @@ Options:
 - `--entry <path>` selects the Worker runtime server entry file
 - `--assets <dir>` makes only that directory of a worker deploy public (remembered for later deploys)
 - `--no-assets` makes no file of a worker deploy public (remembered for later deploys)
+- `--spa` serves `index.html` for every path that has no file, for single-page apps (remembered for later deploys)
+- `--no-spa` returns 404 for a path that has no file, with the deploy's `404.html` when present; the default for new apps (remembered for later deploys)
 - `--port <port>` selects the HTTP port exposed by a container app
 - `--health-path <path>` optionally lets 9pm.ai check container health before marking it healthy
 - `--region <region>` optionally selects provider-neutral container placement

package/dist/cli-types.d.ts

@@ -8,6 +8,7 @@ export type AppRuntime = "static" | "worker" | "container";
 export type ContainerRegion = "auto" | "us-east" | "us-west" | "europe" | "asia" | "south-america" | "middle-east" | "oceania" | "africa";
 export type ManagedFileScope = "user" | "project";
 export type ManagedFileShareMode = "public" | "login_required";
+export type MissingPagesMode = "legacy" | "spa" | "404";
 export interface Project {
     id: string;
     name: string;
@@ -16,6 +17,7 @@ export interface Project {
     createdAt: string;
     updatedAt: string;
     workerPublicAssets?: string | null;
+    missingPages?: MissingPagesMode;
 }
 export interface AppUserFilesUsage {
     usedBytes: number;

package/dist/dns-host.d.ts

@@ -0,0 +1,7 @@
+/** A best guess at the zone a custom hostname lives in: `www.tmrwtitans.com` -> `tmrwtitans.com`. */
+export declare function guessZoneApex(hostname: string): string;
+/**
+ * The record name the way most registrars' Host field wants it, relative to the zone:
+ * `www.tmrwtitans.com` -> `www`, the apex itself -> `@`. A name outside the zone stays whole.
+ */
+export declare function relativeRecordName(recordHost: string, apex: string): string;

package/dist/dns-host.js

@@ -0,0 +1,27 @@
+// AUTO-GENERATED by scripts/generate-cli-package.mjs from the in-repo CLI source -- do not edit.
+// Edit src/cli or src/shared instead; this is regenerated on typecheck/test/build/pack.
+// Record names for a custom domain's DNS instructions, written the way a registrar's Host
+// field wants them. Read by the dashboard's DNS table and by `9pm domains`, and copied into
+// the CLI tarball by scripts/generate-cli-package.mjs, so it must import nothing.
+// Second-level labels that sit under a two-letter country code as part of the public suffix
+// (example.co.uk, example.com.au). Not a public suffix list: it covers the common shapes, and
+// the full name is always shown beside the short one for the cases it misses.
+const SECOND_LEVEL = new Set(["co", "com", "net", "org", "gov", "ac", "edu", "ne", "or", "go"]);
+/** A best guess at the zone a custom hostname lives in: `www.tmrwtitans.com` -> `tmrwtitans.com`. */
+export function guessZoneApex(hostname) {
+    const labels = hostname.toLowerCase().replace(/\.$/, "").split(".");
+    if (labels.length >= 3 && SECOND_LEVEL.has(labels[labels.length - 2]) && labels[labels.length - 1].length === 2) {
+        return labels.slice(-3).join(".");
+    }
+    return labels.slice(-2).join(".");
+}
+/**
+ * The record name the way most registrars' Host field wants it, relative to the zone:
+ * `www.tmrwtitans.com` -> `www`, the apex itself -> `@`. A name outside the zone stays whole.
+ */
+export function relativeRecordName(recordHost, apex) {
+    const host = recordHost.toLowerCase().replace(/\.$/, "");
+    if (host === apex)
+        return "@";
+    return host.endsWith(`.${apex}`) ? host.slice(0, -(apex.length + 1)) : host;
+}

package/dist/index.d.ts

@@ -18,6 +18,7 @@ export interface DeployOptions {
     runtime?: AppRuntime;
     entry?: string;
     publicAssets?: string;
+    missingPages?: "spa" | "404";
     port?: number;
     healthPath?: string;
     region?: ContainerRegion;
@@ -124,7 +125,7 @@ export interface CreatedServiceToken {
     clientSecret: string;
 }
 export type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
-export declare const CLI_VERSION = "0.68.0";
+export declare const CLI_VERSION = "0.72.0";
 type CredentialBackend = "macos-keychain" | "windows-dpapi" | "linux-secret-service" | "file-plaintext" | "none";
 export interface StoredCredentialEntry {
     token: string;
@@ -225,7 +226,8 @@ export declare class DeployError extends Error {
  * prevent (#1061).
  */
 export declare class DeliberateRefusalError extends Error {
-    constructor(message: string);
+    readonly code: string | undefined;
+    constructor(message: string, code?: string);
 }
 export declare function isDeliberateRefusal(error: unknown): boolean;
 export declare function deployDirectory(initialOptions: DeployOptions): Promise<DeployResult>;
@@ -271,12 +273,16 @@ export type LogoutSummary = {
 };
 export declare function summarizeRevocations(attempts: RevocationAttempt[]): LogoutSummary;
 export declare function getSiteAccess(options: SiteAccessOptions): Promise<AccessState>;
-export declare function setSiteAccessPublic(options: SiteAccessOptions): Promise<AccessState["access"]>;
-export declare function setSiteAccessOtp(options: SiteAccessOptions): Promise<AccessState["access"]>;
-export declare function setSiteAccessIdp(options: SiteAccessOptions & {
+export declare const ACCESS_MODE_CHANGE_UNCONFIRMED = "access_mode_change_unconfirmed";
+export interface AccessModeChangeOptions extends SiteAccessOptions {
+    switchMode?: boolean;
+}
+export declare function setSiteAccessPublic(options: AccessModeChangeOptions): Promise<AccessState["access"]>;
+export declare function setSiteAccessOtp(options: AccessModeChangeOptions): Promise<AccessState["access"]>;
+export declare function setSiteAccessIdp(options: AccessModeChangeOptions & {
     providers?: AccessProviderKey[];
 }): Promise<AccessState["access"]>;
-export declare function createAccessServiceToken(options: SiteAccessOptions & {
+export declare function createAccessServiceToken(options: AccessModeChangeOptions & {
     name?: string;
     duration?: string;
 }): Promise<CreatedServiceToken>;
@@ -343,6 +349,7 @@ export interface ListSitesResult {
 export declare function listSites(options: ApiOptions & {
     owner?: string;
 }): Promise<ListSitesResult>;
+export declare function deleteWarningLines(slug: string): string[];
 export declare function deleteSite(options: DeleteSiteOptions): Promise<DeletedSiteResult>;
 export interface DeviceAuthFeedbackOptions {
     progressStream?: NodeJS.WriteStream;
@@ -611,6 +618,36 @@ type CliCommand = {
     };
     apiUrl: string;
     token: string;
+} | {
+    kind: "domains";
+    owner?: string;
+    action: {
+        kind: "list";
+        site?: string;
+        json: boolean;
+    } | {
+        kind: "add" | "status" | "check";
+        site: string;
+        hostname: string;
+        json: boolean;
+    } | {
+        kind: "wait";
+        site: string;
+        hostname: string;
+        json: boolean;
+        timeoutSeconds: number;
+        intervalSeconds: number;
+    } | {
+        kind: "restart";
+        site: string;
+        hostname: string;
+    } | {
+        kind: "remove";
+        site: string;
+        hostname: string;
+    };
+    apiUrl: string;
+    token: string;
 } | {
     kind: "deployments";
     action: {
@@ -631,13 +668,16 @@ type CliCommand = {
     } | {
         kind: "public";
         site: string;
+        switchMode?: true;
     } | {
         kind: "otp";
         site: string;
+        switchMode?: true;
     } | {
         kind: "idp";
         site: string;
         providers?: AccessProviderKey[];
+        switchMode?: true;
     } | {
         kind: "allow";
         site: string;
@@ -653,6 +693,7 @@ type CliCommand = {
         site: string;
         name?: string;
         duration?: string;
+        switchMode?: true;
     } | {
         kind: "service-revoke";
         site: string;
@@ -668,6 +709,7 @@ type CliCommand = {
         tokenId: string;
     };
     apiUrl: string;
+    apiUrlFrom: ApiUrlSource;
     token: string;
 };
 export declare function parseArgs(argv: string[]): CliCommand;
@@ -676,7 +718,142 @@ export declare function parseEnvFileEntries(content: string, kind: "secret" | "v
     value: string;
     kind: "secret" | "var";
 }>;
+export type ListedDeployment = Pick<Deployment, "id" | "version" | "status" | "createdAt"> & {
+    active: boolean;
+};
+export declare function deploymentStatusLabel(deployment: ListedDeployment): string;
+export declare function formatDeploymentsList(deployments: ListedDeployment[]): string[];
+export declare function deploymentsListJson<T extends ListedDeployment>(deployments: T[]): {
+    servingDeploymentId: string | null;
+    deployments: Array<T & {
+        serving: boolean;
+    }>;
+};
+export interface CliDnsInstruction {
+    type: string;
+    host: string;
+    value: string;
+    optional?: boolean;
+}
+export interface CliDomainDnsCheck {
+    provider: string | null;
+    nameservers: string[];
+    records: Array<{
+        type: string;
+        host: string;
+        expected: string;
+        current: string[];
+        matches: boolean;
+    }>;
+}
+export interface CliDomain {
+    hostname: string;
+    routingStatus: string;
+    tlsStatus: string;
+    dnsInstructions: CliDnsInstruction[];
+    provisioningError: string | null;
+    expireAfter?: string | null;
+    expiresAt?: string | null;
+    dnsCheck?: CliDomainDnsCheck;
+    app?: {
+        id: string;
+        slug: string;
+        name: string;
+    };
+}
+export type DomainState = "live" | "waiting_for_dns" | "dns_unverified" | "issuing_certificate" | "failed" | "expired";
+export declare const CUSTOM_DOMAIN_EXPIRED_TEXT = "This domain was removed because its DNS verification was never completed. Add the domain again to retry.";
+export interface DomainRecordStatus {
+    type: string;
+    name: string;
+    fqdn: string;
+    expected: string;
+    current: string[] | null;
+    ok: boolean | null;
+    check: DomainRecordCheck;
+    apex: boolean;
+    optional: boolean;
+}
+export type DomainRecordCheck = "found" | "missing" | "different" | "not_checked" | "apex_addresses";
+export interface DomainStatusJson {
+    hostname: string;
+    app: string;
+    state: DomainState;
+    routing: string;
+    tls: string;
+    provider: string | null;
+    nameservers: string[];
+    records: DomainRecordStatus[];
+    error: string | null;
+    expiresAt: string | null;
+    checkedAt: string;
+}
+export declare const DOMAIN_WAIT_EXIT: {
+    readonly live: 0;
+    readonly ownerAction: 10;
+    readonly platform: 11;
+    readonly failed: 20;
+};
+export declare function domainRecordStatuses(domain: CliDomain): DomainRecordStatus[];
+export declare function deriveDomainState(domain: CliDomain, records?: DomainRecordStatus[]): DomainState;
+export declare function domainStatusJson(domain: CliDomain, app: string, checkedAt: string): DomainStatusJson;
+export declare function domainStateLabel(state: DomainState): string;
+export declare function formatDomainStatus(status: DomainStatusJson, options?: {
+    owner?: string;
+}): string[];
+export declare function domainWaitTimeoutMessage(status: DomainStatusJson): string;
+export declare function formatDomainsList(statuses: DomainStatusJson[]): string[];
+export declare class DomainsApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    constructor(message: string, status: number, code: string | null);
+}
+export declare function domainsApiError(status: number, text: string): DomainsApiError;
+export interface DomainCommandOptions extends ApiOptions {
+    site: string;
+    owner?: string;
+}
+export declare function normalizeDomainArg(value: string): string;
+export declare function listDomainStatuses(options: ApiOptions & {
+    site?: string;
+    owner?: string;
+    now?: () => Date;
+}): Promise<DomainStatusJson[]>;
+export declare function getDomainStatus(options: DomainCommandOptions & {
+    hostname: string;
+    now?: () => Date;
+}): Promise<DomainStatusJson>;
+export declare function addDomain(options: DomainCommandOptions & {
+    hostname: string;
+}): Promise<CliDomain | null>;
+export declare function recheckDomain(options: DomainCommandOptions & {
+    hostname: string;
+}): Promise<void>;
+export declare function restartDomain(options: DomainCommandOptions & {
+    hostname: string;
+}): Promise<{
+    domain: CliDomain;
+    replacedInstructions: CliDnsInstruction[];
+}>;
+export declare function removeDomain(options: DomainCommandOptions & {
+    hostname: string;
+}): Promise<CliDomain | null>;
+export interface DomainWaitResult {
+    status: DomainStatusJson;
+    exitCode: number;
+    timedOut: boolean;
+}
+export declare function waitForDomain(options: DomainCommandOptions & {
+    hostname: string;
+    timeoutMs: number;
+    intervalMs: number;
+    nowMs?: () => number;
+    sleepFn?: (ms: number) => Promise<void>;
+    onStatus?: (status: DomainStatusJson) => void;
+    onRetry?: (error: unknown) => void;
+}): Promise<DomainWaitResult>;
 export declare function healthWithReason(status: string | null | undefined, reason: string | null | undefined): string;
+export type ApiUrlSource = "flag" | "env" | "default";
 export declare function workerPublicFiles(paths: readonly string[], serverEntry: string, selection: string | null): Array<{
     path: string;
     url: string;
@@ -711,4 +888,15 @@ export declare function hasNoGraphicalDisplay(platform: string, env: Record<stri
 export declare function formatAppUserFilesUsageLine(slug: string, usage: AppUserFilesUsage): string;
 export declare class UsageError extends Error {
 }
+export declare function missingPagesLine(deployment: Deployment): string | null;
+type AccessModeChangeAction = Extract<Extract<CliCommand, {
+    kind: "access";
+}>["action"], {
+    kind: "public" | "otp" | "idp" | "service-create";
+}>;
+export interface AccessApiTarget {
+    apiUrl: string;
+    apiUrlFrom: ApiUrlSource;
+}
+export declare function accessSwitchModeCommand(action: AccessModeChangeAction, target?: AccessApiTarget): string;
 export {};