# solverforge-cli
Default entry point for new SolverForge projects.
Use this CLI to scaffold, grow, and validate SolverForge applications. The CLI
is its own versioned product: `solverforge --version` reports the CLI package
version and the scaffold dependency targets separately.
Current CLI package version: `2.2.0`.
Required Rust version: `1.95` or later.
New projects currently target these crate versions:
- `solverforge 0.15.0`
- `solverforge-ui 0.6.5` for the default web shell
- `solverforge-maps 2.1.4` for the default web shell
```bash
cargo install solverforge-cli
solverforge new my-scheduler
```
## Current Contract
Public scaffold path:
- `solverforge new <name>`
That command creates a neutral app shell. The default shell is `web`; use
`--shell api` for an HTTP API without frontend assets or `--shell cli` for a
Clap command-line app without Axum. Users shape the app afterward through
facts, entities, solution/score metadata, variables, constraints, generated
data, and `solverforge.app.toml`. Shell choice is recorded as
`[app].shell`; it is not a modeling family selector. The current public shell
set is exactly `web`, `api`, and `cli`; a Tauri shell is intentionally deferred
and is not generated by this release line.
Planning variable kinds are canonical:
- `scalar` for single-value assignment variables backed by `--range <facts>`
- `list` for sequence variables backed by `--elements <facts>`
Scalar variables can also carry opt-in SolverForge hook metadata for
model-owned candidate selection, nearby candidate selection, distance meters,
and construction ordering:
```bash
solverforge generate variable resource_idx --entity Task --kind scalar --range resources \
--candidate-values resource_candidates \
--nearby-value-candidates nearby_resources \
--nearby-entity-candidates nearby_tasks \
--nearby-value-distance-meter resource_distance \
--nearby-entity-distance-meter task_distance \
--construction-entity-order-key task_priority \
--construction-value-order-key resource_priority
```
Those flags only write `#[planning_variable(...)]` metadata and project it into
`solverforge.app.toml`. Web-shell projects also project that metadata into
`static/generated/ui-model.json`; users still own the Rust hook functions.
Scalar groups and conflict repairs are opt-in modeling resources. They are
identified only by exact IDs: scalar-group names and snake_case constraint IDs.
Unless `--skip-solver-config` is passed, `solverforge generate scalar-group`
writes both grouped construction and grouped local-search `solver.toml` refs
for assignment-backed and candidate-backed groups. `solverforge check` validates
those refs across the solver config graph, including construction phases,
top-level selectors, neighborhoods, nested selector children, and partition
child phases. The CLI writes those generated refs inside one
`# @solverforge:begin solver-config` / `# @solverforge:end solver-config`
region with exact-ID owner comments for each generated phase; generated apps
still consume plain `solver.toml` through the umbrella `solverforge` crate.
`standard` is only a demo dataset size label in `solverforge.app.toml`; it is
not a variable kind.
Basic domain flow:
```bash
solverforge new my-scheduler
cd my-scheduler
solverforge generate fact resource --field category:String --field load:i32
solverforge generate entity task --field label:String --field priority:i32
solverforge generate variable resource_idx --entity Task --kind scalar --range resources --allows-unassigned
solverforge generate data --size large
solverforge server
```
Shell variants:
```bash
solverforge new batch-scheduler --shell cli
solverforge new service-scheduler --shell api
```
Generated projects use managed block markers as the canonical CLI edit points.
Domain exports, solution collections, entity variables, constraint modules, and
constraint calls must retain their `@solverforge:begin ...` /
`@solverforge:end ...` regions for later `generate` and `destroy` commands.
Project-local `.solverforge/templates/entity.rs.tmpl` and
`.solverforge/templates/solution.rs.tmpl` overrides are supported only when
they emit those same canonical managed blocks.
`solverforge generate data` owns the generated data pipeline. It keeps
`src/data/mod.rs` as the stable import wrapper, rewrites
`src/data/data_seed.rs` with deterministic sample builders, and persists
dataset size defaults in `solverforge.app.toml`. `sample` is the default mode;
`stub` is available for shape-only data. The supported demo size labels are
`small`, `standard`, and `large`. Generated values are structurally useful
rather than domain-specific fake business data.
The default web-shell frontend is intentionally thin. It composes shipped
`solverforge-ui 0.6.5` primitives such as `SF.createBackend(...)`,
`SF.createSolver(...)`, and `SF.rail.createTimeline(...)` instead of vendoring
app-specific UI frameworks. Domain-specific examples belong in quickstarts, not
in the built-in scaffold catalog. API-shell and CLI-shell projects do not
generate `static/`, `static/generated/ui-model.json`, or `ui_source`; later
domain mutations keep that shell boundary intact.
## Command Surface
Core commands:
- `solverforge new <name>` creates the neutral scaffold. `--shell web|api|cli`
selects the generated app shell; `web` is the default. `--skip-git` skips the
initial Git repository/commit, and `--skip-readme` skips the generated project
README.
- `solverforge generate fact|entity|variable|constraint|solution|score|data`
mutates the current project through the canonical generated surfaces.
- `solverforge generate scalar-group|conflict-repair` wires opt-in model
resources by exact ID.
- `solverforge destroy fact|entity|variable|constraint|solution|scalar-group|conflict-repair`
removes generated resources and rewrites the app spec/UI projection.
- `solverforge check`, `solverforge info`, and `solverforge routes` inspect the
generated project. `routes` applies only to web/API shells.
- `solverforge config show|set` reads and writes non-phase `solver.toml`
settings. Ordered `phases` edits are manual. Generated model-resource refs in
that file are exact-ID graph references, not aliases; destroy re-renders the
CLI-managed solver config region and blocks when nested or user-authored
solver config still references the resource.
- `solverforge server` runs web/API generated apps through Cargo. CLI-shell
projects run directly with `cargo run -- demo-data`.
- `solverforge test` delegates to `cargo test`.
- `solverforge completions <shell>` emits shell completions.
Generated project manifests include `rust-version = "1.95"` and dependencies
for the selected shell. The web shell includes the current direct web/runtime
support dependencies:
- `axum 0.8.9`
- `tokio 1.52.2`
- `tokio-stream 0.1.18`
- `tower-http 0.6.8`
- `tower 0.5.3`
- `serde 1.0.228`
- `serde_json 1.0.149`
- `uuid 1.23.1`
- `parking_lot 0.12.5`
The API shell keeps `solverforge`, Axum, Tokio, SSE, serialization, and
`parking_lot`, but excludes `solverforge-ui`, `solverforge-maps`, and static
file serving. The CLI shell keeps `solverforge`, Clap, Tokio, serialization,
and `parking_lot`, but excludes Axum, `tower-http`, `tokio-stream`,
`solverforge-ui`, `solverforge-maps`, and `static/`.
Persistent `.solverforgerc` files are loaded from the project root first and
then from `~/.solverforgerc`. Recognized preferences are intentionally narrow:
`port`, `no_color`, and `quiet`.
## Validation Flow
End-to-end validation is split into explicit phases so the real production
pipeline stays readable:
- `cargo test`
Rust unit tests, scaffold contract tests, and generated-app runtime pipeline tests
- `make test-runtime`
phase-marked runtime pipeline against ephemeral generated apps only
- `make test-e2e`
Playwright browser tests against ephemeral generated apps only
- `make install-e2e`
install Playwright Chromium locally before the first browser run
- `make test-full`
full pipeline: binary/unit tests, scaffold contract tests, runtime pipeline,
then Playwright
The runtime and browser suites both scaffold fresh temp apps, mutate them
through the real CLI, boot the generated servers on random ports, and clean up
automatically. Failure artifacts are written under `target/test-artifacts/`.
By default, end-to-end validation keeps generated temp-app `Cargo.toml` files on
the published crate targets. To test a prerelease local ecosystem, set
`SF_USE_LOCAL_PATCHES=1`; the harness writes a temporary `.cargo/config.toml`
with explicit `[patch.crates-io]` entries only for dependencies present in the
generated manifest. Generated manifests are not rewritten.
Current scenario coverage:
- neutral shell: scaffold, boot, and verify the empty production shell
- mixed app: scaffold mixed shape, seed non-empty mixed demo data, and verify
generated runtime/browser surface
- scalar-only app: seed non-empty data and run it through the real generated
solver, including typed SSE, status, analysis, checkpointed Pause/Resume,
user-facing Stop as runtime cancel, terminal-only Delete, and status/snapshot
reconnect bootstrap
The mixed generated app is intentionally not the seeded solve scenario today.
The current SolverForge runtime does not yet support solving that mixed
scalar-plus-list combination end to end, so the test suite keeps that boundary
visible.
For solver and domain extension guidance after scaffolding, see the runtime docs
in [solverforge](https://github.com/SolverForge/solverforge):
[Extend the solver](https://github.com/SolverForge/solverforge/blob/main/docs/extend-solver.md)
and [Extend the domain](https://github.com/SolverForge/solverforge/blob/main/docs/extend-domain.md).
## License
Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).