Lenso Examples

Runnable examples for Lenso module authors.

This repository uses published packages for released contracts where available:

• lenso
• @lenso/remote-module-kit for the gRPC legacy transport example

The V8 proofs currently have two temporary sibling-repository dependencies until the matching contracts are published:

• TypeScript service examples resolve @lenso/service-kit and the V8 @lenso/remote-module-kit build from ../lenso-runtime-console.
• examples/rust-service points at the sibling ../lenso crate.

For local V8 verification, clone the matching V8 branches next to each other:

git clone --branch chore/open-source-hygiene https://github.com/LioRael/lenso-examples.git
git clone --branch chore/open-source-hygiene https://github.com/LioRael/lenso-runtime-console.git
git clone --branch chore/open-source-hygiene https://github.com/LioRael/lenso.git
pnpm --dir lenso-runtime-console install
pnpm --dir lenso-runtime-console --filter @lenso/remote-module-kit build
pnpm --dir lenso-runtime-console --filter @lenso/service-kit build
cd lenso-examples
pnpm install

Quick Start

Install dependencies and run the full example smoke:

pnpm install
pnpm smoke

Launchpad App

Use Launchpad when you want a generated service-ready app instead of wiring a host and services by hand:

cargo install lenso-cli
lenso app list
lenso app inspect support-desk
lenso app create ../support-desk --blueprint support-desk
cd ../support-desk
lenso app add support-sla
lenso app compose --repo-root . --addon support-sla --addon customer-profile --write-plan
lenso dev status
lenso dev doctor --write-state
lenso app plan --addon support-sla --write-plan
lenso app apply .lenso/app-change-plan.json --dry-run
lenso app verify --write-proof
lenso app diff
lenso app repair --dry-run
lenso agent context

The generated app includes a TypeScript support-api service, a Rust notification-worker service, lenso.system.json, lenso.workspace.json, and .lenso/launchpad.json. This repository keeps representative generated output under fixtures/launchpad/support-desk/.

V23 adds product blueprints and addons. The support-desk-addon fixture shows support-sla added to the app, .lenso/dev-doctor.json written by lenso dev doctor --write-state, and the matching lenso agent task handoff.

V24 adds App Proof for generated control-plane state. The support-desk-proof fixture shows .lenso/app-proof.json, a clean lenso app diff, and an agent handoff that marks service source files as user-owned code while generated Launchpad files can be safely repaired.

V25 adds App Change Plan before repair or addon application. The support-desk-change-plan fixture shows .lenso/app-change-plan.json for a safe support-sla addon apply, plus the matching agent handoff boundaries.

V26 adds App Composer. The support-desk-composer fixture shows a support-desk app composed with support-sla and customer-profile, a composition-aware .lenso/app-change-plan.json, and an agent task generated with lenso agent task --from-app-plan.

V27 adds local Capability Packs. The fixtures/capabilities/support-sla-pack fixture shows lenso capability init, lenso capability check, App Composer with --pack, and a capability-scoped agent handoff.

pnpm check:launchpad-fixtures

Blank Host Starter

Use the standalone CLI when you want a blank Rust host before installing services:

cargo install lenso-cli
lenso host init ../my-lenso-host
cd ../my-lenso-host
cp .env.example .env
lenso serve

The starter serves GET /v1/app/status, GET/POST /v1/app/items, /openapi.json, and the admin APIs. Keep this repository for runnable module examples; the host starter template is owned by the standalone lenso-cli repository.

Examples

Rust Manifest

examples/rust-manifest is a minimal Rust package using the published lenso facade. It declares a schema-admin manifest, runs manifest lints, and prints the manifest JSON:

pnpm rust-manifest

Rust Service Provider

examples/rust-service is a standalone Axum service provider. It exposes the rust-audit-log module through a service manifest, status endpoint, module manifest endpoint, and a direct HTTP route:

pnpm start:rust-service

Install its manifest into a local Lenso host:

lenso service install http://127.0.0.1:4130/lenso/service/v1/manifest

Print the manifest without starting the server:

pnpm rust-service:check

With the service running, emit a service package plus module release artifacts from its manifest URL:

pnpm service-package:rust-service

Then install the package artifact:

lenso service install dist/lenso-service/rust-audit-service/lenso.service-package.json \
  --base-url http://127.0.0.1:4130/lenso/service/v1

The example README includes the matching lenso service verify, install, upgrade-plan, rollback preview, and deployment export commands.

The Rust and TypeScript examples intentionally expose the same service contract shape: a service process provides one or more independently installed modules, while the Host owns auth, runtime queues, retries, outbox, and observability. V12 adds lenso.workspace.json at the repo root so the examples can also be treated as one local service workspace:

lenso service workspace list --workspace-file lenso.workspace.json
lenso service dev --workspace-file ../lenso-examples/lenso.workspace.json

Use the second command from a generated host repo when you want the host and example services to start together. After the services are running, workspace check verifies each example service directory, manifest, and status endpoint:

lenso service workspace check --workspace-file lenso.workspace.json

From a generated host repo, install a workspace provider by name:

lenso service install support-suite-provider --workspace-file ../lenso-examples/lenso.workspace.json

Or export the whole example workspace into the host service-start state shape:

lenso service workspace export \
  --workspace-file ../lenso-examples/lenso.workspace.json \
  --output .lenso/module-services.json

V18 adds lenso.system.json as the service system manifest. It describes the same examples as a business system: services own process targets, modules own capabilities, and dependencies show cross-service capability consumption.

lenso system graph --system-file lenso.system.json
lenso system plan --system-file lenso.system.json --check
lenso system diff --system-file lenso.system.json --repo-root fixtures/system-state/ready --check
lenso system apply --system-file lenso.system.json --dry-run
lenso system doctor --system-file lenso.system.json
lenso system release plan \
  --env staging \
  --system-file lenso.system.json \
  --repo-root fixtures/system-state/ready \
  --output fixtures/system-release/staging/system-release.json
lenso system release check fixtures/system-release/staging/system-release.json
lenso system runbook generate \
  fixtures/system-release/staging/system-release.json \
  --output fixtures/system-runbook/staging/system-runbook.json
lenso system runbook check fixtures/system-runbook/staging/system-runbook.json

Copy lenso.system.json into a host repo when you want Console Services to show the system plane next to provider lifecycle, rollout, release, and Remote Calls evidence. V19 adds system drift checks and safe apply. fixtures/system-state/ready contains the minimum host-local .lenso state for a clean system diff; remove a file from that fixture to see the doctor output point at the missing state. V20 adds system release train fixtures under fixtures/system-release/. The staging fixture is ready, the prod fixture is a promotion from staging, and blocked-drift shows the policy output when host-local state is missing. V21 adds generated system runbook fixtures under fixtures/system-runbook/. These are operator evidence artifacts generated from release plans, not module authoring inputs.

V11 examples keep lenso.module.v1 module contracts next to lenso.module-release.v1 release artifacts so module install remains the business-capability entrypoint and service install remains the provider/process entrypoint. The V8 proof path uses service operation metadata and checks across both TS services and the Rust Axum provider, including safe HTTP probes and runtime function declarations.

Hello Action Service

examples/hello-action is a starter service provider. It exposes:

• a service manifest at /lenso/service/v1/manifest;
• service status at /lenso/service/v1/status;
• the hello-action module below /lenso/service/v1/modules/hello-action;
• two HTTP routes, GET /hello/{name} and POST /greetings;
• two runtime functions, hello-action.say-hello.v1 and hello-action.record-greeting.v1;
• one declarative admin surface with a seed_greeting action and a fallback greetings schema-admin entity.

Start the module from the repository root:

pnpm start:hello-action

Or work inside the example package directly:

cd examples/hello-action
pnpm dev
pnpm smoke

Change the module by editing:

• src/module.ts for the manifest, handlers, and seed data;
• src/server.ts for local startup behavior;
• src/smoke.ts for executable expectations as the module grows;
• catalog-entry.json for optional discovery metadata.

The server prints a manifest URL like:

http://127.0.0.1:4100/lenso/service/v1/manifest

Use that URL with a local Lenso host checkout:

lenso service install http://127.0.0.1:4100/lenso/service/v1/manifest

The example does not ship a Runtime Console package, so there is no frontend package install step for this module.

The server reads PORT from the shell environment. The optional discovery record lives at examples/hello-action/catalog-entry.json and matches the default PORT=4100 documented in examples/hello-action/.env.example.

To verify the host-side install path without mutating a real Lenso checkout, run the integration smoke from this repository root:

pnpm host-smoke

It starts the service examples, creates temporary host repos, runs the real lenso module catalog add and lenso service install commands, and checks the generated .lenso/module-catalog.json, .env, and install receipts.

To run the example through a real host API and call its remote HTTP route via /modules/hello-action/http/greetings, follow docs/hello-action-host-run.md.

Account Profile Service

examples/account-profile keeps product profile data outside the first-party auth anchor. The service provider is account-profile-service; it provides the account-profile module with an auth dependency, profile records, organizations, memberships, HTTP routes, an admin action, and schema-admin pages.

Start it from the repository root:

pnpm start:account-profile

Smoke the module directly:

pnpm smoke:account-profile

Install its manifest into a local Lenso host:

lenso service install http://127.0.0.1:4120/lenso/service/v1/manifest

gRPC Notes Legacy Transport

examples/grpc-notes is the native gRPC compatibility example for the older remote-module transport. It exposes a module manifest over gRPC, schema-admin notes, GET /notes through the host proxy, and grpc-notes.summarize.v1 through the runtime function lane. The V5 HTTP service manifest path is shown by the HTTP examples above.

Start it from the repository root:

pnpm start:grpc-notes

Verify the gRPC protocol path:

pnpm smoke:grpc-notes

Install it into a local host with the checked-in manifest and a gRPC base URL:

lenso module catalog add ../lenso-examples/examples/grpc-notes/lenso.module.json --base-url grpc://127.0.0.1:50051 --summary "Native gRPC notes module"
lenso module add ../lenso-examples/examples/grpc-notes/lenso.module.json --base-url grpc://127.0.0.1:50051
lenso console package apply-plan

Support Ticket Service

examples/support-ticket is the agent-ready service demo. It turns a concrete business prompt into an independently running service that provides the support-ticket module with tickets data, HTTP routes, an admin action, a runtime escalation function, and Console-visible metadata:

Build a support ticket module for a Lenso app.

Run it from the repository root:

pnpm start:support-ticket

Smoke the module directly:

pnpm smoke:support-ticket

With the service running, emit a V9 service package artifact from its manifest URL:

pnpm service-package:support-ticket

Then install the package artifact:

lenso service install dist/lenso-service/support-suite-provider/lenso.service-package.json \
  --base-url http://127.0.0.1:4110/lenso/service/v1

Install the business module through the generated V10 module release artifact:

lenso module release inspect dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json
lenso module release check dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json \
  --base-url http://127.0.0.1:4110/lenso/service/v1
lenso module install dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json \
  --base-url http://127.0.0.1:4110/lenso/service/v1

Or add that release to the local catalog and install by module name:

lenso module catalog add dist/lenso-service/support-suite-provider/modules/support-ticket/lenso.module-release.json \
  --base-url http://127.0.0.1:4110/lenso/service/v1
lenso module install support-ticket

Plan and apply the next provider release from the host repository after the service has an install receipt:

lenso service release plan support-suite-provider \
  ../lenso-examples/dist/lenso-service/support-suite-provider/lenso.service-package.json \
  --output .lenso/support-suite-provider.release-plan.json
lenso service policy check .lenso/support-suite-provider.release-plan.json --fail-on breaking
lenso service release apply .lenso/support-suite-provider.release-plan.json

The apply step updates .lenso/service-releases.json; Console Services shows the latest release risk and recent release history for the provider.

Run the full service host path:

pnpm host-api-smoke:support-ticket

That starts the service, installs it into a temporary host, exercises the host-owned HTTP proxy and runtime path for its module, installs the first-party audit-log module by name, and verifies both support-ticket and Audit Events Data Surfaces. The smoke checks co-install visibility; support-ticket records do not create audit rows unless a module calls the audit-log writer API. For the manual walkthrough, see docs/support-ticket-service-module-run.md.

Repositories

• Backend framework: https://github.com/LioRael/lenso
• Runtime Console and service kit: https://github.com/LioRael/lenso-runtime-console