@inquir/compute-cli 0.3.0 → 0.4.0

package/README.md

@@ -58,31 +58,42 @@ inquir whoami                # show the signed-in user + active workspace
 
 `inquir login` prints a short code and opens a dashboard page; confirm the code
 matches and click **Authorize**. The CLI then receives its token automatically.
+Browser-issued CLI sessions expire (90 days by default; the server can configure
+a shorter lifetime). The CLI records the issuing API and expiry with the token.
+Logging in again saves the new session before revoking the previous session owned
+by that profile, unless another stored profile or environment variable still uses it.
 
 Other login modes:
 
 ```bash
 inquir login --browserless   # print the URL + code instead of opening a browser
 inquir login --token <pat>   # non-interactive (CI): use a PAT created in the dashboard
-inquir login --name "my CI"  # label the device/token shown in the dashboard
-```
-
-Login stores the API URL together with the token. To keep credentials for another
-API separately, use a named environment:
-
-```bash
-inquir login --env staging --api-url https://staging.example.com --token <pat>
-inquir whoami --env staging
-```
-
-Changing a login's API or token clears its cached identity and workspace until
-membership discovery succeeds. A previous workspace on the same API is restored
-only if the new token can still access it. If discovery is temporarily unavailable,
-the token remains saved and subsequent commands do not reuse the previous
-account's stored workspace.
-
-Create and revoke PATs from the dashboard under **API Keys → Personal Access
-Tokens**. To sign out and remove the stored token: `inquir logout`.
+inquir login --name "my CI"  # label the device/token shown in the dashboard
+```
+
+Login stores the API URL together with the token. To keep credentials for another
+API separately, use a named environment:
+
+```bash
+inquir login --env staging --api-url https://staging.example.com --token <pat>
+inquir whoami --env staging
+```
+
+Changing a login's API or token clears its cached identity and workspace until
+membership discovery succeeds. A previous workspace on the same API is restored
+only if the new token can still access it. If discovery is temporarily unavailable,
+the token remains saved and subsequent commands do not reuse the previous
+account's stored workspace.
+
+Create and revoke PATs from the dashboard under **API Keys → Personal Access
+Tokens**. `inquir logout` revokes its browser-issued CLI session at the API that
+issued it, then clears the local credentials and workspace. If the API is offline,
+the local logout still completes and warns that server revocation was not confirmed.
+Imported PATs (`--token`), tokens saved by older CLI versions, and credentials shared
+with another profile are only cleared locally; revoke them in the dashboard when
+they are no longer needed. Shell environment variables are never removed by logout.
+`inquir logout --env staging` leaves the default profile intact and prevents the
+logged-out profile from inheriting its credentials again.
 
 > A PAT can deploy to **any workspace you belong to**. A workspace-scoped **API
 > key** is pinned to a single workspace and ignores workspace switching.
@@ -106,39 +117,45 @@ inquir whoami --workspace acme-prod
 ```
 
 Under the hood, user-scoped credentials send an `X-Inquir-Workspace` header; the
-server verifies your membership before honoring it.
-
-## Application projects
-
-Projects group long-lived container applications inside a workspace: web services,
-APIs, databases, and workers. Serverless functions are managed separately and cannot
-be added to these projects. A new application creates a project named after itself
-unless you select an existing project:
-
-```bash
-inquir projects list
-inquir projects create shop
-inquir projects use shop
-inquir apps create api --port 3000
-inquir apps create db --template postgres --project shop
-inquir projects add shop existing-app
-inquir projects current
-inquir projects use --clear
-```
-
-`projects use` saves the selection for the current directory, or the nearest
-`inquir.config.json` root. Use `--cwd <path>` to select another directory. The
-selection is kept locally under `~/.inquir/project-contexts` and isolated by API,
-the actual workspace, and signed-in user (or API key). Switching workspace or
-account therefore cannot silently reuse another context's project.
-
-`apps create --project <id|slug>` overrides the selection for one command.
-`projects use --clear` returns to automatic project creation. Selecting or adding
-to a project accepts its ID or slug; adding an application accepts its ID or name.
-All project commands support `--json`. Deploying an existing container application
-with `apps deploy` keeps its project membership; use `projects add` to file an
-existing application. This selection does not change the serverless `inquir deploy`
-workflow or local source/configuration project discovery.
+server verifies your membership before honoring it.
+
+## Application projects
+
+Projects group long-lived container applications inside a workspace: web services,
+APIs, databases, and workers. Serverless functions are managed separately and cannot
+be added to these projects. A new application creates a project named after itself
+unless you select an existing project:
+
+```bash
+inquir projects list
+inquir projects create shop
+inquir projects use shop
+inquir apps create api --port 3000
+inquir apps create db --template postgres --project shop
+inquir projects add shop existing-app
+inquir projects move shop db        # file it in shop, take it out of its other projects
+inquir projects remove shop old-api # unfile it; it keeps running
+inquir projects current
+inquir projects use --clear
+```
+
+`projects use` saves the selection for the current directory, or the nearest
+`inquir.config.json` root. Use `--cwd <path>` to select another directory. The
+selection is kept locally under `~/.inquir/project-contexts` and isolated by API,
+the actual workspace, and signed-in user (or API key). Switching workspace or
+account therefore cannot silently reuse another context's project.
+
+`apps create --project <project>` overrides the selection for one command.
+`projects use --clear` returns to automatic project creation. Every project command
+accepts a project's ID, slug, or unique display name, and an application's ID or
+name. `apps create` prints the project an application landed in. All project
+commands support `--json`. Deploying an existing container application with
+`apps deploy` keeps its project membership. `projects add` files an application in
+one more project; `projects move` files it and takes it out of every other one.
+No project command archives a project: the API does not record which were created
+automatically, so an emptied one is reported and left for you to archive in the
+dashboard. This selection does not change the serverless `inquir deploy`
+workflow or local source/configuration project discovery.
 
 ## Deploy a function (remote)
 
@@ -177,7 +194,7 @@ OIDC auth), or run `inquir deploy --ci`.
 **Auth & workspaces**
 
 - `inquir login` - authenticate the CLI (browser pairing, `--browserless`, or `--token`).
-- `inquir logout` - remove the stored token + active workspace for the current environment.
+- `inquir logout` - revoke the current browser-issued CLI session and clear its local credentials and workspace.
 - `inquir whoami` - show the signed-in user, active workspace, and role.
 - `inquir workspaces` - list the workspaces you belong to.
 - `inquir use <slug|id> [--local]` - set the active workspace; `--local` links *this project* by writing `workspace` into `inquir.config.json`.
@@ -214,6 +231,9 @@ runtime adapter involved.
 - `inquir apps domain <app> [hostname] [--verify|--remove]` - bind a custom hostname; publish the printed TXT record and point DNS at the platform, then `--verify`.
 - `inquir apps delete <app> --yes` - archive an application (stops every release, unbinds every hostname).
 
+Project archive in the dashboard also archives every application in the project, including applications shared with another project. It requires production permissions (`projects:write` and `apps:promote`). Clearing the local project selection with `inquir projects use --clear` only changes where future applications are created; it does not archive applications.
+
+
 ```bash
 # an HTTP service built from the Dockerfile in the current directory
 inquir apps create web --port 3000
@@ -239,9 +259,14 @@ TCP port is reachable by anyone who can reach the host: the platform
 terminates no TLS and checks no credentials on raw TCP, so the service must
 authenticate its own clients.
 
+`--drain-grace <seconds>` (`create`, `deploy`, `update`; 0–3600) — the time the
+old container gets after SIGTERM before it is killed (`runtimeSpec.drainGraceSeconds`).
+Like `--memory` or `--cpu` it is saved on the application by `create`/`update`
+and carried into every release built from the saved runtime.
+
 **Databases**
 
-- `inquir apps create <name> --template postgres|redis` - create a database: image, persistent volume, pinned public TCP port, generated password and its first release, in one command.
+- `inquir apps create <name> --template postgres|redis` - create a database: image, persistent volume, private TCP port, generated password and its first release, in one command. Add `--volume-runner <runner>` to keep its data and container on a worker; the worker runs the operator's digest-pinned mirror of the template image, and without one the create is refused (`APP_TEMPLATE_IMAGE_NOT_MIRRORED`).
 - `inquir apps connection-url <db>` - print the live connection URL, credentials included (it lands in your shell history).
 - `inquir apps connect <db> <app>` - write that URL into another application's env as `DATABASE_URL` / `REDIS_URL` without it passing through your terminal; it applies on that application's next release.
 - `inquir apps backups <app> [list|create|restore <id>|delete <id>]` - volume snapshots. `restore` **overwrites the volume** with the snapshot and stops the application while it runs, so it asks for confirmation — pass `--yes` in a script.
@@ -280,6 +305,16 @@ failing later on a changed wire contract.
 - `inquir config [show|get <key>|set <key> <value>|path]` - view/edit CLI configuration.
 - `inquir help [command]` - show grouped help, or help for one command.
 
+**Platform operators**
+
+- `inquir admin cluster [status|hold|release|move <memberId>|host register|grant <host> <capability>|revoke <host> <capability>]` -
+  the multi-master control plane (docs/roadmap/R4_MULTI_MASTER.md §6.2). It authenticates with the platform admin token in
+  `INQUIR_ADMIN_TOKEN`, never with your login; changes need the full token and land in the admin audit log.
+- `inquir admin allocations relocate <allocationId> --reason <text> [--target <runnerId>]` - move one serving replica
+  make-before-break: its replacement starts (on the target, which must pass every placement filter and have room), takes
+  the traffic, and only then is the replica stopped. Pinned, volume, preview and TCP-pinned replicas are refused, as is an
+  application in a deployment handoff. `inquir admin allocations relocation <operationId>` shows where it is. Same token.
+
 ### `deploy` flags
 
 ```bash
@@ -394,23 +429,23 @@ wins):
    - `INQUIR_ENV` — pick a named environment
 3. Selected environment in the config file
 4. Project link — `workspace` in the local `inquir.config.json` (set by `inquir use --local`); applies to the workspace only, below flags/env
-5. Top-level config file values (credentials and workspace only when the named environment uses the same API)
-6. Default `apiUrl` of `https://api.inquir.org` (override with env/config for local dev)
-
-A named environment with its own different API does not inherit the default
-token, API key, cached identity, or workspace. Partial profiles using the same API
-can still inherit defaults. Explicit flags and environment variables keep the
-precedence above. An unknown environment name fails before a remote command;
-`inquir login --env <name>` can create it.
-
-When login changes the default API, existing named profiles that inherited that
-API and contain credentials, a workspace, or cached identity retain their previous
-API binding. Their stored credentials are preserved. A profile that previously
-inherited its credentials may need its own login after this change. Empty profiles
-continue to inherit defaults. Changing a profile's API also removes its stored API
-key, so logging out of the new PAT cannot reactivate a key from the previous API.
-
-When both a `token` (PAT) and an `apiKey` are present, the PAT wins. The active
+5. Top-level config file values (credentials and workspace only when the named environment uses the same API)
+6. Default `apiUrl` of `https://api.inquir.org` (override with env/config for local dev)
+
+A named environment with its own different API does not inherit the default
+token, API key, cached identity, or workspace. Partial profiles using the same API
+can still inherit defaults. Explicit flags and environment variables keep the
+precedence above. An unknown environment name fails before a remote command;
+`inquir login --env <name>` can create it.
+
+When login changes the default API, existing named profiles that inherited that
+API and contain credentials, a workspace, or cached identity retain their previous
+API binding. Their stored credentials are preserved. A profile that previously
+inherited its credentials may need its own login after this change. Empty profiles
+continue to inherit defaults. Changing a profile's API also removes its stored API
+key, so logging out of the new PAT cannot reactivate a key from the previous API.
+
+When both a `token` (PAT) and an `apiKey` are present, the PAT wins. The active
 `workspaceId` is only applied to user-scoped credentials (PAT/session); for a
 workspace-scoped API key it is ignored unless you pass `--workspace` explicitly.
 
@@ -419,6 +454,13 @@ Config file locations:
 - `~/.inquir/config.json` (preferred, written by `inquir login` / `use`; saved with `0600` permissions)
 - `~/.lambda-cli/config.json` (legacy fallback — **credentials only**; the legacy `apiUrl` is intentionally ignored so you aren't silently pinned to `localhost`)
 
+Credential updates use an atomic file replacement and an exclusive
+`~/.inquir/config.json.lock` while updating or revoking a session. A timed-out lock
+is never stolen from a running command. If a command crashed and subsequent commands
+report `AUTH_CONFIG_LOCKED`, stop all CLI commands before removing that lock file.
+Older CLI versions do not participate in this locking protocol; avoid running old
+and new versions concurrently against the same configuration.
+
 Example (written/managed by `inquir login`, `inquir use`, `inquir logout`):
 
 ```json
@@ -455,56 +497,123 @@ failing check.
 ## Publishing to npm (maintainers)
 
 The CLI (`@inquir/compute-cli`) depends on the SDK (`@inquir/compute`), so the
-SDK must be published **first** at a version satisfying the CLI's dependency
-range (`dependencies["@inquir/compute"]`, `^0.3.0` for CLI 0.3.0). Set the lower
-bound to the first SDK release containing every API the CLI imports. A workspace
-build uses the local SDK and cannot prove that an older published SDK works.
-
-New `inquir init` scaffolds inherit this SDK range and require Node.js 22+.
-Existing `package.json` files are preserved; update their dependencies explicitly
-when adopting a newer SDK.
+SDK must be published **first** at a version satisfying the CLI's dependency
+range (`dependencies["@inquir/compute"]`, `^0.4.0` for CLI 0.4.0). Set the lower
+bound to the first SDK release containing every API the CLI imports. A workspace
+build uses the local SDK and cannot prove that an older published SDK works.
+
+Release order for 0.4.0: CLI 0.4.0 imports `isPromoteAccepted` and
+`getApplicationRollout` (the background promote, `inquir apps promote`), which
+SDK 0.3.0 does not export. Publish SDK 0.4.0 first and confirm it on the
+registry; a CLI published against SDK 0.3.0 would fail at startup.
+
+New `inquir init` scaffolds inherit this SDK range and require Node.js 22+.
+Existing `package.json` files are preserved; update their dependencies explicitly
+when adopting a newer SDK.
 
 Prerequisites:
 
 - An npm account with publish access to the `@inquir` scope (create the org/scope on npmjs.com), then `npm login`.
 - Both packages declare `"publishConfig": { "access": "public" }`, so scoped packages publish publicly.
-- Both packages build before packing or publishing from source. The SDK includes
-  `dist/`; the CLI includes `dist/` and its bundled `skill/`. npm also includes
-  package metadata and README files.
-- Choose unused release versions, update the CLI's SDK dependency and the lockfile,
-  then run the SDK and CLI tests before preparing the release candidate.
-
-Prepare the exact tarballs from the repo root:
-
-```bash
-# Cleans and builds the SDK first, then the CLI.
-npm run build --workspace @inquir/compute-cli
-# Reuse the verified build instead of rebuilding during packing.
-npm pack --workspace @inquir/compute --ignore-scripts
-npm pack --workspace @inquir/compute-cli --ignore-scripts
-```
-
-Install both tarballs into a temporary directory outside this repository. Check
-`npm ls @inquir/compute`, `inquir --version`, `inquir --help`, project commands,
-and a local TypeScript function run. Resolve packages from that installation,
-without workspace links, so the smoke test exercises the files users receive.
-
-Publish those tested tarballs in order (0.3.0 shown; use the chosen versions):
-
-```bash
-npm publish ./inquir-compute-0.3.0.tgz --access public
-# Confirm this SDK version is available from the registry before publishing CLI.
-npm view @inquir/compute@0.3.0 version
-npm publish ./inquir-compute-cli-0.3.0.tgz --access public
-```
-
-After building, preview package contents without publishing with
-`npm pack --dry-run --json --ignore-scripts --workspace @inquir/compute-cli`.
-`--ignore-scripts` skips build hooks, so only use it after the explicit build.
-The installed command is `inquir`, from `dist/index.js` with its Node shebang.
-After publishing, users can install it with:
+- Both packages build before packing or publishing from source. The SDK includes
+  `dist/`; the CLI includes `dist/` and its bundled `skill/`. npm also includes
+  package metadata and README files.
+- Choose unused release versions, update the CLI's SDK dependency and the lockfile,
+  then run the SDK and CLI tests before preparing the release candidate.
+
+Prepare the exact tarballs from the repo root:
+
+```bash
+# Cleans and builds the SDK first, then the CLI.
+npm run build --workspace @inquir/compute-cli
+# Reuse the verified build instead of rebuilding during packing.
+npm pack --workspace @inquir/compute --ignore-scripts
+npm pack --workspace @inquir/compute-cli --ignore-scripts
+```
+
+Install both tarballs into a temporary directory outside this repository. Check
+`npm ls @inquir/compute`, `inquir --version`, `inquir --help`, project commands,
+and a local TypeScript function run. Resolve packages from that installation,
+without workspace links, so the smoke test exercises the files users receive.
+
+Publish those tested tarballs in order (0.3.0 shown; use the chosen versions):
+
+```bash
+npm publish ./inquir-compute-0.3.0.tgz --access public
+# Confirm this SDK version is available from the registry before publishing CLI.
+npm view @inquir/compute@0.3.0 version
+npm publish ./inquir-compute-cli-0.3.0.tgz --access public
+```
+
+After building, preview package contents without publishing with
+`npm pack --dry-run --json --ignore-scripts --workspace @inquir/compute-cli`.
+`--ignore-scripts` skips build hooks, so only use it after the explicit build.
+The installed command is `inquir`, from `dist/index.js` with its Node shebang.
+After publishing, users can install it with:
 
 ```bash
 npm install -g @inquir/compute-cli@latest
 inquir --help
 ```
+## Application observability
+
+Read actual resource history for every release and replica, or HTTP gateway measurements:
+
+```sh
+inquir apps metrics api --since 6h
+inquir apps metrics api --since 30d --json
+inquir apps metrics api --http --since 1d --json
+```
+
+The resource table shows the latest point per replica in the selected window. JSON contains all returned points, their enforced CPU/RAM limits, network transfer rates, disk I/O rates and deployment markers. `null` means the measurement is unavailable; it is not zero. Disk I/O measures reads/writes, not occupied volume space. HTTP measurements cover gateway requests, including request counts, 5xx errors, response bytes and latency percentiles. Resource and HTTP history is retained for 30 days; resource points older than a day are rolled up to one per five minutes, and older than a week to one per hour, each keeping the bucket's last point plus its CPU and memory peak and mean. Inspect `status`, `latestSampleAt` and `truncated` in resource JSON before interpreting a range as current or complete.
+
+Ask what the CPU and memory figures could be, from what the production replicas actually used:
+
+```sh
+inquir apps resources recommend api
+inquir apps resources recommend api --days 3 --json
+```
+
+The recommendation is read-only. Memory is 1.2 × the peak working set in the window (default 7 days), at least 64 MB, at least 256 MB for a database, and never below the peak of the whole 30-day history plus 10%. The CPU limit follows the peak (1.5 ×, at least 0.1 vCPU); the reserved request shown is what the platform would reserve for that limit, next to the request the 95th percentile of five-minute averages alone would justify. A recommendation needs 24 hours of observed usage; `confidence` reports the days observed and the samples behind it, and `--json` adds each release (replica set) seen in the window. Apply one yourself with `inquir apps update api --memory <mb> --cpu <vcpus>` and `inquir apps redeploy api`.
+
+Persisted container logs remain readable after the container is replaced. Select an app and optionally an exact release or runtime identity:
+
+```sh
+inquir apps log-history api --since 1h --level error --json
+inquir apps logs api --history --release <release-id> --replica <allocation-id> --allocation-fence 4
+inquir apps log-history api --runner <runner-id> --runner-epoch 0 --container <full-container-id>
+inquir apps log-history api --http --since 7d --status 503 --search /api --json
+```
+
+History returns one page, newest first. Runtime retention is 7 days; HTTP retention is 30 days. Use `--limit` (up to 200 runtime rows or 500 HTTP rows) and `--cursor` for older pages. Always reuse the response's `from` and `to` as `--from`/`--to`, plus the same filters, when using a cursor. `apps logs api` without `--history` still follows the current release; `apps logs <build-id>` still reads build output.
+
+Configure alert rules using JSON files or stdin. Destinations are write-only and are omitted from command output:
+
+```sh
+inquir apps alerts api list --json
+inquir apps alerts api create --file cpu-alert.json
+inquir apps alerts api update <rule-id> --file patch.json
+inquir apps alerts api incidents --limit 25 --json
+inquir apps alerts api delete <rule-id>
+```
+
+Example `cpu-alert.json` (incident-only until a notification destination is configured):
+
+```json
+{
+  "name": "High CPU",
+  "enabled": true,
+  "metric": "cpu_percent",
+  "threshold": 85,
+  "forSeconds": 120,
+  "recoveryThreshold": 65,
+  "recoveryForSeconds": 60,
+  "noDataSeconds": 180,
+  "noData": "alert",
+  "channels": []
+}
+```
+
+Use `memory_percent` for RAM or `deployment_failed` for failed production deployments. CPU/RAM rules evaluate the continuous maximum across current production replicas; the hot replica can change during the hold period. Percentage thresholds refer to each container's enforced limit. For deployment events, timing and threshold fields do not control the failure trigger. Notification channels have the shape `{"type":"webhook","url":"https://your-endpoint.example/alerts"}` or `{"type":"slack","url":"https://hooks.slack.com/..."}`. Keep secret URLs in a file outside version control, or pipe JSON to `--file -`. The server must have secret encryption configured to accept notification channels.
+
+A patch such as `{"threshold":90}` keeps existing destinations. `{"channels":[]}` removes them. Deleting a rule disables it and resolves active incidents while preserving retained history. Incident results include notification delivery state and retry counts. All commands honor the existing `--workspace`, `--env`, `--api-url` and credential selection rules.

package/dist/commands/admin-tenants.d.ts

@@ -0,0 +1,11 @@
+export type AdminCall = (args: string[], request: {
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    path: string;
+    body?: Record<string, unknown>;
+}) => Promise<Record<string, unknown>>;
+export declare const TENANT_VALUE_FLAGS: string[];
+export declare const TENANT_USAGE: string[];
+export declare const TENANT_HELP: string[];
+export declare function tenantsCommand(args: string[], action: string | undefined, rest: string[], json: boolean, call: AdminCall): Promise<void>;
+export declare function containerdTenantsCommand(args: string[], action: string | undefined, rest: string[], json: boolean, call: AdminCall): Promise<void>;
+//# sourceMappingURL=admin-tenants.d.ts.map

package/dist/commands/admin-tenants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-tenants.d.ts","sourceRoot":"","sources":["../../src/commands/admin-tenants.ts"],"names":[],"mappings":"AAWA,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE;IAAE,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,KAC3I,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAEnC,eAAO,MAAM,kBAAkB,UAG9B,CAAC;AAEF,eAAO,MAAM,YAAY,UAMxB,CAAC;AAEF,eAAO,MAAM,WAAW,UAcvB,CAAC;AAiNF,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA0C9I;AAED,wBAAsB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CA8CxJ"}