ninepm 0.0.1 → 0.26.0

package/README.md

@@ -1,8 +1,237 @@
-# 9pm
+# 9pm.ai CLI
 
-This name is reserved for the [9pm.ai](https://9pm.ai) deploy CLI.
+CLI for deploying built applications to 9pm.ai.
 
-The real CLI will be published under this name shortly. Until then, install
-it via the instructions at https://9pm.ai.
+This package contains only client-side deploy code. It does not include the 9pm.ai control plane, infrastructure provisioning code, migrations, staging config, operator tokens, or smoke-test scripts.
 
-Published by TMRW (tmrw.com).
+## Install
+
+```sh
+npm i -g ninepm        # persistent `9pm` binary
+npx ninepm <args>      # run without installing
+```
+
+## Configure
+
+Authenticate in your own browser. The CLI stores the token in native protected storage: macOS Keychain, Windows DPAPI, or Linux Secret Service when available. If native storage is unavailable, plaintext file storage is opt-in with `--allow-file-credential-store` or `NINEPM_ALLOW_FILE_CREDENTIAL_STORE=1`.
+
+```sh
+9pm login
+9pm whoami
+9pm doctor
+```
+
+For CI, set `NINEPM_API_KEY` yourself in the CI secret store. `--token` and `NINEPM_API_KEY` still override the stored login token.
+
+## Inventory
+
+List the apps you have on 9pm.ai before deploying or modifying:
+
+```sh
+9pm apps
+9pm apps --json
+```
+
+The slug column is the handle you pass to `access`, `delete`, and `files --project`.
+
+## Versioning
+
+Check installed vs published CLI version:
+
+```sh
+9pm --version       # installed
+9pm latest          # installed vs latest, prints update one-liner when behind
+9pm doctor          # surfaces the same drift line alongside credential/account health
+```
+
+Upgrade:
+
+```sh
+npm i -g ninepm@latest
+```
+
+## Deploy
+
+Deploy a static directory:
+
+```sh
+9pm deploy . --name my-app --slug my-app
+```
+
+Deploy a built framework output directory:
+
+```sh
+npm run build
+9pm deploy ./dist --check
+9pm deploy ./dist --name my-app --slug my-app
+```
+
+Deploy with a managed SQL database:
+
+```sh
+9pm deploy ./dist --name my-app --slug my-app --with-db
+```
+
+Attach an optional short description to the deploy (shown next to the version in the dashboard; up to 200 characters):
+
+```sh
+9pm deploy ./dist --name my-app --slug my-app --description "Fix login redirect"
+```
+
+The CLI prints the public app URL after upload and finalization.
+
+Store and share working files:
+
+```sh
+9pm files put ./report.pdf
+9pm files share <file-id> --expires 24h
+9pm files put ./notes.md --project my-app --path notes/release.md
+9pm files share <file-id> --project my-app --login-required
+```
+
+Personal files and project files both count toward the account file storage limit. Share links expire and are capped at 7 days. Login-required links are owner-only.
+
+Deploy a first-class Worker runtime app:
+
+```sh
+9pm deploy ./examples/worker-app --name worker-app --slug worker-app --runtime worker --entry src/index.js --with-db
+```
+
+The `--runtime worker` entry must be a bundled fetch-compatible JavaScript module with a default export. With `--with-db`, the app receives `env.DB` and should use SQLite-compatible prepared statements.
+
+Deploy a container app from a local Docker build:
+
+```sh
+9pm deploy . --check --runtime container --port 8080
+9pm deploy . --name container-app --slug container-app --runtime container --port 8080 --health-path /health --region auto
+```
+
+Container deploys require Docker locally. The CLI builds a `linux/amd64` image, exports it, checks image size against the per-app limit and account retained-image quota, uploads through a short-lived session, and finalizes a queued deployment. The container must listen on `0.0.0.0:$PORT` or the selected `--port`; set `--health-path` when the app has a cheap readiness endpoint.
+
+Use `--with-db` when the container needs managed SQL. The app receives `NINEPM_SQL_URL` and `NINEPM_DB_BINDINGS`; send `POST` requests to `NINEPM_SQL_URL` with `{ "binding": "DB", "sql": "SELECT 1", "params": [] }`. For local development, use the app's normal local database adapter behind a repository layer and keep deployed SQL compatible with SQLite.
+
+Regions are provider-neutral: `auto`, `us-east`, `us-west`, `europe`, `asia`, `south-america`, `middle-east`, `oceania`, `africa`.
+
+When a container app fails to come up or you want to investigate it after the fact, retrieve its recent logs:
+
+```sh
+9pm logs my-app                # recent container logs + the failure reason, if any
+9pm logs my-app --lines 50     # last N lines
+9pm logs my-app --json         # machine-readable
+```
+
+`9pm logs` reports the latest container deployment's status, health, the failure reason, and the captured startup output when a deploy failed to come up. It is read-only and does not affect deploys.
+
+Delete an app, its managed database, managed container app, and retained image:
+
+```sh
+9pm delete my-app --confirm my-app
+```
+
+## Access Modes
+
+Apps are public by default.
+
+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 revoke email my-app dev@example.com
+9pm access revoke domain my-app example.com
+```
+
+Identity provider access:
+
+```sh
+9pm access idp my-app --provider google
+```
+
+Machine access:
+
+```sh
+9pm access service create my-app --name backend
+```
+
+Return to public:
+
+```sh
+9pm access public my-app
+```
+
+Create an app-scoped runtime token for server-side allowlist management:
+
+```sh
+9pm access token create my-app --name production-app-server
+```
+
+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.
+
+## Commands
+
+```sh
+9pm --version
+9pm deploy [directory] --name <name> [--slug <slug>] [--with-db]
+9pm deploy [directory] --check [--runtime worker --entry <path>]
+9pm deploy [directory] --runtime container --port 8080 [--health-path /health] [--region auto] [--with-db]
+9pm signup
+9pm login
+9pm logout
+9pm doctor [--json]
+9pm whoami
+9pm apps [--json]
+9pm latest [--json]
+9pm files list [--project <site>]
+9pm files put <local-path> [--path <remote-path>] [--project <site>]
+9pm files get <file-id> [--output <path>] [--project <site>]
+9pm files share <file-id> [--expires 24h] [--login-required] [--project <site>]
+9pm files delete <file-id> [--project <site>]
+9pm deploy [directory] --runtime worker --entry <path> [--with-db]
+9pm delete <site> --confirm <slug>
+9pm access show <site>
+9pm access public <site>
+9pm access otp <site>
+9pm access idp <site> [--provider google|github|entra]
+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 revoke <site> <service-token-id>
+9pm access token create <site> [--name <name>]
+9pm access token revoke <site> <token-id>
+```
+
+Options:
+
+- `--api-url <url>` overrides `NINEPM_API_URL`
+- `--token <key>` overrides `NINEPM_API_KEY`
+- `--allow-file-credential-store` permits plaintext fallback storage for `login` and `signup` when native protected storage is unavailable
+- `--name <name>` sets the app display name
+- `--slug <slug>` sets the URL-safe app slug
+- `--with-db` requests managed storage for the app
+- `--database-name <name>` customizes the requested database name
+- `--binding <name>` customizes the database binding name
+- `--environment <name>` sets deployment environment metadata
+- `--runtime <static|worker|container>` selects static asset hosting, app-owned Worker code, or local Docker container deployment
+- `--entry <path>` selects the Worker runtime server entry file
+- `--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
+- `--project <site>` scopes file commands to an app
+- `--path <remote-path>` stores a file at a specific path
+- `--output <path>` writes a downloaded file to disk
+- `--expires <duration>` sets public share-link expiry, capped at 7 days
+- `--login-required` creates an owner-only share link
+- `--confirm <slug>` confirms app deletion by requiring the slug
+- `--provider <google|github|entra>` selects a configured identity provider
+- `--duration <duration>` sets a service token duration
+
+Access command options:
+
+- `--api-url <url>` overrides `NINEPM_API_URL`
+- `--token <key>` overrides `NINEPM_API_KEY`
+- `--name <name>` names an app-scoped runtime token
+- `--expires-at <iso-date>` optionally expires an app-scoped runtime token

package/dist/cli-config.d.ts

@@ -0,0 +1,5 @@
+export declare const DEFAULT_API_URL = "https://api.9pm.ai";
+export declare const CLI_CLIENT_ID = "ninepm";
+export declare const API_URL_HELP = "Control plane API URL";
+export declare const API_KEY_HELP = "API key from 9pm.ai; overrides stored login";
+export declare function reportCliError(error: unknown): void;

package/dist/cli-config.js

@@ -0,0 +1,17 @@
+// Per-entry CLI configuration. This is the ONLY file that intentionally differs
+// between the shipped ninepm tarball (this copy) and the in-repo dev CLI
+// (src/cli/cli-config.ts). Everything else in this package is generated from
+// src/cli by scripts/generate-cli-package.mjs, so behavior changes land once.
+// Keep the two cli-config.ts files in deliberate sync only for the values below.
+//
+// Tarball variant: targets the production control plane and keeps output terse.
+export const DEFAULT_API_URL = "https://api.9pm.ai";
+// Value recorded in deployment metadata's `cli` field.
+export const CLI_CLIENT_ID = "ninepm";
+// Help text for the NINEPM_API_URL / NINEPM_API_KEY environment variables.
+export const API_URL_HELP = "Control plane API URL";
+export const API_KEY_HELP = "API key from 9pm.ai; overrides stored login";
+// Render an error to stderr.
+export function reportCliError(error) {
+    console.error(error instanceof Error ? error.message : error);
+}

package/dist/cli-types.d.ts

@@ -0,0 +1,131 @@
+export type DeploymentStatus = "pending_upload" | "queued" | "publishing" | "active" | "failed";
+export type AppDatabaseStatus = "requested" | "provisioned" | "failed";
+export type AccessMode = "public" | "private_otp" | "private_idp" | "private_service";
+export type AccessGrantType = "email" | "domain";
+export type AccessProviderKey = "google" | "github" | "entra";
+export type AccessProvisioningStatus = "not_configured" | "active" | "failed";
+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 interface Project {
+    id: string;
+    name: string;
+    slug: string;
+    activeDeploymentId: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface FileManifestEntry {
+    path: string;
+    size: number;
+    sha256: string;
+    contentType: string;
+}
+export interface Deployment {
+    id: string;
+    projectId: string;
+    version: number;
+    status: DeploymentStatus;
+    environment: string;
+    url: string;
+    manifest: FileManifestEntry[];
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    finalizedAt: string | null;
+}
+export interface ContainerImageUploadInstruction {
+    uploadUrl: string;
+    completeUrl?: string;
+    method: "PUT";
+    expiresAt: string;
+    maxBytes: number;
+    partBytes?: number;
+    headers: Record<string, string>;
+}
+export interface AppDatabase {
+    id: string;
+    projectId: string;
+    name: string;
+    bindingName: string;
+    status: AppDatabaseStatus;
+    providerDatabaseId: string | null;
+    providerDatabaseName: string | null;
+    migrationsStatus: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface ManagedFileObject {
+    id: string;
+    projectId: string | null;
+    scope: ManagedFileScope;
+    path: string;
+    size: number;
+    contentType: string;
+    sha256: string;
+    createdAt: string;
+    updatedAt: string;
+    deletedAt: string | null;
+}
+export interface ManagedFileShare {
+    id: string;
+    fileId: string;
+    projectId: string | null;
+    mode: ManagedFileShareMode;
+    expiresAt: string;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface ManagedFileUsage {
+    usedBytes: number;
+    quotaBytes: number;
+}
+export interface AppAccessSettings {
+    projectId: string;
+    mode: AccessMode;
+    grantsVersion: number;
+    accessAppId: string | null;
+    accessAppAud: string | null;
+    accessPolicyId: string | null;
+    accessHostname: string | null;
+    providerKeys: AccessProviderKey[];
+    allowedIdps: string[];
+    provisioningStatus: AccessProvisioningStatus;
+    provisioningError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AccessGrant {
+    id: string;
+    projectId: string;
+    type: AccessGrantType;
+    value: string;
+    revokedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AppAccessToken {
+    id: string;
+    projectId: string;
+    name: string;
+    prefix: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface AppAccessServiceToken {
+    id: string;
+    projectId: string;
+    name: string;
+    clientId: string;
+    duration: string;
+    expiresAt: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+}
+export interface UploadInstruction {
+    path: string;
+    method: "PUT";
+    uploadUrl: string;
+    headers: Record<string, string>;
+}

package/dist/cli-types.js

@@ -0,0 +1,7 @@
+// 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.
+// Public, platform-opaque shapes the CLI exchanges with the control plane API.
+// Single source of truth for both the in-repo dev CLI (src/cli) and the shipped
+// ninepm tarball (packages/cli), which receives a generated copy at build time
+// (scripts/generate-cli-package.mjs). Keep free of server-only fields and imports.
+export {};

package/dist/deploy-description.d.ts

@@ -0,0 +1,11 @@
+export declare const MAX_DEPLOY_DESCRIPTION_LENGTH = 200;
+export declare class DeployDescriptionTooLongError extends Error {
+    constructor();
+}
+/**
+ * Normalize a raw description value into what we persist:
+ * - non-strings, undefined, and whitespace-only -> null ("no description")
+ * - otherwise trimmed
+ * Throws {@link DeployDescriptionTooLongError} if the trimmed value exceeds the cap.
+ */
+export declare function normalizeDeployDescription(value: unknown): string | null;

package/dist/deploy-description.js

@@ -0,0 +1,31 @@
+// 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.
+// A deploy description is a short, optional, human-readable note attached to a
+// deployment. Both the CLI and the control plane normalize through here
+// so the rules stay identical on either side of the API.
+export const MAX_DEPLOY_DESCRIPTION_LENGTH = 200;
+export class DeployDescriptionTooLongError extends Error {
+    constructor() {
+        super(`Deploy description must be at most ${MAX_DEPLOY_DESCRIPTION_LENGTH} characters.`);
+        this.name = "DeployDescriptionTooLongError";
+    }
+}
+/**
+ * Normalize a raw description value into what we persist:
+ * - non-strings, undefined, and whitespace-only -> null ("no description")
+ * - otherwise trimmed
+ * Throws {@link DeployDescriptionTooLongError} if the trimmed value exceeds the cap.
+ */
+export function normalizeDeployDescription(value) {
+    if (typeof value !== "string") {
+        return null;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return null;
+    }
+    if (trimmed.length > MAX_DEPLOY_DESCRIPTION_LENGTH) {
+        throw new DeployDescriptionTooLongError();
+    }
+    return trimmed;
+}

package/dist/deploy-limits.d.ts

@@ -0,0 +1,7 @@
+export declare const MAX_STATIC_ASSET_FILE_BYTES: number;
+export declare function formatMebibytes(bytes: number): string;
+export declare function assetFileTooLargeMessage(filePath: string, size: number): string;
+export declare function oversizedAssets<T extends {
+    path: string;
+    size: number;
+}>(files: readonly T[]): T[];

package/dist/deploy-limits.js

@@ -0,0 +1,30 @@
+// 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.
+// Single source of truth for the per-file static-asset size limit, shared by the
+// control plane (the create-deployment guard) and the CLI (`--check` and the
+// real-deploy preflight). Keep this module dependency-free: it is copied verbatim
+// into the shipped ninepm tarball, so it must not import server-only or
+// Cloudflare code.
+// Individual static/worker assets are capped at 25 MiB. A file above this can't
+// be served by the platform at all (inlining it into the Worker script blows the
+// finalize CPU/script-size budget — the #169 failure), so it is rejected up front:
+// at `9pm deploy --check`, before the project is created on a real deploy (#195),
+// and at create time on the server.
+export const MAX_STATIC_ASSET_FILE_BYTES = 25 * 1024 * 1024;
+// Mebibyte-accurate formatter for the size-limit messaging. The general-purpose
+// formatBytes() labels 1024²-based values "MB"; here we say "MiB" so the number,
+// the unit, and the actual binary threshold agree (the cap is 25 MiB, not the
+// 26.2 MB that "25 MB" would imply).
+export function formatMebibytes(bytes) {
+    const mib = Math.max(0, bytes) / (1024 * 1024);
+    // Whole numbers read cleanly (25 MiB); fractional sizes get one decimal.
+    return Number.isInteger(mib) ? `${mib} MiB` : `${mib.toFixed(1)} MiB`;
+}
+export function assetFileTooLargeMessage(filePath, size) {
+    return `File "${filePath}" is ${formatMebibytes(size)}; individual files are limited to ${formatMebibytes(MAX_STATIC_ASSET_FILE_BYTES)}.`;
+}
+// Manifest entries that exceed the per-file limit. A structural type keeps this
+// module free of cross-tree type imports so it copies cleanly into the CLI.
+export function oversizedAssets(files) {
+    return files.filter((file) => file.size > MAX_STATIC_ASSET_FILE_BYTES);
+}