Local App development and Engine

Build from local Plugin sources, select optional conventions, or use Engine without an App.

Engine is independently delivered: lenso-engine 0.1.1 and the optional App, Runtime, Authoring, Markdown, Worker and Host packages at 0.1.0 are published on crates.io. The generic Engine can be consumed directly as a library. CLI and Console development kits have separate release paths. Before using the App commands below, run lenso app --help and lenso engine --help against the installed binary; the Engine library version alone does not identify CLI features.

Create an App without configuration

lenso app create my-app --runtime bun
cd my-app
lenso app dev
# After stopping development:
lenso app build
lenso app start --from dist

app/ holds App-owned Plugin sources. plugins/ holds Instance configuration and disabled markers. A basic source App needs no lenso.toml, Host declaration, preset or activation flag. The default scaffold runtime is process; bun, wasm, multi, and empty are explicit alternatives. Rust source builds need the corresponding Rust toolchain; Bun-only Apps use a precompiled runtime.

Add local discovery locations only when needed:

# Optional lenso.toml
plugin_sources = ["../shared-plugins", "../packages/*"]

These are local discovery sources, not marketplace endpoints. Shared candidates are built/admitted only when selected through a Root entry such as plugins/example.audit/default.toml. App-owned Plugins get a disableable default Instance. Duplicate identities and unresolved requirements fail explicitly.

lenso app discover --json
lenso app build --out dist-review
lenso app check --root dist-review
lenso app show --root dist-review --json
lenso app start --from dist-review --check

Build writes a new output directory and refuses to overwrite an existing one. The distribution includes the selected Host, resolver, artifacts, Bun when needed, Root intent and integrity metadata. It runs without source, Cargo or Bun on PATH. Runtime packaging and a reproducible source archive are distinct.

Development rebuilds and restarts generations. A build failure keeps the last running generation. A startup failure after a successful build is reported; zero-downtime replacement and automatic rollback are not promised.

Choose a development experience

• File conventions: CLI commands, Rust macros, Agent Tools and optional package boundaries.
• App Console: pages, owner services and a development kit that needs no Rust toolchain.
• Local Capability generation: lenso app contract new example.text creates a Descriptor/JSON Schema package and TypeScript projection under contracts/. --source rust instead creates a Rust contract package and needs Cargo. app build / app dev synchronize selected contracts before compiling consumers. Production startup runs no generator. Continue with Capability authoring for role and version rules.

Existing custom Hosts, Plugin SDKs, plugin dev and lower-level APIs remain available. Conventions lower into those same contracts and runtime boundaries.

Use Engine without an App

Engine is an independently embeddable authoring layer in the lenso-engine repository. Rust packages live under crates/; the CLI consumes the libraries. The core handles immutable inputs, processing plans, dependency ordering, sessions and publication. App composition is an optional processor.

lenso engine inspect --source ./content --markdown
lenso engine run --source ./content --markdown
lenso engine dev --source ./content --markdown --output ./dist

This Markdown path needs no App, Cargo or Bun. A file such as plugin.rs has no meaning unless the corresponding support is selected. Processor behavior may read, parse, compile, transform or index; it is not limited to compilation. Rust, Bun, Python and other executable tools can implement the versioned JSON processor protocol. This does not add a business Plugin runtime Adapter.

For custom processing, an engine.json workflow separates input sources from local processor sources and explicit activation:

{
  "schema": "lenso.engine-workflow.v1",
  "sources": ["content"],
  "plugin_sources": ["tools"],
  "plugins": ["example.reader.v1"],
  "presets": []
}

The local tools directory must contain a valid engine-plugin.json for that identity and its existing executable/artifacts. Use Engine’s maintained README and examples for the processor protocol before running:

lenso engine lock --workflow engine.json
lenso engine run --workflow engine.json --output dist

Locking hashes existing selected tools, artifacts and configuration without installing or compiling. Execution verifies the host-local lock. Tool or config changes require re-locking; source documents remain editable. Bootstrap uses already executable processors, avoiding a dependency on their own source-file convention to load themselves.