solverforge-cli 2.0.4

CLI for scaffolding and managing SolverForge constraint solver projects
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

# 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.0.4`.

Required Rust version: `1.95` or later.

New projects currently target these crate versions:

- `solverforge 0.11.1`
- `solverforge-ui 0.6.5`
- `solverforge-maps 2.1.4`

```bash
cargo install solverforge-cli
solverforge new my-scheduler
```

## Current Contract

Public scaffold path:

- `solverforge new <name>`

That command creates a neutral app shell. Users shape the app afterward through
facts, entities, solution/score metadata, variables, constraints, generated
data, and `solverforge.app.toml`. There are no public scaffold-family flags.

Planning variable kinds are canonical:

- `scalar` for single-value assignment variables backed by `--range <facts>`
- `list` for sequence variables backed by `--elements <facts>`

`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
```

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 generated 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.

## Command Surface

Core commands:

- `solverforge new <name>` creates the neutral scaffold. `--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 destroy fact|entity|variable|constraint|solution` removes
  generated resources and rewrites the app spec/UI projection.
- `solverforge check`, `solverforge info`, and `solverforge routes` inspect the
  generated project.
- `solverforge config show|set` reads and writes `solver.toml`.
- `solverforge server` runs the generated app through Cargo.
- `solverforge test` delegates to `cargo test`.
- `solverforge completions <shell>` emits shell completions.

Generated project manifests include `rust-version = "1.95"` and 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`

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 for the sibling `solverforge-rs`,
`solverforge-ui`, and `solverforge-maps` checkouts. 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-rs](https://github.com/solverforge/solverforge-rs):
[Extend the solver](https://github.com/solverforge/solverforge-rs/blob/main/docs/extend-solver.md)
and [Extend the domain](https://github.com/solverforge/solverforge-rs/blob/main/docs/extend-domain.md).

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).