@inquir/compute-cli 0.2.1 → 0.3.0

package/README.md

@@ -64,10 +64,24 @@ 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
-```
-
-Create and revoke PATs from the dashboard under **API Keys → Personal Access
+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`.
 
 > A PAT can deploy to **any workspace you belong to**. A workspace-scoped **API
@@ -92,7 +106,39 @@ 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.
+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.
 
 ## Deploy a function (remote)
 
@@ -158,13 +204,13 @@ runtime adapter involved.
 - `inquir apps deploy <app> [--image <ref>]` - start a release and wait until it is healthy. Without `--image` the current directory (or `--dir`) is built from its Dockerfile first; `--build <id>` releases an existing build.
 - `inquir apps build <app> [--dir <path>] [--dockerfile <f>] [--context <dir>] [--build-arg K=V]` - build an image from source without releasing it.
 - `inquir apps builds <app>` - build history (`--cancel <buildId>` drops a queued build).
-- `inquir apps status <app>` - endpoints, hostnames and recent releases.
+- `inquir apps status <app>` - endpoints (public and private), hostnames and recent releases. The `private:` lines are what another app in the workspace dials (`{slug}.apps.internal`, port per TCP service); they appear once the platform has verified the route.
 - `inquir apps logs <app|release|build> [--tail <n>]` - stream container (or build) logs.
 - `inquir apps promote <release>` - send production traffic to a release (needs a login, not an API key).
 - `inquir apps rollback <app>` - return production to the previous release.
 - `inquir apps stop <release>` - stop any release that is not serving production.
 - `inquir apps exec <app> -- <command>` - run a command inside the container (owner/admin login only — it can read every secret).
-- `inquir apps update <app> [--set K=V] [--port …] [--egress none|full] …` - change settings; applies to the next release.
+- `inquir apps update <app> [--set K=V] [--port …] [--egress none|full] [--ingress private|public] …` - change settings; applies to the next release. `--ingress public` creates the generated public domain, `--ingress private` removes it (the private address is unaffected). New apps are private unless created with `--ingress public`.
 - `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).
 
@@ -193,6 +239,26 @@ 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.
 
+**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 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.
+
+```bash
+inquir apps create mydb --template postgres
+inquir apps connect mydb web          # web gets DATABASE_URL on its next release
+inquir apps backups mydb create       # snapshot every volume, wait for it to settle
+inquir apps backups mydb restore 3f9c1a2b --yes
+```
+
+An application that declares a volume deploys by stopping its container before
+starting the new one, so two containers never write the same data — expect a
+short outage on every deploy. Backups are crash-consistent (the container is
+paused while it is copied) and need an artifact store configured on the
+deployment; without one the backup commands report that they are unavailable.
+
 **Staying up to date**
 
 The CLI keeps itself in step with the platform. On start it checks — at most
@@ -328,10 +394,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
-6. Default `apiUrl` of `https://api.inquir.org` (override with env/config for local dev)
-
-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.
 
@@ -376,35 +455,54 @@ 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"]`, currently `^0.1.0`).
+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.
 
 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.
-- Each package's `prepublishOnly` rebuilds `dist/` automatically; only `dist/` ships (`files: ["dist"]`).
-
-Steps (run from the repo root):
-
-```bash
-npm login
-
-# 1) Publish the SDK first — the CLI resolves it from the public registry.
-npm version <patch|minor|major> --workspace @inquir/compute
-npm publish --workspace @inquir/compute
-
-# 2) Publish the CLI. Ensure its @inquir/compute dependency range covers the
-#    SDK version you just published, then:
-npm version <patch|minor|major> --workspace @inquir/compute-cli
-npm publish --workspace @inquir/compute-cli
-```
-
-Tips:
-
-- Preview the exact tarball contents without publishing: `npm publish --dry-run --workspace @inquir/compute-cli`.
-- The published `bin` is `inquir` (from `dist/index.js`, which keeps its `#!/usr/bin/env node` shebang).
-- After publishing, anyone can install and deploy:
+- 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

package/dist/commands/apps.d.ts

@@ -1,13 +1,28 @@
-import { type AppPortSpec, type AppRuntimeSpec, type Release } from '../utils/api.js';
+import { type AppNetworkPolicy, type AppPortSpec, type AppRuntimeSpec, type AppScalingPolicy, type ApplicationDetail, type Release } from '../utils/api.js';
 export declare function appsCommand(args: string[]): Promise<void>;
 /**
- * `--tcp name:port[:public][:hostPort]` — the shorthand people actually want
- * to type for a database or SSH endpoint.
+ * `--tcp name:port[:public][:hostPort]` — ordinary usage stops at `public` and
+ * lets the platform lease a stable endpoint port. The final numeric modifier
+ * remains an API/CLI compatibility escape hatch for an existing installation.
  */
 export declare function parseTcpPortFlag(value: string): AppPortSpec;
 export declare function parseSetFlags(values: string[]): Record<string, string>;
-/** Runtime spec assembled from flags; undefined when nothing was specified. */
-export declare function buildRuntimeFromFlags(args: string[]): AppRuntimeSpec | undefined;
+/** Parse a CLI duration such as `90`, `90s`, `15m`, `1h30m`, or `1.5m`. */
+export declare function parseDurationSeconds(value: string): number;
+/** Build the partial policy sent by `apps scale`; omitted values remain unchanged server-side. */
+export declare function buildScalingPatchFromFlags(args: string[], positionalActivation?: string): Partial<AppScalingPolicy>;
+type AppVolumeSpec = NonNullable<AppRuntimeSpec['volumes']>[number];
+/** `--volume name:/absolute/container/path[:ro]`; host paths are never accepted. */
+export declare function parseVolumeFlag(value: string): AppVolumeSpec;
+/** Runtime flags patch the saved application runtime rather than replacing unrelated fields. */
+export declare function buildRuntimeFromFlags(args: string[], baseRuntime?: AppRuntimeSpec): AppRuntimeSpec | undefined;
+export declare function selectConnectionUrl(result: {
+    url?: string;
+    publicUrl?: string;
+}, preference?: 'auto' | 'private' | 'public'): {
+    url: string;
+    visibility: 'private' | 'public';
+};
 /**
  * Where a client can actually connect. Public endpoints first; a host-local
  * port is still printed (marked as such) because on an installation with no
@@ -16,6 +31,28 @@ export declare function buildRuntimeFromFlags(args: string[]): AppRuntimeSpec |
 export declare function releaseEndpointLines(release: Release, previewUrl?: string, options?: {
     includeHostLocal?: boolean;
 }): string[];
+/**
+ * Where same-workspace services reach this application. The server projects
+ * `privateDomain` only once the private route is verified end to end, so a
+ * missing domain on an installation with private networking means "still
+ * being reconciled", not "no such thing" — and that is worth a line too.
+ */
+export declare function privateEndpointLines(detail: Pick<ApplicationDetail, 'privateDomain' | 'privateBaseUrl'>, active: Pick<Release, 'ports'> | undefined, options?: {
+    privateNetworking?: boolean;
+}): string[];
+/**
+ * The networkPolicy patch for `--egress` / `--ingress`. The API requires
+ * egress inside networkPolicy, so a lone --ingress change carries the
+ * application's current egress along unchanged, and vice versa; with neither
+ * flag the policy is left alone (the server's defaults apply on create).
+ */
+export declare function buildNetworkPolicyPatch(input: {
+    egress?: string;
+    ingress?: string;
+    current?: AppNetworkPolicy;
+}): AppNetworkPolicy | undefined;
 /** A build-sourced release is best named by its build; a pulled one by its ref. */
 export declare function describeImage(release: Pick<Release, 'imageSource' | 'buildId' | 'imageRef' | 'imageDigest'>): string;
+export declare function describeScalingPolicy(policy: AppScalingPolicy): string;
+export {};
 //# sourceMappingURL=apps.d.ts.map

package/dist/commands/apps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"AAEA,OAAO,EAyBL,KAAK,WAAW,EAChB,KAAK,cAAc,EAGnB,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AAgCzB,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA8C/D;AAqDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA6B3D;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUtE;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,cAAc,GAAG,SAAS,CAuChF;AA+PD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,MAAM,EAAE,CAwBV;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC,GAAG,MAAM,CAGpH"}
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/commands/apps.ts"],"names":[],"mappings":"AASA,OAAO,EAoCL,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,cAAc,EAEnB,KAAK,gBAAgB,EAErB,KAAK,iBAAiB,EAGtB,KAAK,OAAO,EAEb,MAAM,iBAAiB,CAAC;AAsDzB,wBAAsB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAoE/D;AA6ED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,WAAW,CA6B3D;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUtE;AAKD,2EAA2E;AAC3E,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgC1D;AAgCD,kGAAkG;AAClG,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EAAE,EACd,oBAAoB,CAAC,EAAE,MAAM,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAuD3B;AAED,KAAK,aAAa,GAAG,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAKpE,oFAAoF;AACpF,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CA2D5D;AAiCD,gGAAgG;AAChG,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EAAE,EACd,WAAW,CAAC,EAAE,cAAc,GAC3B,cAAc,GAAG,SAAS,CAmD5B;AAubD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5C,UAAU,GAAE,MAAM,GAAG,SAAS,GAAG,QAAiB,GACjD;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,SAAS,GAAG,QAAQ,CAAA;CAAE,CAcnD;AA+TD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,OAAO,EAChB,UAAU,CAAC,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,MAAM,EAAE,CAwBV;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,GAAG,gBAAgB,CAAC,EACnE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,GAAG,SAAS,EAC1C,OAAO,GAAE;IAAE,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC5C,MAAM,EAAE,CAaV;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B,GAAG,gBAAgB,GAAG,SAAS,CAe/B;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,aAAa,GAAG,SAAS,GAAG,UAAU,GAAG,aAAa,CAAC,GAAG,MAAM,CAGpH;AAgCD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAMtE"}