@xemahq/xema 0.29.1 → 0.30.0

package/README.md

@@ -6,7 +6,7 @@
     <path d="M26 12 L41 21 L41 39 L26 48 L11 39 L11 21 Z" fill="#8B5CF6"/>
   </g>
   <text x="92" y="52" font-family="ui-monospace,SFMono-Regular,Menlo,monospace" font-size="22" fill="#F8FAFC" font-weight="700">@xemahq/xema</text>
-  <text x="92" y="80" font-family="ui-sans-serif,system-ui,sans-serif" font-size="15" fill="#94A3B8">The Xema OS command-line interface</text>
+  <text x="92" y="80" font-family="ui-sans-serif,system-ui,sans-serif" font-size="15" fill="#94A3B8">Command-line interface for Xema</text>
   <text x="652" y="105" text-anchor="end" font-family="ui-sans-serif,system-ui,sans-serif" font-size="12" fill="#475569">xema.dev</text>
 </svg>
 </p>
@@ -24,21 +24,18 @@
 
 # @xemahq/xema
 
-> The Xema OS command-line interface
+> Command-line interface for Xema
 
 ## Overview
 
-The single global binary for Xema. Install it once to **launch the whole
-platform with one command**, author and ship biomes, and invoke capabilities
-from your terminal.
+The `xema` command launches a Xema installation locally or on Kubernetes, authors and publishes biomes, invokes capabilities, and manages declarative stacks against a running control plane. It resolves an edition's distribution lock into a service roster and runs it on the substrate you choose.
 
-`xema up` resolves the platform's distribution lock into an effective service
-roster, brings up the backing infrastructure you don't already run, and
-supervises every service to readiness — over a **container** substrate
-(customers) or a **native** substrate (contributors). It is a thin bring-up
-coordinator: it resolves topology and sequences startup, delegating process
-lifecycle (restart, health, resource limits) to the substrate beneath it
-(Docker/Podman, or your own infra). It never becomes a second orchestrator.
+## When to use it
+
+- Run a Xema installation on your machine or on Kubernetes (`up`, `dev`, `installation`).
+- Author, publish and install biomes (`biome`).
+- Drive a running platform: `login`, `run`, `plan`, `apply`, `export`, `import`, `status`, `logs`.
+- Resolve, seal and check editions (`edition`; see [`edition/README.md`](edition/README.md)).
 
 ## Installation
 
@@ -46,409 +43,83 @@ lifecycle (restart, health, resource limits) to the substrate beneath it
 npm i -g @xemahq/xema
 ```
 
-### Client mode vs developer mode
-
-A fresh install starts in **client mode**, for people who USE a Xema deployment:
-`login`, `apply`, `plan`, `run`, `shell`, `objects`, `status`, `logs`.
-
-The commands that stand a platform up locally — **`up`, `dev`, `serve`**, which
-the rest of this document is largely about — are the platform contributor's inner
-loop. They are fully functional in client mode but **hidden from `xema --help`**,
-so following the sections below without turning developer mode on gives you
-working commands that `--help` never mentions:
+A fresh install is in client mode. `up`, `dev` and `serve` still work but are hidden from `xema --help` until you turn developer mode on:
 
 ```bash
 xema config set dev on     # or: export XEMA_DEV=1
 ```
 
-`xema --help` states this in both modes, and `xema config get` explains which
-input decided it.
-
-## Scaffold a config — `xema init`
-
-Generate a `xema.config.yaml` tailored to your scenario. Run it with no flags for
-a short interactive wizard, or `--preset` / `--yes` for scripted use:
+## Usage
 
 ```bash
-xema init                                  # interactive wizard
-xema init --preset local-container --yes   # full local stack in containers
-xema init --preset byo-infra               # bring-your-own Postgres/Keycloak/object-store
-xema init --preset appliance               # Kubernetes via Helm
-#   --edition <id> picks a distribution edition (offered from xema-distributions);
-#   --web enables the host shell; --output <path>; --force to overwrite.
+xema init --preset local-container --yes   # write xema.config.yaml
+xema up                                    # boot infra and services
+xema status                                # workloads and health
+xema logs <service> -f                     # stream one workload's logs
+xema down                                  # stop (add --purge to delete data volumes)
 ```
 
-The wizard walks you through:
-
-- **scenario** (containers / BYO-infra / appliance),
-- **edition** — which biomes make up the platform (`oss`, `core`, … described inline),
-- **infrastructure, per service** — for each of Postgres / Redis / Keycloak /
-  object-store / etcd / search / Temporal, choose **auto** (xema launches it) or
-  **external** (paste your connection URL), and each external URL is
-  **connection-tested** (reachability),
-- **your own biomes** — add git repo(s) as sources (composed with the edition at
-  launch).
-
-Every generated config is validated against the schema before it's written, so it
-can never be one `xema up` would reject.
-
-## Launch the platform
-
-```bash
-xema up                    # boot the backend (infra + services) as one supervised process
-xema up --web              # also start the host-shell frontend
-xema up --all              # everything, including the frontend
-xema up --detach           # leave container workloads running and return
-xema down                  # stop everything (xema down --purge also deletes data volumes)
-xema status                # show launcher-owned workloads + health
-xema logs <service> -f     # stream a launcher-owned workload's logs
-```
-
-Every verb works against the configured substrate — one verb set, pluggable
-target. `xema logs` streams from a launcher-owned container (`docker logs`) on
-the container substrate, from the owned release's Deployment
-(`kubectl logs deploy/<service>`) on the helm substrate, and on native points
-at the foreground `xema up` / `xema dev` console (that is where native
-services log).
+| Command | Purpose |
+| --- | --- |
+| `xema init [--preset <name>] [--edition <id>] [--web] [--output <path>] [--yes] [--force]` | Scaffold `xema.config.yaml`; interactive without flags. |
+| `xema up [--web] [--all] [--only <services>] [--detach] [--dry-run] [--edition <id>] [--config <path>]` | Boot the configured substrate. |
+| `xema dev [services...] [--watch] [--web] [--dry-run]` | Native boot from source; a service list boots only those plus their prerequisites. |
+| `xema serve --substrate single-instance\|cluster\|appliance` | Boot as separate processes. |
+| `xema doctor [--infra] [--sources]` | Check the environment, backing services and biome sources (token presence only). |
+| `xema biome scaffold\|install\|publish\|lint\|search\|list\|info\|remove` | Author and manage biomes. |
+| `xema run <capability> [--input <json>]` | Invoke a capability. |
+| `xema plan\|apply\|export\|import -f xema.yaml` | Declarative stacks (`--stack`, `--auto-approve` on apply). |
+| `xema installation init\|validate\|plan\|apply\|verify\|status\|support-bundle` | Manage a `XemaInstallation` (`xema.installation.yaml`). |
+| `xema login`, `logout`, `whoami` | Authenticate against a platform. |
 
-The launcher and automation use the same compiled desired state — one
-`XemaInstallation` document — and the target kind decides who executes it.
+`xema <command> --help` lists every option.
 
-### Installing on Kubernetes — the boring path
+### Kubernetes
 
 ```bash
-export XEMA_DEPLOYMENT_ENGINE=/path/to/xema-deploy/scripts/engine/cli.mjs  # the ONE deployment engine
+export XEMA_DEPLOYMENT_ENGINE=/path/to/xema-deploy/scripts/engine/cli.mjs
 xema installation init --profile single-node-production \
   --target customer-kubernetes --context <kubectl-context> --kubeconfig ./kubeconfig \
-  --name acme-prod --edition oss
-#   …fill in xema.installation.yaml: namespace, domains, external infrastructure…
-xema installation validate --file xema.installation.yaml   # providers, then the deployment root
-xema installation plan     --file xema.installation.yaml   # what apply would change
-xema installation apply    --file xema.installation.yaml   # reconcile, wave by wave
-xema installation verify   --file xema.installation.yaml   # every release present and converged
-```
-
-On a `customer-kubernetes` or `single-node-kubernetes` target every verb
-PROJECTS the installation into a deployment root — `deployment.yaml`,
-`infra.yaml`, `secret-inputs.yaml`, `values.yaml` and the edition's two lock
-files, under `~/.xema/installations/<name>/deployment/` or beside the
-installation file when that directory already holds a `deployment.yaml` —
-and runs `xema-deployment-engine` over it. The CLI never renders a chart,
-ranks a wave or reads a lock; the engine does. A declaration the root cannot
-carry is refused by name rather than dropped, and nothing in the root is ever a
-secret value.
-
-#### Getting the deployment engine
-
-`XEMA_DEPLOYMENT_ENGINE` resolves the engine, and it takes either the
-`xema-deployment-engine` bin itself or a package root whose `package.json`
-declares that bin.
-
-**Today it is the bin.** The engine ships as `scripts/engine/cli.mjs` in the
-`xema-dev/xema-deploy` repository — the checkout an operator running a managed
-Xema deployment already has — so point the variable at that file:
-
-```bash
-export XEMA_DEPLOYMENT_ENGINE="$HOME/xema-deploy/scripts/engine/cli.mjs"
-xema-deployment-engine() { node "$XEMA_DEPLOYMENT_ENGINE" "$@"; }   # optional, for running it by hand
+  --name my-install --edition oss
+xema installation validate --file xema.installation.yaml
+xema installation plan     --file xema.installation.yaml
+xema installation apply    --file xema.installation.yaml
+xema installation verify   --file xema.installation.yaml
 ```
 
-Two things this README asserted until 2026-09-21 and should not have. There is
-no package to fetch: the name `@xemahq/deployment-engine` is served by no
-registry, so the `npm i -g` that used to open this section answered 404. And
-the package-root form does not reach a `xema-deploy` checkout either, because
-`scripts/engine/` carries no `package.json` — pointing the variable at the
-directory refuses with *"is a directory without a package.json"*. Point it at
-the file. The package-root form stays supported for the day the engine is
-published under a name of its own.
-
-Point it at the file *inside the checkout*, not at a copy of it: `cli.mjs`
-imports `../lib/*.mjs` from `scripts/lib/`, so the surrounding tree is part of
-the engine.
+The CLI projects the installation into a deployment root and runs the deployment engine over it; without `XEMA_DEPLOYMENT_ENGINE` every Kubernetes verb refuses. Last-applied state is kept under `~/.xema/installations/<name>/`.
 
-Unset it and every Kubernetes verb refuses by name, with that same remedy,
-before anything is projected or spawned.
-
-### Installing on this machine
+### Biomes
 
 ```bash
-xema installation plan                    # deterministic redacted change plan
-xema installation apply --detach           # reconcile through the same launcher as `xema up`
-xema installation status                  # desired vs applied vs observed drift
-xema installation support-bundle          # redacted JSON + SHA-256 integrity manifest
-```
-
-Destructive transitions are refused unless explicitly reviewed and authorized
-with `--allow-destructive`; rejected identity/schema transitions and the
-profiles without a renderer (`business-ha`, `enterprise-regulated`,
-`hosted-cell`) remain fail-fast. Last-applied state is atomically stored
-under `~/.xema/installations/<installation-id>/`, while secret values are
-resolved before source or deployment side effects and are never persisted in
-plans or support bundles.
-
-### Topology — `xema.config.yaml`
-
-The launcher reads an optional `xema.config.yaml` (or `~/.xema/config.yaml`)
-declaring **which infrastructure you own** and **what to run**. Every backing
-component is `managed` (the launcher starts it), `external` (you already run it —
-provide the URL), or `disabled`:
-
-```yaml
-edition: oss
-infra:
-  postgres:
-    {
-      mode: external,
-      url: postgresql://xema@db.corp:5432,
-      secretRef: postgres-password,
-    }
-  redis: { mode: managed }
-  etcd: { mode: managed }
-  keycloak: { mode: external, url: https://sso.corp/realms/xema, realm: xema }
-  objectStore: { mode: external, url: https://s3.corp }
-  search: { mode: managed }
-  temporal: { mode: managed }
-secrets:
-  postgres-password: { from: env, env: XEMA_POSTGRES_PASSWORD }
-app:
-  substrate: container # container | native
-  include: [all] # all | default | minimal | <tier> | [service ...]
-  features: [] # curated capability bundles
-  web: { enabled: true }
+xema biome install <biomeId> --project <projectId>   # or --org for in-process biomes
 ```
 
-- **`container`** (recommended): pulls content-addressed service images
-  (`imageRef:contentHash`) and runs them on a shared network, after bringing up
-  and bootstrapping managed infra — works without a monorepo checkout.
-- **`native`**: runs services as host processes against a built monorepo (the
-  contributor inner loop). Equivalent: `xema serve --substrate single-instance`.
-- **`helm`**: deploys to Kubernetes via `helm upgrade --install` (the appliance /
-  cluster target). Equivalent: `xema serve --substrate appliance`. `xema
-  status` lists the installation's releases, `xema logs` streams them through
-  `kubectl` (or the `k3s kubectl` applet a k3s appliance ships), and `xema
-  down` uninstalls exactly the releases this installation owns.
+Target and auth come from `--endpoint` / `--token` or `XEMA_ENDPOINT` / `XEMA_TOKEN`. Use `--install-config <file.json>` for install config and `--version <semver>` to pin.
 
-`xema up` fails fast on a missing required secret, an unreachable `external`
-dependency, or a disabled-but-mandatory infra component — never a silent
-degradation.
+## Configuration
 
-Managed local PostgreSQL and object-store credentials are generated uniquely
-per installation and retained under
-`~/.xema/installations/<installation-id>/managed-local-credentials.json` with
-directory mode `0700` and file mode `0600`. Repeated and concurrent launches
-reuse the same credentials; values are not written to config or command
-arguments. `xema down` preserves them with the data volumes, while
-`xema down --purge` removes both. A named volume created by an older CLI with
-fixed development credentials fails fast and requires that explicit purge
-before its first launch with credential custody.
+`xema.config.yaml` is read from `--config <path>`, then `./xema.config.yaml`, then `~/.xema/config.yaml`, then built-in defaults. See [`xema.config.example.yaml`](xema.config.example.yaml) and [`examples/`](examples/README.md).
 
-External PostgreSQL credentials are never defaulted or persisted in the
-endpoint URL. Put the username in the URL and source the password through
-`secretRef`. A referenced secret must be declared under
-`secrets` and resolve from `env`, `file`, or an interactive masked `prompt`
-before Xema creates any deployment resources.
-
-Secret names that are valid environment-variable names are intentionally
-injected into every native/container service in the launch. Use a non-environment
-name such as `postgres-password` for launcher-only `secretRef` values. File
-sources must be regular, non-symlink files with no group/other permissions
-(`0600` or stricter); relative paths resolve from the directory containing
-`xema.config.yaml`. The Helm substrate does not accept launcher-resolved
-secrets: configure Kubernetes Secrets through each service chart instead.
-
-### Credential custody — the local OpenBao
-
-The credential broker (`credential-broker-api`) refuses to boot without a
-deployment-selected custody provider. On the container and native substrates
-`xema up` therefore runs its own single-node OpenBao (`xema-openbao`, the
-official `openbao/openbao` image pinned by digest, integrated raft storage on the
-`xema-openbao-data` volume, published on `127.0.0.1:8200` only) whenever the
-roster contains the broker. On the first launch the CLI initialises it with a
-single unseal share and stores the unseal key and root token, encrypted, in
-`~/.xema/installations/<installation-id>/openbao-custody.json` (directory
-`0700`, file `0600`); they are never printed. Every later launch only unseals
-from the stored key, so `xema up` is idempotent. The CLI mounts a KV v2 engine
-at `xema-local`, writes a policy limited to `xema-local/{data,metadata}/xema/*`,
-and mints a scoped (non-root) token for the broker on each launch. The broker
-alone receives:
-
-| Variable | Value |
+| Key | Values |
 | --- | --- |
-| `CUSTODY_PROVIDER_REF` | `openbao` |
-| `OPENBAO_ADDRESS` | `http://xema-openbao:8200` (container) or `http://127.0.0.1:8200` (native) |
-| `OPENBAO_AUTH_METHOD` | `token` |
-| `OPENBAO_TOKEN` | the scoped broker token |
-| `OPENBAO_MOUNT_PATH` | `xema-local` |
-
-`xema down` keeps the vault and its keys; `xema down --purge` removes both
-together. A vault whose keys are missing (or keys whose vault is gone) is
-reported with that instruction rather than re-initialised. The Helm substrate
-does not start a vault: the chart selects the provider.
-
-`xema dev` does not start a vault. It expects an OpenBao on `127.0.0.1:8200`
-(pre-flight checks the port) and an `OPENBAO_TOKEN` in your environment; it
-defaults the rest of the contract above.
-
-### Realtime dev
-
-Xema always runs the `distributed` model: every service is its own process and
-peers discover each other through the KernelState adapter over etcd (native forks
-one child per service; container/helm run one workload each).
-
-For development, see code changes live — the composition restarts when service
-output changes (pair with each service's own `tsc -w` / `turbo watch`):
-
-```bash
-xema dev --watch           # boot from source; restart on any .ts change
-```
-
-### Launch one service (or a subset)
-
-Boot just the services you're working on — their hard prerequisites
-(`identity-api`, the foundational services) are pulled in automatically, so a
-lone service still boots a correct graph:
-
-```bash
-xema dev agent-session-api memory-api     # native: just these two (+ prerequisites)
-xema up   --only app-platform-api          # container: one service (+ prerequisites)
-xema serve --substrate cluster --only audit-log-api
-```
-
-### Biome sources — pull biomes from many origins
-
-A deployment's biomes can come from the first-party distribution, a cultivars
-edition, **a client's own private git repo or registry**, or a third party —
-each with its own auth — declared in a `sources:` block:
-
-```yaml
-sources:
-  - name: workspace # local working tree (monorepo): always wins
-    kind: workspace
-  - name: cultivars # a pinned edition lock
-    kind: distribution
-    edition: cultivars
-  - name: acme # a client's OWN biome git repo (private)
-    kind: git
-    url: https://github.com/acme/xema-biomes.git
-    ref: v2.1.0
-    authTokenEnv: GIT_TOKEN_ACME # env-var NAME, never the secret
-```
-
-Precedence: **`workspace` > other sources (declared order) > base distribution**.
-In a monorepo checkout the workspace source always wins, so `xema dev` runs your
-local edits with **no publish** and **no token** required. Tokens for private
-sources are referenced by env-var _name_ (the `biome-fetcher` convention) and
-resolved from the environment or a git-ignored `~/.xema/credentials.env` — never
-inlined in config. `npm`/`oci` sources are install-time (the `xema biome install`
-path); `workspace`/`distribution`/`git` boot directly from `xema up`/`dev`.
-
-Check every source + token before launching:
-
-```bash
-xema doctor --sources       # per source: target, launch-vs-install, token present? (redacted)
-```
-
-A full example lives at [`examples/06-biome-sources.yaml`](examples/06-biome-sources.yaml).
-
-### The standard biome structure (one shape, open features)
-
-Sources discover biomes by walking for `xema-biome.json` — a repo may hold ONE
-biome at its root or MANY nested; both are valid layouts of the **same
-standard**. A biome is a directory with a manifest at its root; its services
-live at the manifest-declared `ships.apis[].path` (convention `./api/<name>`).
-What a biome _does_ (services, skills, capabilities, agents) is wholly open —
-only the bundle _shape_ is standardized, so every author builds the same way and
-any source resolves the same way.
-
-## Resolve and check an edition — `xema edition`
-
-```bash
-xema edition resolve <id> [--check]      # the release lock set (distribution, authorization, chart-set, images)
-xema edition seal <id>                   # seal the image digests
-xema edition develop <subcommand> ...    # develop editions: resolve a snapshot into the edition artifact files
-xema edition artifact <id> --channel release --registry <ns> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir>
-                                         # the release edition artifact files, from the committed sealed locks
-xema edition index biome|platform-service|runtime-image-source [--check]
-xema edition check                       # the committed locks and indices are current
-xema edition why <id> <biome>            # why a biome is in an edition
-xema edition verify-platforms <id>       # the registry serves every required platform
-xema edition checkout-sources            # check out the sources the image index pins
-```
-
-Every verb takes the six roots (`--data-root`, `--editions-root`, `--sources-root`, `--kernel`,
-`--deploy-root`, `--cache-dir`); see `edition/README.md` for which verb needs which.
-
-### The edition protocol — what ties this CLI to a kernel
-
-The CLI is coupled to the kernel's **edition protocol**, not to the whole kernel package.
-`@xemahq/contracts` exports the protocol's identity as data
-(`@xemahq/contracts/edition-protocol/edition-protocol.json`): a version and a content digest over
-the exact bytes of every kernel source file the protocol's entry subpaths load at runtime (the
-schemas and every refinement, parser, resolver and composer behind them), derived from the
-kernel's import graph. This CLI declares the protocol versions it supports, each pinned to one
-digest, and vendors each supported contract (the identity, the entry subpaths and the source
-paths); it loads no kernel subpath outside those entry subpaths. `xema edition check` and every
-other verb compare only that identity with the `--kernel` they are given, and refuse any other,
-naming the versions this CLI supports and the version the kernel declares.
-
-The digest is a CONSERVATIVE, deterministic stand-in for protocol semantics. Any change to
-accepted or refused edition semantics MUST change it; a behaviour-preserving refactor MAY change
-it too, and the cost is a repin, which is accepted. Semantic equivalence isn't computable, so it
-is never detected.
-
-A kernel change outside the protocol's source files keeps the identity, so it needs no CLI
-release. An edition protocol change needs a CLI that supports it, so the order is: **the CLI
-release that supports the new protocol goes first, then the data root repins its kernel
-authority** to a kernel that speaks it.
-
-## Author biomes & run capabilities
-
-```bash
-xema dev                    # lock-driven native dev boot (contributors)
-xema biome scaffold <name>  # author a new biome
-xema biome publish <path>   # ship a biome
-xema run <capability>       # invoke a capability by name
-xema doctor                 # diagnose your environment
-```
-
-Install a catalog biome into a running platform (by id — the biome's bundle
-source is resolved server-side from its registered manifest; npm/OCI biomes
-require a project):
-
-```bash
-xema biome install <biomeId> --project <projectId>   # npm/OCI + any catalog biome
-xema biome install <biomeId> --org                   # in-process / kernel biomes only
-#   target + auth: --endpoint/--token or env XEMA_ENDPOINT / XEMA_TOKEN
-#   --config <file.json> for install config, --version <semver> to pin
-```
-
-The CLI never sends a registry token: a private source's `authTokenEnv` is read
-by `biome-fetcher-api` in the platform's own environment, so the token lives on
-the cluster, not in the install call.
-
-## Xema-as-Code — declarative stacks
-
-Drive a running control plane from a `xema.yaml` manifest (orgs, roles,
-deliverable-specs, biome-installs, …) — plan/apply/export/import, GitOps-style:
-
-```bash
-xema plan   -f xema.yaml                 # preview the change set (read-only)
-xema apply  -f xema.yaml                  # apply it (--auto-approve to skip the prompt)
-xema export --stack <name> -o xema.yaml   # snapshot a live stack to a manifest
-xema import -f xema.yaml                   # adopt existing resources into a stack
-#   target + auth: --endpoint/--token or env XEMA_ENDPOINT / XEMA_TOKEN
-```
-
-## Diagnose
-
-```bash
-xema doctor                 # node version + ~/.xema/ + dev KernelState
-xema doctor --infra         # also TCP-probe Postgres / Redis / event-hub-api
-xema doctor --sources       # list biome sources + per-source token presence (redacted)
-```
+| `edition` | Distribution edition id (default `oss`). |
+| `infra.<component>.mode` | `managed`, `external` (with `url`, optional `secretRef`) or `disabled`. Components: `postgres`, `redis`, `etcd`, `keycloak`, `objectStore`, `fga`, `git`, `temporal`. |
+| `app.substrate` | `container`, `native` or `helm`. |
+| `app.include` / `app.exclude` | `default`, `all`, tier names or service names / service names to drop. |
+| `app.features` | Curated capability bundles. |
+| `app.web.enabled` | Start the host-shell frontend. |
+| `secrets.<name>` | `{ from: env \| file \| prompt }`; files must be mode `0600` or stricter. |
+| `sources[]` | Biome sources: `kind: workspace \| distribution \| git`, with `authTokenEnv` naming an environment variable (never the token). |
+
+| Environment | Purpose |
+| --- | --- |
+| `XEMA_DEV` | Developer mode on or off. |
+| `XEMA_ENDPOINT`, `XEMA_TOKEN` | Platform API and bearer token for client commands. |
+| `XEMA_DEPLOYMENT_ENGINE` | Deployment engine bin for Kubernetes installations. |
+| `XEMA_NAMESPACE` | Kubernetes namespace (default `xema`). |
+| `XEMA_MANAGED_LOCAL_KEY_PROVIDER`, `XEMA_MANAGED_LOCAL_RECOVERY_KEY` | Managed-local secret custody on headless hosts. |
 
 ## License
 
-Apache-2.0 &copy; Neuralchowder Inc. — [xema.dev](https://xema.dev). `@xemahq/xema`
-is the open developer/operator tool tier (like the Xema SDKs), distributed under
-the Apache License 2.0. See [LICENSE](../../LICENSE) / [NOTICE](../../NOTICE).
+Apache-2.0 &copy; Xema &mdash; [xema.dev](https://xema.dev)

package/dist/commands/edition.js

@@ -7,7 +7,7 @@ const verb_map_1 = require("../runtime/edition/verb-map");
 const VERB_SUMMARY = {
     [verb_map_1.EditionVerb.Resolve]: 'Resolve the whole release lock set of an edition: xema edition resolve <id> [--check]; or a customer edition against the catalogue pinned in catalogue.pin.json beside the definition: xema edition resolve --definition <file> --channel <release|develop> --out <dir> [--source-image <source>=<registry>/<prefix>]...',
     [verb_map_1.EditionVerb.Seal]: 'Seal the image digests of an edition: xema edition seal <id> [--definition <file>] (a customer edition seals against the release catalogue pinned in catalogue.pin.json beside the definition)',
-    [verb_map_1.EditionVerb.Develop]: 'Resolve a develop edition snapshot: xema edition develop <resolve|target|freeze-graph|freeze-sources|check-existing|check-overrides> ...; or a customer develop edition (catalogue pinned in catalogue.pin.json beside the definition): xema edition develop <resolve|target|check-existing|freeze-sources|kernel-commit> --definition <file> ... (resolve: --pins <file> --out <dir> --registry <root> --engine-image <repo>@sha256:<digest> [--source-image <source>=<registry>/<prefix>]...; kernel-commit prints the contract authority source commit of the catalogue)',
+    [verb_map_1.EditionVerb.Develop]: 'Resolve a develop edition snapshot: xema edition develop <resolve|target|freeze-graph|freeze-sources|check-existing|check-overrides> ...; or a customer develop edition (catalogue pinned in catalogue.pin.json beside the definition): xema edition develop <resolve|target|check-existing|freeze-sources> --definition <file> ... (resolve: --pins <file> --out <dir> --registry <root> --engine-image <repo>@sha256:<digest> [--source-image <source>=<registry>/<prefix>]...)',
     [verb_map_1.EditionVerb.Artifact]: 'Write the OCI artifact files of a release edition from the committed sealed locks: xema edition artifact <id> --channel release --registry <root> --coordinate <tag> --engine-image <repo>@sha256:<digest> --out <dir>',
     [verb_map_1.EditionVerb.Catalogue]: 'Write the catalogue.json of a release offering from its committed sealed locks: xema edition catalogue <id> --out <dir>',
     [verb_map_1.EditionVerb.Index]: `Rebuild a catalogue index: xema edition index <${Object.values(verb_map_1.EditionIndexKind).join('|')}> [--check]; xema edition index runtime-image-source --repin-contract-authority --kernel-commit <40-hex> replaces only the contract authority of the committed index with the kernel checkout's at the stated commit (its HEAD must equal it)`,
@@ -19,8 +19,8 @@ const VERB_SUMMARY = {
     [verb_map_1.EditionVerb.VerifyEvidence]: 'Verify the signed image evidence of an edition with the pinned verifier bundle: xema edition verify-evidence <id> --evidence-root <dir> --descriptor <path> --state <path> --cosign <path> --git <path> [--json] --data-root <dir> --editions-root <dir> --kernel <dir>',
     [verb_map_1.EditionVerb.Evidence]: `Build, accept and plan image evidence (never signs): xema edition evidence <${Object.values(verb_map_1.EditionEvidenceKind).join('|')}> …`,
     [verb_map_1.EditionVerb.List]: 'Print the offering ids of an editions root as JSON: xema edition list --editions-root <dir>',
-    [verb_map_1.EditionVerb.Locks]: 'Print the validated locks of an edition as JSON: xema edition locks <id> --data-root <dir> --editions-root <dir> --kernel <dir>',
-    [verb_map_1.EditionVerb.ChartSet]: `Pin the chart set of the editions to the charts the registry serves: xema edition chart-set <${Object.values(verb_map_1.EditionChartSetOperation).join('|')}> [--check] --data-root <dir> --editions-root <dir> --deploy-root <dir> --kernel <dir>; source-commit prints the commit each publisher closed its locked set at (--data-root, --kernel)`,
+    [verb_map_1.EditionVerb.Locks]: 'Print the validated locks of an edition as JSON: xema edition locks <id> --channel <release|develop> --data-root <dir> --editions-root <dir> --kernel <dir>',
+    [verb_map_1.EditionVerb.ChartSet]: `Pin the chart set of the editions to the charts the registry serves: xema edition chart-set <${Object.values(verb_map_1.EditionChartSetOperation).join('|')}> [--check] --data-root <dir> --editions-root <dir> --kernel <dir>; source-commit prints the commit each publisher closed its locked set at (--data-root, --kernel)`,
     [verb_map_1.EditionVerb.BiomeManifests]: 'Print the pinned xema-biome.json of every biome of an edition as JSON: xema edition biome-manifests <id> --json --data-root <dir> --editions-root <dir> --sources-root <dir> --kernel <dir>',
     [verb_map_1.EditionVerb.Arming]: 'Print whether the data root evidence trust policy is armed on one channel as one JSON line, exiting 0 only when armed: xema edition arming --channel <release|develop> --data-root <dir> --kernel <dir>',
     [verb_map_1.EditionVerb.SourceClosure]: 'Print the source tree hash and workspace closure of a source directory at a commit as JSON: xema edition source-closure --repo <repo> --path <dir> --commit <sha> --sources-root <dir> --kernel <dir>',

package/dist/commands/edition.js.map

@@ -1 +1 @@
-{"version":3,"file":"edition.js","sourceRoot":"","sources":["../../src/commands/edition.ts"],"names":[],"mappings":";;AAyCA,0CAiBC;AA1DD,kDAA8D;AAC9D,4DAA8D;AAC9D,0DAA2H;AAW3H,MAAM,YAAY,GAA0C;IAC1D,CAAC,sBAAW,CAAC,OAAO,CAAC,EACnB,0TAA0T;IAC5T,CAAC,sBAAW,CAAC,IAAI,CAAC,EAAE,gMAAgM;IACpN,CAAC,sBAAW,CAAC,OAAO,CAAC,EAAE,6iBAA6iB;IACpkB,CAAC,sBAAW,CAAC,QAAQ,CAAC,EACpB,wNAAwN;IAC1N,CAAC,sBAAW,CAAC,SAAS,CAAC,EAAE,yHAAyH;IAClJ,CAAC,sBAAW,CAAC,KAAK,CAAC,EAAE,kDAAkD,MAAM,CAAC,MAAM,CAAC,2BAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,+OAA+O;IAC/V,CAAC,sBAAW,CAAC,KAAK,CAAC,EAAE,yDAAyD;IAC9E,CAAC,sBAAW,CAAC,GAAG,CAAC,EAAE,qEAAqE;IACxF,CAAC,sBAAW,CAAC,eAAe,CAAC,EAAE,qGAAqG;IACpI,CAAC,sBAAW,CAAC,eAAe,CAAC,EAAE,wEAAwE;IACvG,CAAC,sBAAW,CAAC,kBAAkB,CAAC,EAAE,mIAAmI;IACrK,CAAC,sBAAW,CAAC,cAAc,CAAC,EAC1B,yQAAyQ;IAC3Q,CAAC,sBAAW,CAAC,QAAQ,CAAC,EAAE,+EAA+E,MAAM,CAAC,MAAM,CAAC,8BAAmB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK;IACxJ,CAAC,sBAAW,CAAC,IAAI,CAAC,EAAE,6FAA6F;IACjH,CAAC,sBAAW,CAAC,KAAK,CAAC,EAAE,iIAAiI;IACtJ,CAAC,sBAAW,CAAC,QAAQ,CAAC,EAAE,gGAAgG,MAAM,CAAC,MAAM,CAAC,mCAAwB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,yLAAyL;IAClW,CAAC,sBAAW,CAAC,cAAc,CAAC,EAC1B,6LAA6L;IAC/L,CAAC,sBAAW,CAAC,MAAM,CAAC,EAClB,yMAAyM;IAC3M,CAAC,sBAAW,CAAC,aAAa,CAAC,EACzB,uMAAuM;CAC1M,CAAC;AAEF,SAAgB,eAAe,CAAC,OAAgB;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;IACvF,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,sBAAW,CAAC,EAAE,CAAC;QAC9C,OAAO;aACJ,OAAO,CAAC,IAAI,CAAC;aACb,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;aAC/B,QAAQ,CAAC,WAAW,EAAE,0DAA0D,CAAC;aACjF,kBAAkB,EAAE;aACpB,MAAM,CAAC,CAAC,IAAc,EAAE,EAAE;YACzB,IAAI,CAAC;gBACH,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAA,0BAAc,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAA,qBAAQ,EAAC,4BAAe,CAAC,YAAY,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACjG,CAAC;QACH,CAAC,CAAC,CAAC;IACP,CAAC;AACH,CAAC"}
+{"version":3,"file":"edition.js","sourceRoot":"","sources":["../../src/commands/edition.ts"],"names":[],"mappings":";;AAyCA,0CAiBC;AA1DD,kDAA8D;AAC9D,4DAA8D;AAC9D,0DAA2H;AAW3H,MAAM,YAAY,GAA0C;IAC1D,CAAC,sBAAW,CAAC,OAAO,CAAC,EACnB,0TAA0T;IAC5T,CAAC,sBAAW,CAAC,IAAI,CAAC,EAAE,gMAAgM;IACpN,CAAC,sBAAW,CAAC,OAAO,CAAC,EAAE,mdAAmd;IAC1e,CAAC,sBAAW,CAAC,QAAQ,CAAC,EACpB,wNAAwN;IAC1N,CAAC,sBAAW,CAAC,SAAS,CAAC,EAAE,yHAAyH;IAClJ,CAAC,sBAAW,CAAC,KAAK,CAAC,EAAE,kDAAkD,MAAM,CAAC,MAAM,CAAC,2BAAgB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,+OAA+O;IAC/V,CAAC,sBAAW,CAAC,KAAK,CAAC,EAAE,yDAAyD;IAC9E,CAAC,sBAAW,CAAC,GAAG,CAAC,EAAE,qEAAqE;IACxF,CAAC,sBAAW,CAAC,eAAe,CAAC,EAAE,qGAAqG;IACpI,CAAC,sBAAW,CAAC,eAAe,CAAC,EAAE,wEAAwE;IACvG,CAAC,sBAAW,CAAC,kBAAkB,CAAC,EAAE,mIAAmI;IACrK,CAAC,sBAAW,CAAC,cAAc,CAAC,EAC1B,yQAAyQ;IAC3Q,CAAC,sBAAW,CAAC,QAAQ,CAAC,EAAE,+EAA+E,MAAM,CAAC,MAAM,CAAC,8BAAmB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK;IACxJ,CAAC,sBAAW,CAAC,IAAI,CAAC,EAAE,6FAA6F;IACjH,CAAC,sBAAW,CAAC,KAAK,CAAC,EAAE,6JAA6J;IAClL,CAAC,sBAAW,CAAC,QAAQ,CAAC,EAAE,gGAAgG,MAAM,CAAC,MAAM,CAAC,mCAAwB,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,qKAAqK;IAC9U,CAAC,sBAAW,CAAC,cAAc,CAAC,EAC1B,6LAA6L;IAC/L,CAAC,sBAAW,CAAC,MAAM,CAAC,EAClB,yMAAyM;IAC3M,CAAC,sBAAW,CAAC,aAAa,CAAC,EACzB,uMAAuM;CAC1M,CAAC;AAEF,SAAgB,eAAe,CAAC,OAAgB;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;IACvF,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,MAAM,CAAC,sBAAW,CAAC,EAAE,CAAC;QAC9C,OAAO;aACJ,OAAO,CAAC,IAAI,CAAC;aACb,WAAW,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;aAC/B,QAAQ,CAAC,WAAW,EAAE,0DAA0D,CAAC;aACjF,kBAAkB,EAAE;aACpB,MAAM,CAAC,CAAC,IAAc,EAAE,EAAE;YACzB,IAAI,CAAC;gBACH,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAA,0BAAc,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC;gBAChD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAA,qBAAQ,EAAC,4BAAe,CAAC,YAAY,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;YACjG,CAAC;QACH,CAAC,CAAC,CAAC;IACP,CAAC;AACH,CAAC"}