@lenso/cli 0.2.17 → 0.3.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.
 
-## Install Lenso Console
+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.
+
+## 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
@@ -216,8 +236,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 +277,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`:
 

package/package.json

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