@di-framework/tenant-cli 0.0.0-stage → 6.0.10

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @di-framework/tenant-cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pilot of the tenant CLI that never speaks Kubernetes. It holds one credential per account, an
+identity-server token or a tenant API key, and every action is a call to the tenant controller's
+OpenAPI contract. Kubeconfigs exist only inside the controller. The cut-over criterion and the
+command set are platform issue #40; the prototype it starts from is `../tenant-auth`.
+
+## The contract is the shared artifact
+
+`api/v1/openapi.yaml` is committed and generated, never edited:
+
+```text
+src/api/contracts/*-v1.codegen.ts   manifests (operations, paths, schemas)
+src/api/schemas.ts                  JSON schemas published under components.schemas
+src/api/handlers.ts                 the server side; every operation answers 501 in the pilot
+src/api/generated/**                @di-framework/codegen output: typed routes and validators
+api/v1/openapi.yaml                 emitted from the generated @Endpoint metadata
+src/client/schema.d.ts              openapi-typescript output
+src/client/index.ts                 the typed client; its paths are checked against `paths`
+src/client/sse.ts                   the one hand-written transport: text/event-stream framing
+```
+
+```sh
+bun run generate        # di-framework generate, then the document, then the client types
+bun test                # includes a drift check: the committed document must match the manifests
+```
+
+An operation added to a manifest shows up in the document and in `paths`; a path the client
+references that is no longer in the contract fails `tsc`. That is the whole drift story.
+
+Streaming operations (`logs`) are SSE: each `log` event's `data` is one `LogEvent` as JSON, and
+`end` closes the stream. The spec names this in the operation description; the framing itself is
+`src/client/sse.ts`.
+
+## Using the client
+
+`@di-framework/tenant-cli/client` is the published entry point: the typed `/v1` client
+(`createClient`, `ControllerError`, `events`, and the request/response types). It ships compiled
+(`dist`, with `.d.ts`), so consumers need no `.ts` import support. The package also installs the
+`di-tenant` command, which requires Bun (its shebang is `bun`).
+
+The `./src/api/*` export is workspace-internal: `../tenant-auth` uses it inside this repository, and it
+is not usable from the npm package (`src` is not published).
+
+```ts
+import { createClient } from '@di-framework/tenant-cli/client';
+
+const info = await createClient({ baseUrl: 'https://controller.example' }).authInfo();
+```
+
+`api/v1/openapi.yaml` ships alongside as the contract. `bun run build` produces `dist`.
+
+## Registry
+
+Each tenant gets its own OCI registry component in its namespace (platform#83, decision in
+platform#52). Nothing is minted: you log in to the registry with your own identity. Use your
+identity-server access token or a `dik_` API key as the Basic password (the username is ignored).
+The registry asks the tenant controller's `GET /v1/auth/whoami` who the caller is: a developer may
+push and pull, a viewer may only pull.
+
+`GET /v1/deploy/registry` (viewer or developer) returns `RegistryInfo`: the registry `url` (an
+origin: scheme + host[:port], no path), an optional `repositoryPrefix`, `auth` (`basic-identity`)
+and a fixed `username` hint (`token`). The tenant controller reads the origin from
+`TENANT_CONTROLLER_REGISTRY_URL` (`{tenant}` is replaced by the tenant), which the platform sets
+when its `tenantAuth.registry` config is present; otherwise the endpoint answers 503
+`no registry is configured for this tenant`. While a registry is configured but not served (a
+host conflict or a suspended tenant) it answers 503 `the tenant registry is not available; see
+the Tenant's TenantAuthReady condition`. The origin must be `https://`; plain `http://` is
+accepted only for loopback (`localhost`, `127.0.0.0/8`, `[::1]`) and in-cluster hosts (`*.svc`,
+`*.svc.cluster.local`).
+
+Log in against the host of `url`, not the full URL, then push to
+`<host>/<repositoryPrefix>/<name>:<tag>`:
+
+```text
+oras login <host>
+docker login <host>
+oras push <host>/<repositoryPrefix>/<name>:<tag> ...
+```
+
+An `http:` origin means plain HTTP (loopback or in-cluster only): pass `oras --plain-http` or
+`wash --insecure`. The platform serves the registry over HTTPS through the gateway, since the Basic
+password is an identity credential. Its certificate is the tenant controller's, so trust the
+tenant's CA (ConfigMap `tenant-controller-ca`) as you do for the controller, for example
+`oras login --ca-file` or `/etc/docker/certs.d/<host>/ca.crt`.
+
+Identity access tokens expire, so a stored `docker login` stops working; a `dik_` API key suits CI.
+
+### Which reference a workload uses
+
+Push to the registry's public origin (`url` above), but reference the same repository on the
+in-cluster pull host in the workload you deploy: tenant hosts pull from
+`tenant-registry.di-runtime-<tenant>.svc` (no port), with a platform-managed pull credential, not
+from the public origin, which is a gateway or port-forward address the hosts cannot use. Both
+names serve the same repositories:
+
+```text
+oras push registry.acme.localhost:28180/web:1.0.0 ...            # push (your credential)
+# workload component image:
+tenant-registry.di-runtime-acme.svc/web@sha256:<digest>           # pull (the tenant's hosts)
+```
+
+`/v1/deploy` and `/v1/deploy/preview` refuse (`422`) a bundle whose component or service image
+names the public origin, and the problem `detail` gives the in-cluster reference to use instead.
+
+## Commands
+
+```text
+login --controller <url> [--account <tenant>] [--api-key <key>]
+logout | whoami
+deploy preview|apply --env <prod|staging> --bundle <file>
+logs --service <name> --env <env> [--deployment <id>] [--follow] [--since <dur>] [--tail <n>]
+services create <keyvalue|messaging|blobstore|postgres|egress> --name <name> --env <env> [--class] [--storage] [--memory] [--cpu] [--deletion-policy] [--destination]
+deployments list|stats --env <env> [--service <name>]
+deployments rollback --service <name> --env <env> [--to <id>]
+secrets|vars list|set|update|unset <name> --env <env> [--from-file <path|->]
+proxy --service <name> --env <env> [--port <n>]
+init [name] [--dir <path>] [--name <name>] [--force]
+```
+
+Shared flags: `--env`, `--json`, `--account` (or `DI_TENANT_ACCOUNT`, or the only login on disk).
+There is no token argument. Secret and var values come from `--from-file` or stdin (`-`), so they
+stay out of shell history. `init` writes a minimal di-framework seed and creates no platform
+resources.
+
+## Login
+
+`login --controller <url>` asks the controller's one public operation (`GET /v1/auth/info`) for
+the account, the identity issuer, and the public client id, then runs the RFC 8252 flow: a
+loopback listener on a free port is the redirect URI, the browser signs in at the issuer, and the
+code comes back with the PKCE verifier and `client_id` only, no secret. The identity server must
+register that client (`AUTH_CLI_CLIENT_ID`; loopback redirects match on any port). The tokens are
+stored under `$DI_FRAMEWORK_HOME/credentials.json` with the issuer and client id; a token within a
+minute of expiry is refreshed before the next command, and `logout` revokes the refresh token at
+the issuer and tells the controller. `--api-key` skips the browser; `--no-browser` prints the URL
+instead of opening it.
+
+## What the pilot does not do yet
+
+- Building the component and rendering the bundle: `deploy` sends a bundle file. The CLI-side
+  build that produces it is shared with `cli-plugin-platform` and is the next step.
+- The controller: `../tenant-auth` serves `services create` and `services proxy`; operations it
+  does not implement yet answer 501. The controller grows the endpoints behind this contract, importing the generated routes from `src/api/generated`.
+- The `proxy` session URL is an HTTP passthrough the controller serves outside the document (`/v1/services/<service>/proxy/<session>/...`); WebSocket is not supported yet. The session URL takes its origin from the Host the caller reached (the controller has no configured public URL); the passthrough uses a 60 s idle timeout, keeps relative `Location` redirects under the session URL, and marks every request as external with `X-Forwarded-*` so workload control paths stay closed. It sends `Host: <service>-<env>` (the session's env), the host the deploy lane sets as `config.host` on the bundle's `wasi:http` host interface; a bundle must leave `config.host` out or set it to that value.

package/api/v1/openapi.yaml

@@ -0,0 +1 @@
+{openapi: 3.1.0,info: {title: Tenant Controller API,version: v1,description: The only surface a tenant CLI talks to. Every call carries an identity-server credential; the controller holds the kubeconfig and never exposes Kubernetes.},paths: {/v1/auth/info: {get: {summary: Describe how to log in,description: The account this controller serves and the identity server to obtain a credential from. The only unauthenticated operation.,operationId: authInfo,responses: {"200": {description: Describe how to log in,content: {application/json: {schema: {type: object,description: "What a CLI needs before it holds a credential: the account this controller serves and the identity server to log in with.",properties: {account: {type: string},issuer: {type: string,format: uri},clientId: {type: string}},required: [account,issuer,clientId]}}}}}}},/v1/auth/logout: {post: {summary: Revoke the credential,description: Revokes the bearer token at the identity server (or the API key) so it stops working everywhere.,operationId: logout,requestBody: {content: {application/json: {schema: {type: object}}},required: false},responses: {"204": {description: Revoke the credential}},security: [{identity: []}]}},/v1/auth/whoami: {get: {summary: Resolve the caller,description: "The user, role, and credential the bearer token stands for in this account.",operationId: whoami,responses: {"200": {description: Resolve the caller,content: {application/json: {schema: {type: object,properties: {user: {type: string},account: {type: string},role: {type: string,enum: [developer,viewer]},via: {type: string,enum: [identity,api-key]},credentialId: {type: string}},required: [user,account,role,via]}}}}},security: [{identity: []}]}},/v1/deploy: {post: {summary: Apply a deployment,description: Validates the bundle and starts the rollout. Progress is streamed by the logs operation of the service.,operationId: deploy,requestBody: {content: {application/json: {schema: {type: object,description: Everything the CLI renders client-side. The controller validates it at the boundary and never receives a kubeconfig or a namespace.,properties: {env: {type: string,enum: [prod,staging]},service: {type: string,description: Service the deployment belongs to.},component: {$ref: "#/components/schemas/ComponentReference"},workload: {type: object,description: "The rendered WorkloadDeployment template, without namespace or host selector.",additionalProperties: true},bindings: {type: array,items: {$ref: "#/components/schemas/Binding"}},secrets: {type: array,description: Names of tenant secrets the workload references; values never travel.,items: {type: string}}},required: [env,service,component,workload,bindings,secrets]}}},required: true},responses: {"202": {description: Apply a deployment,content: {application/json: {schema: {type: object,properties: {id: {type: string},service: {type: string},env: {type: string,enum: [prod,staging]},status: {type: string,enum: [pending,rolling,ready,failed,rolled-back]},component: {$ref: "#/components/schemas/ComponentReference"},createdAt: {type: string,format: date-time},readyAt: {type: string,format: date-time}},required: [id,service,env,status,component,createdAt]}}}}},security: [{identity: []}]}},/v1/deploy/preview: {post: {summary: Preview a deployment,description: "Validates the bundle and reports what applying it would change in the given environment, without changing anything.",operationId: previewDeploy,requestBody: {content: {application/json: {schema: {type: object,description: Everything the CLI renders client-side. The controller validates it at the boundary and never receives a kubeconfig or a namespace.,properties: {env: {type: string,enum: [prod,staging]},service: {type: string,description: Service the deployment belongs to.},component: {$ref: "#/components/schemas/ComponentReference"},workload: {type: object,description: "The rendered WorkloadDeployment template, without namespace or host selector.",additionalProperties: true},bindings: {type: array,items: {$ref: "#/components/schemas/Binding"}},secrets: {type: array,description: Names of tenant secrets the workload references; values never travel.,items: {type: string}}},required: [env,service,component,workload,bindings,secrets]}}},required: true},responses: {"200": {description: Preview a deployment,content: {application/json: {schema: {type: object,description: What applying the bundle would change.,properties: {env: {type: string,enum: [prod,staging]},service: {type: string},changes: {type: array,items: {$ref: "#/components/schemas/DeployChange"}}},required: [env,service,changes]}}}}},security: [{identity: []}]}},/v1/deploy/registry: {get: {summary: Get the tenant registry,description: "The tenant's own OCI registry: its URL and how to log in. Pull is open to viewers and developers; push needs developer. No credential is minted.",operationId: registry,responses: {"200": {description: Get the tenant registry,content: {application/json: {schema: {type: object,description: "Where a tenant pushes and pulls images: the tenant's own OCI registry. Log in with an identity-server access token or API key as the Basic password.",properties: {url: {type: string,format: uri,description: "Origin of the tenant's OCI registry: scheme + host[:port], no path. Clients use its host[:port] for login and in image references; an http: origin means plain HTTP."},repositoryPrefix: {type: string,description: "Namespace inside the tenant registry, when there is one."},auth: {type: string,enum: [basic-identity],description: Basic auth whose password is an identity-server access token or dik_ API key.},username: {type: string,description: A fixed hint for the Basic username; the registry ignores it.}},required: [url,auth,username]}}}}},security: [{identity: []}]}},/v1/deployments: {get: {summary: List deployments,description: "Deployments of the environment, newest first, optionally for one service.",operationId: deployments,responses: {"200": {description: List deployments,content: {application/json: {schema: {type: object,properties: {items: {type: array,items: {$ref: "#/components/schemas/Deployment"}}},required: [items]}}}}},parameters: [{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}},{name: service,in: query,required: false,schema: {type: string}}],security: [{identity: []}]}},/v1/deployments/stats: {get: {summary: Summarize deployments,operationId: deploymentStats,responses: {"200": {description: Summarize deployments,content: {application/json: {schema: {type: object,properties: {env: {type: string,enum: [prod,staging]},services: {type: integer,format: int32},deployments: {type: integer,format: int32},ready: {type: integer,format: int32},failed: {type: integer,format: int32},lastDeployedAt: {type: string,format: date-time}},required: [env,services,deployments,ready,failed]}}}}},parameters: [{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]}},/v1/deployments/rollback: {post: {summary: Roll a service back,description: "Starts a rollout of an earlier deployment, the previous one unless `to` names it.",operationId: rollback,requestBody: {content: {application/json: {schema: {type: object,properties: {env: {type: string,enum: [prod,staging]},service: {type: string},to: {type: string,description: Deployment id to roll back to; the previous one when absent.}},required: [env,service]}}},required: true},responses: {"202": {description: Roll a service back,content: {application/json: {schema: {type: object,properties: {id: {type: string},service: {type: string},env: {type: string,enum: [prod,staging]},status: {type: string,enum: [pending,rolling,ready,failed,rolled-back]},component: {$ref: "#/components/schemas/ComponentReference"},createdAt: {type: string,format: date-time},readyAt: {type: string,format: date-time}},required: [id,service,env,status,component,createdAt]}}}}},security: [{identity: []}]}},/v1/secrets: {get: {summary: List secrets,description: Names and update times only; secret values are never returned.,operationId: secrets,responses: {"200": {description: List secrets,content: {application/json: {schema: {type: object,properties: {env: {type: string,enum: [prod,staging]},items: {type: array,items: {$ref: "#/components/schemas/SecretEntry"}}},required: [env,items]}}}}},parameters: [{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]}},"/v1/secrets/{name}": {put: {summary: Set a secret,description: Creates or replaces the secret. The CLI reads the value from a file or stdin so it stays out of shell history.,operationId: setSecret,requestBody: {content: {application/json: {schema: {type: object,properties: {value: {type: string}},required: [value]}}},required: true},responses: {"204": {description: Set a secret}},parameters: [{name: name,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]},delete: {summary: Unset a secret,operationId: unsetSecret,responses: {"204": {description: Unset a secret}},parameters: [{name: name,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]},patch: {summary: Update a secret,description: Replaces the value of an existing secret; 404 when it does not exist.,operationId: updateSecret,requestBody: {content: {application/json: {schema: {type: object,properties: {value: {type: string}},required: [value]}}},required: true},responses: {"204": {description: Update a secret}},parameters: [{name: name,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]}},/v1/services: {post: {summary: Create a backing service,description: "Creates a keyvalue, messaging, blobstore, postgres or egress backing service in the environment as the caller. http, cron and worker services come from the deploy bundle.",operationId: createService,requestBody: {content: {application/json: {schema: {type: object,description: "A backing service (BackingService) in the environment, shaped like `di-framework platform service create`. `destinations` is required for egress and only allowed there. http, cron and worker services come from the deploy bundle, not from this operation.",properties: {env: {type: string,enum: [prod,staging]},type: {type: string,enum: [keyvalue,messaging,blobstore,postgres,egress]},name: {type: string,description: "DNS label, at most 40 characters: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`."},className: {type: string,description: "The platform default class for the type when absent (keyvalue-redis, messaging-nats, blobstore-nats, postgres-dedicated, egress-public); any other class is refused."},parameters: {type: object,description: "Sizing quantities such as `1Gi` or `500m`.",properties: {storage: {type: string},memory: {type: string},cpu: {type: string}},additionalProperties: false},deletionPolicy: {type: string,enum: [Retain,Delete]},destinations: {type: array,items: {type: string},description: "Egress only: hosts the workload may reach (`host`, `*.suffix`, optionally `:port`)."}},required: [env,type,name]}}},required: true},responses: {"201": {description: Create a backing service,content: {application/json: {schema: {type: object,properties: {name: {type: string},env: {type: string,enum: [prod,staging]},type: {type: string,enum: [keyvalue,messaging,blobstore,postgres,egress]},className: {type: string},parameters: {type: object,properties: {storage: {type: string},memory: {type: string},cpu: {type: string}}},deletionPolicy: {type: string,enum: [Retain,Delete]},destinations: {type: array,items: {type: string}},createdAt: {type: string,format: date-time}},required: [name,env,type,className,createdAt]}}}}},security: [{identity: []}]}},"/v1/services/{service}/logs": {get: {summary: Read or follow service logs,description: "Server-sent events (`text/event-stream`). Each `log` event carries one LogEvent as JSON; an `end` event closes the stream. With `follow` the stream stays open until the client disconnects.",operationId: logs,responses: {"200": {description: Read or follow service logs,content: {application/json: {schema: {type: object,description: "One line of a service log. Streamed as `text/event-stream`: each SSE `data:` field is one LogEvent as JSON; the `event:` field is `log`, or `end` when the stream closes.",properties: {timestamp: {type: string,format: date-time},deployment: {type: string},instance: {type: string},level: {type: string,enum: [debug,info,warn,error]},message: {type: string}},required: [timestamp,deployment,message]}}}}},parameters: [{name: service,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}},{name: deployment,in: query,required: false,schema: {type: string}},{name: follow,in: query,required: false,schema: {type: boolean,default: false}},{name: since,in: query,required: false,schema: {type: string,description: "Duration such as 10m or 1h, or an RFC 3339 timestamp."}},{name: tail,in: query,required: false,schema: {type: integer,format: int32,default: 100}}],security: [{identity: []}]}},"/v1/services/{service}/proxy": {post: {summary: Open an HTTP session to a service,description: "Issues a short-lived HTTP session to the service, bound to the caller. The session URL takes the same bearer.",operationId: proxy,requestBody: {content: {application/json: {schema: {type: object,properties: {env: {type: string,enum: [prod,staging]},port: {type: integer,format: int32,description: "Service port; only 80, the tenant HTTP upstream, is supported (the default)."}},required: [env]}}},required: true},responses: {"201": {description: Open an HTTP session to a service,content: {application/json: {schema: {type: object,description: "A short-lived HTTP session to one service, bound to the caller. Requests to `url` and paths below it carry the same bearer and are forwarded to the service until `expiresAt`. The controller serves the session URL outside this document; WebSocket is not supported yet.",properties: {url: {type: string,format: uri},port: {type: integer,format: int32},expiresAt: {type: string,format: date-time}},required: [url,port,expiresAt]}}}}},parameters: [{name: service,in: path,required: true,schema: {type: string}}],security: [{identity: []}]}},"/v1/vars/{name}": {put: {summary: Set a var,description: Creates or replaces the var. The CLI reads the value from a file or stdin so it stays out of shell history.,operationId: setVar,requestBody: {content: {application/json: {schema: {type: object,properties: {value: {type: string}},required: [value]}}},required: true},responses: {"204": {description: Set a var}},parameters: [{name: name,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]},delete: {summary: Unset a var,operationId: unsetVar,responses: {"204": {description: Unset a var}},parameters: [{name: name,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]},patch: {summary: Update a var,description: Replaces the value of an existing var; 404 when it does not exist.,operationId: updateVar,requestBody: {content: {application/json: {schema: {type: object,properties: {value: {type: string}},required: [value]}}},required: true},responses: {"204": {description: Update a var}},parameters: [{name: name,in: path,required: true,schema: {type: string}},{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]}},/v1/vars: {get: {summary: List vars,description: "Names, values, and update times of the environment variables.",operationId: vars,responses: {"200": {description: List vars,content: {application/json: {schema: {type: object,properties: {env: {type: string,enum: [prod,staging]},items: {type: array,items: {$ref: "#/components/schemas/ConfigEntry"}}},required: [env,items]}}}}},parameters: [{name: env,in: query,required: true,schema: {type: string,enum: [prod,staging]}}],security: [{identity: []}]}}},components: {schemas: {Empty: {type: object},Problem: {type: object,description: RFC 9457 problem details; every error response uses it.,properties: {type: {type: string},title: {type: string},status: {type: integer,format: int32},detail: {type: string}},required: [title,status]},AuthInfo: {type: object,description: "What a CLI needs before it holds a credential: the account this controller serves and the identity server to log in with.",properties: {account: {type: string},issuer: {type: string,format: uri},clientId: {type: string}},required: [account,issuer,clientId]},Principal: {type: object,properties: {user: {type: string},account: {type: string},role: {type: string,enum: [developer,viewer]},via: {type: string,enum: [identity,api-key]},credentialId: {type: string}},required: [user,account,role,via]},ComponentReference: {type: object,description: The built component the controller pulls from the platform registry.,properties: {reference: {type: string,description: OCI reference the component was pushed as.},digest: {type: string,description: sha256 digest of the pushed artifact.}},required: [reference,digest]},Binding: {type: object,description: "One `@WasmCloudBinding` of the component, rendered by the CLI.",properties: {name: {type: string},capability: {type: string},serviceName: {type: string,description: Backing service the binding attaches to.},config: {type: object,additionalProperties: {type: string}}},required: [name,capability]},DeployBundle: {type: object,description: Everything the CLI renders client-side. The controller validates it at the boundary and never receives a kubeconfig or a namespace.,properties: {env: {type: string,enum: [prod,staging]},service: {type: string,description: Service the deployment belongs to.},component: {$ref: "#/components/schemas/ComponentReference"},workload: {type: object,description: "The rendered WorkloadDeployment template, without namespace or host selector.",additionalProperties: true},bindings: {type: array,items: {$ref: "#/components/schemas/Binding"}},secrets: {type: array,description: Names of tenant secrets the workload references; values never travel.,items: {type: string}}},required: [env,service,component,workload,bindings,secrets]},RegistryInfo: {type: object,description: "Where a tenant pushes and pulls images: the tenant's own OCI registry. Log in with an identity-server access token or API key as the Basic password.",properties: {url: {type: string,format: uri,description: "Origin of the tenant's OCI registry: scheme + host[:port], no path. Clients use its host[:port] for login and in image references; an http: origin means plain HTTP."},repositoryPrefix: {type: string,description: "Namespace inside the tenant registry, when there is one."},auth: {type: string,enum: [basic-identity],description: Basic auth whose password is an identity-server access token or dik_ API key.},username: {type: string,description: A fixed hint for the Basic username; the registry ignores it.}},required: [url,auth,username]},DeployChange: {type: object,properties: {kind: {type: string,enum: [create,update,unchanged,delete]},resource: {type: string},name: {type: string},detail: {type: string}},required: [kind,resource,name]},DeployPlan: {type: object,description: What applying the bundle would change.,properties: {env: {type: string,enum: [prod,staging]},service: {type: string},changes: {type: array,items: {$ref: "#/components/schemas/DeployChange"}}},required: [env,service,changes]},Deployment: {type: object,properties: {id: {type: string},service: {type: string},env: {type: string,enum: [prod,staging]},status: {type: string,enum: [pending,rolling,ready,failed,rolled-back]},component: {$ref: "#/components/schemas/ComponentReference"},createdAt: {type: string,format: date-time},readyAt: {type: string,format: date-time}},required: [id,service,env,status,component,createdAt]},DeploymentList: {type: object,properties: {items: {type: array,items: {$ref: "#/components/schemas/Deployment"}}},required: [items]},DeploymentStats: {type: object,properties: {env: {type: string,enum: [prod,staging]},services: {type: integer,format: int32},deployments: {type: integer,format: int32},ready: {type: integer,format: int32},failed: {type: integer,format: int32},lastDeployedAt: {type: string,format: date-time}},required: [env,services,deployments,ready,failed]},RollbackRequest: {type: object,properties: {env: {type: string,enum: [prod,staging]},service: {type: string},to: {type: string,description: Deployment id to roll back to; the previous one when absent.}},required: [env,service]},CreateServiceRequest: {type: object,description: "A backing service (BackingService) in the environment, shaped like `di-framework platform service create`. `destinations` is required for egress and only allowed there. http, cron and worker services come from the deploy bundle, not from this operation.",properties: {env: {type: string,enum: [prod,staging]},type: {type: string,enum: [keyvalue,messaging,blobstore,postgres,egress]},name: {type: string,description: "DNS label, at most 40 characters: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`."},className: {type: string,description: "The platform default class for the type when absent (keyvalue-redis, messaging-nats, blobstore-nats, postgres-dedicated, egress-public); any other class is refused."},parameters: {type: object,description: "Sizing quantities such as `1Gi` or `500m`.",properties: {storage: {type: string},memory: {type: string},cpu: {type: string}},additionalProperties: false},deletionPolicy: {type: string,enum: [Retain,Delete]},destinations: {type: array,items: {type: string},description: "Egress only: hosts the workload may reach (`host`, `*.suffix`, optionally `:port`)."}},required: [env,type,name]},Service: {type: object,properties: {name: {type: string},env: {type: string,enum: [prod,staging]},type: {type: string,enum: [keyvalue,messaging,blobstore,postgres,egress]},className: {type: string},parameters: {type: object,properties: {storage: {type: string},memory: {type: string},cpu: {type: string}}},deletionPolicy: {type: string,enum: [Retain,Delete]},destinations: {type: array,items: {type: string}},createdAt: {type: string,format: date-time}},required: [name,env,type,className,createdAt]},LogEvent: {type: object,description: "One line of a service log. Streamed as `text/event-stream`: each SSE `data:` field is one LogEvent as JSON; the `event:` field is `log`, or `end` when the stream closes.",properties: {timestamp: {type: string,format: date-time},deployment: {type: string},instance: {type: string},level: {type: string,enum: [debug,info,warn,error]},message: {type: string}},required: [timestamp,deployment,message]},ConfigEntry: {type: object,description: A secret lists its name only; a var also carries its value.,properties: {name: {type: string},value: {type: string},updatedAt: {type: string,format: date-time}},required: [name,updatedAt]},ConfigList: {type: object,properties: {env: {type: string,enum: [prod,staging]},items: {type: array,items: {$ref: "#/components/schemas/ConfigEntry"}}},required: [env,items]},SecretEntry: {type: object,description: A secret lists its name and update time only; its value never travels on read.,properties: {name: {type: string},updatedAt: {type: string,format: date-time}},required: [name,updatedAt],additionalProperties: false},SecretList: {type: object,properties: {env: {type: string,enum: [prod,staging]},items: {type: array,items: {$ref: "#/components/schemas/SecretEntry"}}},required: [env,items]},ConfigValue: {type: object,properties: {value: {type: string}},required: [value]},ProxyRequest: {type: object,properties: {env: {type: string,enum: [prod,staging]},port: {type: integer,format: int32,description: "Service port; only 80, the tenant HTTP upstream, is supported (the default)."}},required: [env]},ProxySession: {type: object,description: "A short-lived HTTP session to one service, bound to the caller. Requests to `url` and paths below it carry the same bearer and are forwarded to the service until `expiresAt`. The controller serves the session URL outside this document; WebSocket is not supported yet.",properties: {url: {type: string,format: uri},port: {type: integer,format: int32},expiresAt: {type: string,format: date-time}},required: [url,port,expiresAt]}},securitySchemes: {identity: {type: http,scheme: bearer,description: "An identity-server access token for a member of this account, or a tenant API key (`dik_…`). Obtained by the CLI login; never passed as an argument."}}}}

package/dist/cli.d.ts

@@ -0,0 +1,22 @@
+export interface Io {
+    stdout(line: string): void;
+    stderr(line: string): void;
+    /** Standard input, read whole; used by `--from-file -`. */
+    stdin(): string;
+    /** Opens a URL in the user's browser; `main.ts` spawns the platform opener. */
+    open(url: string): void;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    fetch?: typeof fetch;
+    /** How long `login` waits for the browser to come back; five minutes by default. */
+    loginTimeoutMs?: number;
+}
+export interface Parsed {
+    command: string;
+    flags: Record<string, string>;
+    positionals: string[];
+}
+/** `--flag value`, `--flag=value`, boolean flags, and positionals; `--` ends flag parsing. */
+export declare function parseArgs(argv: string[]): Parsed;
+export declare const USAGE = "di-tenant: the tenant CLI pilot. It talks to the tenant controller only.\n\n  login --controller <url> [--account <tenant>] [--api-key <key>] [--no-browser]\n  logout [--account <tenant>]\n  whoami [--account <tenant>]\n  deploy preview|apply --env <prod|staging> --bundle <file>\n  logs --service <name> --env <env> [--deployment <id>] [--follow] [--since <dur>] [--tail <n>]\n  services create <keyvalue|messaging|blobstore|postgres|egress> --name <name> --env <env> [--class <class>] [--storage <q>] [--memory <q>] [--cpu <q>] [--deletion-policy <Retain|Delete>] [--destination <host[:port],...>]\n  deployments list|stats --env <env> [--service <name>]\n  deployments rollback --service <name> --env <env> [--to <id>]\n  secrets|vars list --env <env>\n  secrets|vars set|update <name> --env <env> --from-file <path|->\n  secrets|vars unset <name> --env <env>\n  proxy --service <name> --env <env> [--port <n>]\n  init [name] [--dir <path>] [--name <name>] [--force]\n\nShared flags: --env, --json, --account. The credential comes from the login on disk; there is no token argument.";
+export declare function run(argv: string[], io: Io): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,419 @@
+import { readFileSync } from 'node:fs';
+import { createClient, } from "./client/index.js";
+import { bearer, CliError, load, needsRefresh, readStore, resolveAccount, writeStore, } from "./credentials.js";
+import { init } from "./init.js";
+import { authorizationUrl, discover, exchangeCode, OidcError, pkce, randomToken, refreshTokens, revokeToken, } from "./oidc.js";
+const SCOPE = 'openid profile email offline_access';
+const BOOLEAN_FLAGS = new Set(['json', 'follow', 'force', 'no-browser']);
+/** `--flag value`, `--flag=value`, boolean flags, and positionals; `--` ends flag parsing. */
+export function parseArgs(argv) {
+    const flags = {};
+    const positionals = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === '--') {
+            positionals.push(...argv.slice(i + 1));
+            break;
+        }
+        if (!arg.startsWith('--')) {
+            positionals.push(arg);
+            continue;
+        }
+        const equals = arg.indexOf('=');
+        const name = equals === -1 ? arg.slice(2) : arg.slice(2, equals);
+        if (equals !== -1)
+            flags[name] = arg.slice(equals + 1);
+        else if (BOOLEAN_FLAGS.has(name))
+            flags[name] = 'true';
+        else {
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--'))
+                throw new CliError(`--${name} needs a value`);
+            flags[name] = value;
+            i++;
+        }
+    }
+    const [command = 'help', ...rest] = positionals;
+    return { command, flags, positionals: rest };
+}
+export const USAGE = `di-tenant: the tenant CLI pilot. It talks to the tenant controller only.
+
+  login --controller <url> [--account <tenant>] [--api-key <key>] [--no-browser]
+  logout [--account <tenant>]
+  whoami [--account <tenant>]
+  deploy preview|apply --env <prod|staging> --bundle <file>
+  logs --service <name> --env <env> [--deployment <id>] [--follow] [--since <dur>] [--tail <n>]
+  services create <keyvalue|messaging|blobstore|postgres|egress> --name <name> --env <env> [--class <class>] [--storage <q>] [--memory <q>] [--cpu <q>] [--deletion-policy <Retain|Delete>] [--destination <host[:port],...>]
+  deployments list|stats --env <env> [--service <name>]
+  deployments rollback --service <name> --env <env> [--to <id>]
+  secrets|vars list --env <env>
+  secrets|vars set|update <name> --env <env> --from-file <path|->
+  secrets|vars unset <name> --env <env>
+  proxy --service <name> --env <env> [--port <n>]
+  init [name] [--dir <path>] [--name <name>] [--force]
+
+Shared flags: --env, --json, --account. The credential comes from the login on disk; there is no token argument.`;
+function requireFlag(flags, name) {
+    const value = flags[name];
+    if (!value)
+        throw new CliError(`--${name} is required`);
+    return value;
+}
+function requireEnv(flags) {
+    const value = requireFlag(flags, 'env');
+    if (value !== 'prod' && value !== 'staging')
+        throw new CliError('--env must be prod or staging');
+    return value;
+}
+const BACKING_TYPES = [
+    'keyvalue',
+    'messaging',
+    'blobstore',
+    'postgres',
+    'egress',
+];
+function integer(flags, name) {
+    const value = flags[name];
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0)
+        throw new CliError(`--${name} must be a whole number`);
+    return parsed;
+}
+/** `--from-file <path>` or `-` for stdin: values never appear on the command line. */
+function valueFrom(flags, io) {
+    const source = requireFlag(flags, 'from-file');
+    const raw = source === '-' ? io.stdin() : readFileSync(source, 'utf8');
+    return raw.replace(/\r?\n$/, '');
+}
+function print(io, flags, value, line) {
+    io.stdout(flags.json === 'true' ? JSON.stringify(value, null, 2) : line(value));
+}
+/**
+ * Resolves the credential on disk for the account, refreshing an identity token that is about to
+ * expire, and builds a client with its bearer.
+ */
+async function session(flags, io) {
+    const store = readStore(io.env);
+    const account = resolveAccount(flags.account, io.env, store);
+    let credential = load(account, io.env);
+    if (needsRefresh(credential)) {
+        credential = await refresh(credential, io);
+        store[account] = credential;
+        writeStore(store, io.env);
+    }
+    const client = createClient({
+        baseUrl: credential.controller.url,
+        token: bearer(credential),
+        fetch: io.fetch,
+    });
+    return { credential, client };
+}
+/** The refresh grant at the issuer, with the public client id; identity rotates the token. */
+async function refresh(credential, io) {
+    if (!credential.issuer || !credential.clientId || !credential.refreshToken) {
+        throw new CliError('the login cannot be refreshed; run login again');
+    }
+    const metadata = await discover(credential.issuer, io.fetch);
+    let tokens;
+    try {
+        tokens = await refreshTokens(metadata, { clientId: credential.clientId, refreshToken: credential.refreshToken }, io.fetch);
+    }
+    catch (error) {
+        if (error instanceof OidcError) {
+            throw new CliError(`the login has expired (${error.message}); run login again`);
+        }
+        throw error;
+    }
+    return { ...credential, ...issued(tokens, credential.refreshToken) };
+}
+function issued(tokens, previousRefresh) {
+    return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token ?? previousRefresh,
+        expiresAt: new Date(Date.now() + tokens.expires_in * 1000).toISOString(),
+    };
+}
+const page = (text, status = 200) => new Response(`<!doctype html><title>di-tenant</title><p style="font:16px system-ui;padding:24px">${text}</p>`, { status, headers: { 'content-type': 'text/html' } });
+/**
+ * RFC 8252 browser login: a loopback listener on a free port is the redirect URI, the browser
+ * signs in at the issuer, and the code comes back with the PKCE verifier, no client secret.
+ */
+async function browserLogin(info, flags, io) {
+    const metadata = await discover(info.issuer, io.fetch);
+    const { verifier, challenge } = await pkce();
+    const state = randomToken(16);
+    const { promise, resolve, reject } = Promise.withResolvers();
+    const server = Bun.serve({
+        hostname: '127.0.0.1',
+        port: 0,
+        fetch(request) {
+            const url = new URL(request.url);
+            if (url.pathname !== '/callback')
+                return page('Not found.', 404);
+            const refused = url.searchParams.get('error');
+            if (refused) {
+                reject(new CliError(`the identity server refused the login: ${refused}`));
+                return page('Login failed. Return to the terminal.', 400);
+            }
+            const code = url.searchParams.get('code');
+            if (!code || url.searchParams.get('state') !== state) {
+                reject(new CliError('the browser returned an unexpected login response'));
+                return page('Login failed. Return to the terminal.', 400);
+            }
+            resolve(code);
+            return page('Signed in. You can close this window and return to the terminal.');
+        },
+    });
+    const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+    try {
+        const url = authorizationUrl(metadata, {
+            clientId: info.clientId,
+            redirectUri,
+            scope: SCOPE,
+            state,
+            nonce: randomToken(16),
+            codeChallenge: challenge,
+        });
+        io.stderr(`Opening your browser to sign in to ${info.account} at ${info.issuer}.\nIf it does not open, visit:\n  ${url}`);
+        if (flags['no-browser'] !== 'true')
+            io.open(url);
+        const timer = setTimeout(() => reject(new CliError('timed out waiting for the browser login')), io.loginTimeoutMs ?? 300_000);
+        const code = await promise.finally(() => clearTimeout(timer));
+        return await exchangeCode(metadata, { clientId: info.clientId, redirectUri, code, codeVerifier: verifier }, io.fetch);
+    }
+    finally {
+        await server.stop();
+    }
+}
+async function login(flags, io) {
+    const controller = requireFlag(flags, 'controller').replace(/\/$/, '');
+    const info = await createClient({ baseUrl: controller, fetch: io.fetch }).authInfo();
+    if (flags.account && info.account !== flags.account) {
+        throw new CliError(`${controller} serves account ${info.account}, not ${flags.account}`);
+    }
+    const apiKey = flags['api-key'];
+    const tokens = apiKey ? undefined : await browserLogin(info, flags, io);
+    const token = apiKey ?? tokens.access_token;
+    const who = await createClient({ baseUrl: controller, token, fetch: io.fetch }).whoami();
+    const base = {
+        account: info.account,
+        user: who.user,
+        role: who.role,
+        controller: { url: controller },
+    };
+    const credential = apiKey
+        ? { ...base, via: 'api-key', apiKey }
+        : {
+            ...base,
+            via: 'identity',
+            issuer: info.issuer,
+            clientId: info.clientId,
+            ...issued(tokens),
+        };
+    const store = readStore(io.env);
+    store[info.account] = credential;
+    writeStore(store, io.env);
+    io.stderr(`Logged in to ${info.account} as ${who.user} (${who.role}) via ${credential.via}.`);
+    return 0;
+}
+export async function run(argv, io) {
+    try {
+        return await dispatch(parseArgs(argv), io);
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            io.stderr(error.message);
+            return error.exitCode;
+        }
+        if (error instanceof OidcError) {
+            io.stderr(`identity: ${error.message}`);
+            return 1;
+        }
+        if (error.name === 'ControllerError') {
+            const failure = error;
+            io.stderr(`controller: ${failure.status} ${failure.message}`);
+            return 1;
+        }
+        throw error;
+    }
+}
+async function dispatch(parsed, io) {
+    const { command, flags, positionals } = parsed;
+    const [sub, ...rest] = positionals;
+    switch (command) {
+        case 'help':
+            io.stdout(USAGE);
+            return 0;
+        case 'login':
+            return login(flags, io);
+        case 'logout': {
+            // Tell the controller first, while the token is still valid, then revoke the refresh token
+            // at the issuer, then forget the credential. A failure anywhere still forgets it.
+            const store = readStore(io.env);
+            const account = resolveAccount(flags.account, io.env, store);
+            const credential = load(account, io.env);
+            try {
+                await createClient({
+                    baseUrl: credential.controller.url,
+                    token: bearer(credential),
+                    fetch: io.fetch,
+                }).logout();
+            }
+            catch {
+                // An expired or already revoked token; nothing to tell the controller.
+            }
+            if (credential.via === 'identity' && credential.refreshToken && credential.issuer) {
+                await revokeToken(await discover(credential.issuer, io.fetch), credential.clientId ?? '', credential.refreshToken, io.fetch);
+            }
+            delete store[account];
+            writeStore(store, io.env);
+            io.stderr(`Logged out of ${account}.`);
+            return 0;
+        }
+        case 'whoami': {
+            const { client } = await session(flags, io);
+            const who = await client.whoami();
+            print(io, flags, who, () => `${who.user} (${who.role}) in ${who.account} via ${who.via}`);
+            return 0;
+        }
+        case 'deploy': {
+            if (sub !== 'preview' && sub !== 'apply')
+                throw new CliError('usage: deploy preview|apply');
+            const env = requireEnv(flags);
+            const bundle = JSON.parse(readFileSync(requireFlag(flags, 'bundle'), 'utf8'));
+            bundle.env = env;
+            const { client } = await session(flags, io);
+            if (sub === 'preview') {
+                const plan = await client.previewDeploy(bundle);
+                print(io, flags, plan, () => plan.changes.length === 0
+                    ? `${plan.service} in ${plan.env}: no changes`
+                    : plan.changes.map((c) => `${c.kind} ${c.resource}/${c.name}`).join('\n'));
+                return 0;
+            }
+            const deployment = await client.deploy(bundle);
+            print(io, flags, deployment, () => `${deployment.service} in ${deployment.env}: ${deployment.id} ${deployment.status}`);
+            return 0;
+        }
+        case 'logs': {
+            const { client } = await session(flags, io);
+            const stream = client.logs(requireFlag(flags, 'service'), {
+                env: requireEnv(flags),
+                deployment: flags.deployment,
+                follow: flags.follow === 'true',
+                since: flags.since,
+                tail: integer(flags, 'tail'),
+            });
+            for await (const event of stream) {
+                print(io, flags, event, () => `${event.timestamp} ${event.deployment} ${event.level ?? 'info'} ${event.message}`);
+            }
+            return 0;
+        }
+        case 'services': {
+            if (sub !== 'create')
+                throw new CliError('usage: services create <keyvalue|messaging|blobstore|postgres|egress> --name <name>');
+            const type = rest[0];
+            if (!BACKING_TYPES.includes(type)) {
+                throw new CliError('service type must be keyvalue, messaging, blobstore, postgres, or egress (http, cron and worker services come from deploy)');
+            }
+            const policy = flags['deletion-policy'];
+            if (policy !== undefined && policy !== 'Retain' && policy !== 'Delete')
+                throw new CliError('--deletion-policy must be Retain or Delete');
+            const sizing = { storage: flags.storage, memory: flags.memory, cpu: flags.cpu };
+            const request = {
+                env: requireEnv(flags),
+                type,
+                name: requireFlag(flags, 'name'),
+                className: flags.class,
+                parameters: Object.values(sizing).some((v) => v !== undefined) ? sizing : undefined,
+                deletionPolicy: policy,
+                destinations: flags.destination?.split(',').filter((d) => d !== ''),
+            };
+            const { client } = await session(flags, io);
+            const service = await client.createService(request);
+            print(io, flags, service, () => `created ${service.type} service ${service.name} (${service.className}) in ${service.env}`);
+            return 0;
+        }
+        case 'deployments': {
+            const env = requireEnv(flags);
+            const { client } = await session(flags, io);
+            if (sub === 'list') {
+                const list = await client.deployments({ env, service: flags.service });
+                print(io, flags, list, () => list.items.length === 0
+                    ? `no deployments in ${env}`
+                    : list.items.map((d) => `${d.id} ${d.service} ${d.status} ${d.createdAt}`).join('\n'));
+                return 0;
+            }
+            if (sub === 'stats') {
+                const stats = await client.deploymentStats(env);
+                print(io, flags, stats, () => `${env}: ${stats.services} services, ${stats.deployments} deployments, ${stats.ready} ready, ${stats.failed} failed`);
+                return 0;
+            }
+            if (sub === 'rollback') {
+                const deployment = await client.rollback({
+                    env,
+                    service: requireFlag(flags, 'service'),
+                    to: flags.to,
+                });
+                print(io, flags, deployment, () => `${deployment.service} in ${env}: rolling back to ${deployment.id}`);
+                return 0;
+            }
+            throw new CliError('usage: deployments list|stats|rollback');
+        }
+        case 'secrets':
+        case 'vars': {
+            const env = requireEnv(flags);
+            const { client } = await session(flags, io);
+            const secret = command === 'secrets';
+            if (sub === 'list') {
+                const list = secret
+                    ? await client.secrets(env)
+                    : await client.vars(env);
+                print(io, flags, list, () => list.items.length === 0
+                    ? `no ${command} in ${env}`
+                    : list.items.map((e) => (secret ? e.name : `${e.name}=${e.value ?? ''}`)).join('\n'));
+                return 0;
+            }
+            const name = rest[0];
+            if (!name || (sub !== 'set' && sub !== 'update' && sub !== 'unset')) {
+                throw new CliError(`usage: ${command} list|set|update|unset <name>`);
+            }
+            if (sub === 'unset')
+                await (secret ? client.unsetSecret(env, name) : client.unsetVar(env, name));
+            else {
+                const value = valueFrom(flags, io);
+                if (sub === 'set')
+                    await (secret ? client.setSecret(env, name, value) : client.setVar(env, name, value));
+                else
+                    await (secret
+                        ? client.updateSecret(env, name, value)
+                        : client.updateVar(env, name, value));
+            }
+            io.stderr(`${sub} ${command.slice(0, -1)} ${name} in ${env}`);
+            return 0;
+        }
+        case 'proxy': {
+            const { client } = await session(flags, io);
+            const sessionInfo = await client.proxy(requireFlag(flags, 'service'), {
+                env: requireEnv(flags),
+                port: integer(flags, 'port'),
+            });
+            print(io, flags, sessionInfo, () => `proxy session until ${sessionInfo.expiresAt}: send HTTP requests to ${sessionInfo.url}/<path> with your bearer, e.g. curl -H "Authorization: Bearer $TOKEN" ${sessionInfo.url}/`);
+            return 0;
+        }
+        case 'init': {
+            const seeded = init({
+                name: sub,
+                dir: flags.dir,
+                projectName: flags.name,
+                force: flags.force === 'true',
+                cwd: io.cwd,
+            });
+            print(io, flags, seeded, () => `seeded ${seeded.directory}: ${seeded.files.join(', ')}`);
+            return 0;
+        }
+        default:
+            throw new CliError(`unknown command ${command}\n\n${USAGE}`, 2);
+    }
+}