@lenso/cli 0.2.17 → 0.4.0

package/README.md

@@ -10,22 +10,42 @@ npm install -g @lenso/cli
 cargo install lenso-cli
 ```
 
-## Scaffold a host application
+## Application lifecycle
 
 ```sh
-lenso host init my-app
-cd my-app
-cp .env.example .env
-lenso serve
+lenso app compose ./support-desk \
+  --blueprint support-desk \
+  --implementation support-api=linked \
+  --apply
+cd support-desk
+lenso system dev
 ```
 
-The package name defaults to the target directory name and can be overridden with
-`--name`. Pass `--force` to scaffold into a non-empty directory.
+`lenso app compose` writes the exact `lenso.app.json` App Composition and lock.
+Its `--apply` flag atomically materializes that composition in the same command;
+it is not a separate lifecycle stage and does not create a plan artifact. The
+public application path is Compose, Run locally, Connect, and Status. Connect
+and Status happen in Lenso Console through a signed enrollment exchange. The
+CLI does not select an environment, deploy the application, release it, or
+connect it to Console.
+
+`lenso system check` remains a contract-validation command. `lenso host init`
+and `lenso serve` remain lower-level host development tools, not alternative
+application lifecycle stages.
+
+The former App Plan, Apply, Verify, Diff, Repair, Next, Upgrade, and Explain
+commands and the former System Init, AddService, AddModule, Plan, Diff, Apply,
+Doctor, Release, Runbook, and Graph commands are no longer public entrypoints.
+`lenso app compose` also no longer accepts `--write-plan`, `--explain`, or
+`--addon`. Its surviving `--apply` option is only the atomic materialization
+flag described above, not an Apply stage.
 
-## Install Lenso Console
+## Provision Lenso Console independently
 
 Lenso Console is installed as an independent Service, not embedded into a
-business Service. Obtain an official GitHub-attested Console Release Manifest,
+business Service. Provisioning Console is separate from connecting an
+application and does not grant Console production deployment or release
+authority. Obtain an official GitHub-attested Console Release Manifest,
 review the deterministic plan, and then approve that exact plan digest:
 
 ```sh
@@ -198,6 +218,36 @@ existing identity with `--identifier` or `--user-id`. Restart the Console API
 and Worker after bootstrapping. Business Service users and Auth state are never
 modified.
 
+After upgrading the CLI, reconcile an existing Operator with the current
+minimum scopes idempotently:
+
+```sh
+lenso console operator configure \
+  --console-root ../lenso-console \
+  --identifier admin@example.com
+```
+
+This preserves unrelated operators and explicit extra scopes while adding the
+System read/connect, artifact reconciliation, Surface Gateway, Auth, and Story
+capabilities required by the current Console workflow.
+
+Apply prepared signed connection evidence through one public, idempotent CLI
+entrypoint instead of a sequence of custom HTTP calls:
+
+```sh
+LENSO_CONSOLE_TOKEN='<operator-session-token>' \
+  lenso console connect \
+  --console-url http://127.0.0.1:3030 \
+  --bundle .lenso/console-connect.json
+```
+
+The `lenso.console-connect.v1` bundle contains signed enrollment receipts, an
+optional exact `console_composition` artifact effect, and the digest-bound
+System Connection request. The command reuses existing enrollments, reconciles
+artifacts, connects the System, and fails unless Console returns `connected`.
+Use `--token-file` with a private regular file for non-interactive operation;
+tokens and signing material are never printed or stored in the bundle.
+
 The generated host depends on the crates.io `lenso` crate with the `host`
 feature, which is the current narrow host API for booting API, worker, and
 migration entrypoints. See
@@ -216,8 +266,8 @@ running until Ctrl-C. New hosts run them in one local process; pass
 lenso module create billing
 ```
 
-Add `--with-console-ui` when the Module Release should also contain its isolated
-Console UI artifact:
+Add `--with-console-ui` when the Module Release should also contain its verified
+same-realm ESM Console UI artifact:
 
 ```sh
 lenso module create billing --with-console-ui
@@ -257,6 +307,47 @@ lenso system dev --scenario deadline-timeout --json
 lenso system dev --cleanup
 ```
 
+For a new product-shaped application, materialize one exact App Composition
+instead of layering generated state. The blueprint and implementation overrides
+are composition inputs; `lenso.app.json` is the only application composition
+and lock, with immutable Module release digests, implementation bindings,
+resolved dependency selections, and an optimistic revision:
+
+```sh
+lenso app compose ./support-desk --blueprint support-desk --apply
+lenso app compose --repo-root ./support-desk \
+  --implementation support-api=linked \
+  --observed-revision 1 --apply
+lenso system dev --system-file ./support-desk/lenso.app.json --dry-run --json
+lenso system dev --system-file ./support-desk/lenso.app.json
+```
+
+`lenso system dev` realizes service-backed bindings through a persistent Local
+Control Adapter. The coordinator may exit after reporting workload identities;
+the adapter and its explicitly started local workloads remain active. Use
+`lenso system dev --system-file ./support-desk/lenso.app.json --cleanup` to
+stop only the adapter-owned workloads. This path does not create a second App
+lock or copy process commands into `lenso.app.json`.
+
+The adapter state under `.lenso/local-control-adapter/<appId>/state.json`
+advertises its `adapterId`, exact `adapterWorkload`, loopback `endpoint`,
+`workloadControlProtocol`, `workloadControlSchemaDigest`, and exact
+`capabilities`. Without a server-side
+`LENSO_WORKLOAD_CONTROL_TOKEN` override, startup creates an owner-only local
+credential file and records only its `credentialFile` reference; the bearer
+token is never serialized into adapter state or HTTP responses.
+
+The Local Control Adapter advertises and accepts only `suspend` and `resume`.
+Each accepted mutation returns an asynchronous Operation Record identified by
+`operationId`; callers poll that handle for the Adapter's final result.
+
+Until the Workload Control contract from
+[LioRael/lenso#530](https://github.com/LioRael/lenso/pull/530) is published,
+the CLI keeps a private, frozen mirror of its wire DTOs and constants. The
+advertised schema digest and protocol conformance tests pin that bounded mirror
+to the reviewed contract without adding an unpublished dependency to the CLI
+package.
+
 The System graph remains in `lenso.system.json`. Local-only executable details
 live beside it in `lenso.system-sandbox.json`:
 
@@ -359,10 +450,34 @@ Workloads, move data, or change authority. Use `--repo-root` and
 `--modules-root` when the Module sources are not under the current repository's
 default `modules/` directory.
 
-Generated TS and Rust services also support `--check-release` to print the
-development module release descriptor before packaging.
-Before handing a service to another app or deployment pipeline, package-check
-the project and then emit a local service artifact:
+Generated TypeScript services expose the current Provider contract directly:
+
+```sh
+pnpm check
+pnpm module:release > lenso.module-release.json
+pnpm start
+```
+
+`pnpm start` serves the exact `lenso.provider.v1` descriptor, invocation,
+recovery, and acknowledgement endpoints. The descriptor digests are the same
+ones emitted in `lenso.module-release.json`.
+
+Install that release into the Host runtime inputs with the Provider URL, not
+the legacy Service discovery URL:
+
+```sh
+lenso module install ./lenso.module-release.json \
+  --base-url http://127.0.0.1:4100/lenso/provider/v1 \
+  --repo-root ../my-lenso-host
+```
+
+This writes `lenso.modules.json`, `lenso.modules.lock.json`, the Module Planning
+Context, and the local Service Installation Set consumed by Host startup. It
+does not write `SERVICE_MODULES` or treat an old install ledger as runtime
+truth.
+
+Before handing a legacy Service manifest to another app or deployment
+pipeline, package-check the project and emit a compatibility package:
 
 ```sh
 cd ../services/support-suite-provider
@@ -376,31 +491,29 @@ The package artifact contains the canonical `lenso.service.json`,
 `modules/<module>/lenso.module-release.json` file for each provided module.
 The service package records the provider name, version, and provided module
 names; each module release is the business-module install entrypoint.
-Operators can install a provider directly. For a local package artifact, still
-pass the runtime service base URL:
+Compatibility packages remain available for older Service discovery consumers:
 
 ```sh
 lenso service install dist/lenso-service/support-suite-provider/lenso.service-package.json \
   --base-url http://127.0.0.1:4100/lenso/service/v1
 ```
 
-Install and manage a Module through the stable lifecycle commands:
+Install current Provider Modules from an exact release. The endpoint must end
+in `/lenso/provider/v1`:
 
 ```sh
-lenso module install dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json \
-  --base-url http://127.0.0.1:4100/lenso/service/v1
-lenso module disable support-ticket
-lenso module remove support-ticket
-lenso module doctor support-ticket
+lenso module install ./lenso.module-release.json \
+  --base-url http://127.0.0.1:4100/lenso/provider/v1
 ```
 
-`lenso.module-release.v1` is the module release channel. It records the module
-name, version, capabilities, source, and optional provider pointer. V11 keeps
-`lenso module install` as the unified business-capability entrypoint:
+`lenso.module-release.v1` is the current Module release channel. It records a
+fully qualified Module ID, canonical Manifest digest, exact delivery, governing
+contract digests, and optional release-bound `console_ui_esm` artifact.
 
-- `source: service` resolves to a provider service package or service manifest.
-- `source: linked` enables linked Rust code in the host.
-- `source: bundled` enables a host-bundled module.
+- Service delivery resolves to a locked Provider export and Service Installation.
+- Linked delivery resolves to an immutable crate release and Host binding.
+- A Console Surface exists only when the same exact release carries a
+  `console_ui_esm` artifact and Console has reconciled its receipt.
 
 `lenso service install` remains the lower-level provider/process command. It
 connects a service, but it does not mean every module inside that service is
@@ -429,24 +542,13 @@ longer copies packages into a Console checkout or maintains extension registries
 ## Install a module
 
 ```sh
-lenso module install auth
-lenso module install auth-password
-lenso module install auth-oidc
-lenso module install auth-device
+lenso module install ./releases/auth/lenso.module-release.json
+lenso module install ./releases/auth-password/lenso.module-release.json
 ```
 
-`module install` reads `source` from the module descriptor when one is present.
-When the reference is a module name, the CLI resolves it from the official
-catalog at `https://catalog.lenso.dev/v1/modules.json` unless `--catalog-url`
-points at another registry. If the primary official catalog endpoint is
-temporarily blocked by edge security, the CLI falls back to the official
-workers.dev mirror at `https://lenso-catalog.lenso.workers.dev/v1/modules.json`.
-For V5 service-backed modules, `module install <name>` is the business-capability
-entrypoint: the catalog resolves the provider service, installs it when needed,
-then enables the requested module.
-For module releases, `module install <module-release.json>` resolves the
-release by source, then records `moduleRelease` provenance in
-`.lenso/module-installs.json` where the source supports a receipt.
+Prefer an exact Module Release reference. Name-based catalog entries are accepted
+only as a compatibility path and may describe a legacy linked install; they do
+not prove that a current Console Surface artifact exists.
 
 Install a service directly when you have a workspace service name or manifest
 reference:
@@ -464,12 +566,11 @@ also infer `--base-url`; package artifacts outside that workspace still need
 `--base-url` so the host records the runtime service endpoint rather than the
 file path.
 
-Service installs update `SERVICE_MODULES` and record `.lenso/module-installs.json`
-in one step. Console UI artifacts remain immutable members of their Module
-Release and are bound only by an applied Console Service Composition. Linked modules update the
-host `Cargo.toml`, `src/lib.rs`, `.env` toggle, and the same install receipt
-from the descriptor's `linked` section. `module add` remains a compatibility
-alias for service installs.
+Exact Provider installs update the App Module lock and local Service
+Installation Set in one step. Console UI artifacts remain immutable members of
+their Module Release and are bound only by an applied Console composition.
+Legacy linked descriptors still update host source and their compatibility
+receipt, but that receipt is not an App Composition or a Surface grant.
 
 Legacy `lenso module install <manifest-url>` still works for one compatibility
 window, but prints a deprecation warning. Use `lenso service install <manifest>`
@@ -570,11 +671,9 @@ lenso service doctor billing --json
 lenso service check billing --json
 ```
 
-The doctor reads `SERVICE_MODULES`, `.lenso/module-installs.json`, and
-`.lenso/module-services.json`. It reports whether the service is
-installed, configured, whether an HTTP manifest is reachable, whether managed
-service `readyUrl` endpoints are ready, and which stale `.lock`/`.pid` files
-may be blocking a host-started service.
+The legacy doctor still reports compatibility Service discovery state. For a
+current Provider, verify `lenso.modules.lock.json`, the local Service
+Installation Set, and the live `/lenso/provider/v1` descriptor at Host startup.
 
 Export declared service processes as a Compose fragment when handing the
 service to deployment tooling:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenso/cli",
-  "version": "0.2.17",
+  "version": "0.4.0",
   "description": "Lenso command-line interface for scaffolding and operating Lenso backend projects.",
   "license": "MIT",
   "homepage": "https://github.com/LioRael/lenso-cli",