hero_rpc#129: scaffolder examples/ + benches/ + serial_test dev-dep + osis_benches symmetry #139

Merged

timur merged 2 commits from issue-129-examples-benches into development 2026-05-25 10:47:23 +00:00

Conversation 0 Commits 2 Files changed 26 +665 -21

timur commented 2026-05-25 10:35:37 +00:00

Owner

Copy link

Summary

Phase 1 + Phase 6 of hero_rpc#129 (lifecycle alignment, part 2). The scaffolder now emits two workspace-root crates the consumer-service layout sanctions (examples/ and benches/) on every scaffold, pre-installs serial_test so contributors don't have to amend tests/Cargo.toml first, and moves crates/osis_benches/ → benches/ for symmetry with the consumer layout (the crate keeps its hero_rpc_osis_benches package name).

Sibling PRs landing alongside:

• lhumina_code/hero_skills — --example + --bench verbs + dual-home --test dispatch + skill docs.
• lhumina_code/hero_service — re-scaffold against this generator to pick up the new emissions.

Scope per the issue body

• §1 examples/ scaffolded at workspace root (01_connect.rs + wrapper Cargo.toml, regen-once).
• §5 benches/ workspace member crate at root (re-exports <name>_tests::* for shared spin_up_service).
• §7 serial_test = "3" under [dev-dependencies] in scaffolded tests/Cargo.toml.
• §8 (optional) crates/osis_benches/ → benches/ move. Cosmetic-only; no functional change.
• --no-examples / --no-benches flags surfaced on the hero_rpc_generator CLI binary mirroring --no-tests / --no-web.

Out of scope here (in sibling PRs):

• §2 (--example verb), §3 (dual-home --test), §6 (--bench verb), §4 (skill text) — hero_skills PR.
• Re-scaffolded hero_service consuming all the above — hero_service PR.

Tests

5 new scaffolder tests (29 total green; 0 ignored):

• test_scaffold_tests_cargo_toml_has_serial_test_dev_dep
• test_scaffold_emits_examples_crate
• test_scaffold_emits_benches_crate
• test_workspace_cargo_toml_lists_examples_and_benches
• test_workspace_cargo_toml_omits_examples_and_benches_when_disabled

cargo check --workspace green including the relocated hero_rpc_osis_benches (now at benches/).

Diff stat highlights

 crates/generator/src/build/scaffold.rs       | +629
 crates/generator/src/bin/scaffold.rs         | +21  (--no-examples / --no-benches)
 Cargo.toml                                   | -1 / +1  (osis_benches -> benches member)
 BENCH_RESULTS.md                             | -1 / +5  (path reference)
 {crates/osis_benches => benches}/...         | rename only, 100% content match

Decisions taken without confirmation

1. examples/ is a real workspace member (with Cargo.toml + src/lib.rs) rather than a bare directory at root. Cargo can only run examples that belong to a package, so a virtual workspace can't host a loose examples/. The wrapper package (<name>_examples) is the smallest change that lets cargo run -p <name>_examples --example <foo> work — which is what the lab --example verb dispatches through. [[example]] entries point at 01_connect.rs directly so the file sits at the package root, not under a nested examples/examples/.

2. benches/ gated on generate_tests. The starter shape re-exports <name>_tests::spin_up_service; without tests/ that path dep would dangle.

3. No lab CLI scaffold subcommand wiring. A grep across hero_skills/crates/lab/src/ turned up no scaffold invocation, so the new --no-examples / --no-benches flags are only on the standalone hero_rpc_generator binary. When/if a lab scaffold verb lands, wiring the two flags is a one-line append per opt-out.

Test plan

• cargo test -p hero_rpc_generator --lib build::scaffold:: — 29/29 green
• cargo check --workspace — green incl. relocated hero_rpc_osis_benches
• hero_rpc_generator --help shows the two new --no-* flags
• hero_service re-scaffolded against this branch emits examples/01_connect.rs + benches/Cargo.toml (see sibling hero_service PR)

Closes part of hero_rpc#129 (Phase 1 + Phase 6).

## Summary Phase 1 + Phase 6 of hero_rpc#129 (lifecycle alignment, part 2). The scaffolder now emits two workspace-root crates the consumer-service layout sanctions (`examples/` and `benches/`) on every scaffold, pre-installs `serial_test` so contributors don't have to amend `tests/Cargo.toml` first, and moves `crates/osis_benches/` → `benches/` for symmetry with the consumer layout (the crate keeps its `hero_rpc_osis_benches` package name). Sibling PRs landing alongside: - lhumina_code/hero_skills — `--example` + `--bench` verbs + dual-home `--test` dispatch + skill docs. - lhumina_code/hero_service — re-scaffold against this generator to pick up the new emissions. ## Scope per the issue body - [x] §1 `examples/` scaffolded at workspace root (`01_connect.rs` + wrapper Cargo.toml, regen-once). - [x] §5 `benches/` workspace member crate at root (re-exports `<name>_tests::*` for shared `spin_up_service`). - [x] §7 `serial_test = "3"` under `[dev-dependencies]` in scaffolded `tests/Cargo.toml`. - [x] §8 (optional) `crates/osis_benches/` → `benches/` move. Cosmetic-only; no functional change. - [x] `--no-examples` / `--no-benches` flags surfaced on the `hero_rpc_generator` CLI binary mirroring `--no-tests` / `--no-web`. Out of scope here (in sibling PRs): - §2 (`--example` verb), §3 (dual-home `--test`), §6 (`--bench` verb), §4 (skill text) — hero_skills PR. - Re-scaffolded hero_service consuming all the above — hero_service PR. ## Tests 5 new scaffolder tests (29 total green; 0 ignored): - `test_scaffold_tests_cargo_toml_has_serial_test_dev_dep` - `test_scaffold_emits_examples_crate` - `test_scaffold_emits_benches_crate` - `test_workspace_cargo_toml_lists_examples_and_benches` - `test_workspace_cargo_toml_omits_examples_and_benches_when_disabled` `cargo check --workspace` green including the relocated `hero_rpc_osis_benches` (now at `benches/`). ## Diff stat highlights ``` crates/generator/src/build/scaffold.rs | +629 crates/generator/src/bin/scaffold.rs | +21 (--no-examples / --no-benches) Cargo.toml | -1 / +1 (osis_benches -> benches member) BENCH_RESULTS.md | -1 / +5 (path reference) {crates/osis_benches => benches}/... | rename only, 100% content match ``` ## Decisions taken without confirmation 1. **`examples/` is a real workspace member** (with `Cargo.toml` + `src/lib.rs`) rather than a bare directory at root. Cargo can only run examples that belong to a package, so a virtual workspace can't host a loose `examples/`. The wrapper package (`<name>_examples`) is the smallest change that lets `cargo run -p <name>_examples --example <foo>` work — which is what the lab `--example` verb dispatches through. `[[example]]` entries point at `01_connect.rs` directly so the file sits at the package root, not under a nested `examples/examples/`. 2. **`benches/` gated on `generate_tests`.** The starter shape re-exports `<name>_tests::spin_up_service`; without `tests/` that path dep would dangle. 3. **No lab CLI scaffold subcommand wiring.** A grep across `hero_skills/crates/lab/src/` turned up no scaffold invocation, so the new `--no-examples` / `--no-benches` flags are only on the standalone `hero_rpc_generator` binary. When/if a lab scaffold verb lands, wiring the two flags is a one-line append per opt-out. ## Test plan - [x] `cargo test -p hero_rpc_generator --lib build::scaffold::` — 29/29 green - [x] `cargo check --workspace` — green incl. relocated `hero_rpc_osis_benches` - [x] `hero_rpc_generator --help` shows the two new `--no-*` flags - [x] hero_service re-scaffolded against this branch emits `examples/01_connect.rs` + `benches/Cargo.toml` (see sibling hero_service PR) Closes part of hero_rpc#129 (Phase 1 + Phase 6).

timur added 1 commit 2026-05-25 10:35:37 +00:00

hero_rpc#129: scaffolder examples/ + benches/ + serial_test dev-dep + osis_benches symmetry ... dcc138f549

Phase 1 of the lifecycle-alignment part 2 follow-up — the scaffolder
now emits the two workspace-root crates the consumer-service layout
sanctions (`examples/` and `benches/`) on every scaffold, and
pre-installs `serial_test` so contributors who need
`#[serial_test::serial]` to gate env-mutating tests don't have to
amend `tests/Cargo.toml` first.

Scaffolder additions
--------------------

`examples/` workspace member — `<name>_examples` package with one
starter `01_connect.rs`. The example reads `HERO_TEST_SOCKET`
(exported by `lab service <name> --example` from the JSON envelope of
the ephemeral it spawns), connects via `hero_rpc2::ClientBuilder`,
and calls `<root>_list` on the first discovered rootobject — the
canonical 30-line "SDK works against this service" demo. Cargo.toml
registers `[[example]] path = "01_connect.rs"` explicitly so the
file lives at the package root rather than under
`examples/examples/`. Lab dispatches via `cargo run -p
<name>_examples --example 01_connect`.

`benches/` workspace member — `<name>_benches` package whose
`src/lib.rs` re-exports `<name>_tests::*` so subprocess-driver
benches can call `<name>_benches::spin_up_service` without
duplicating the lab subprocess bootstrap. Ships a commented-out
`example_bench.rs` criterion skeleton plus a commented-out `[[bench]]`
entry in Cargo.toml; contributors uncomment, edit, and add real
measurements. Gated on `generate_tests` — opting `tests/` out also
opts `benches/` out, since the path dep would dangle.

`tests/Cargo.toml` `[dev-dependencies]` — adds `serial_test = "3"`.
The single addition contributors most frequently need on day one and
the cheapest dep to ship pre-installed (~50 KB compile cost, paid
only on `cargo test`).

Symmetry move
-------------

`crates/osis_benches/` → `benches/`. Cosmetic-only, requested in
hero_rpc#129 item 8. The package keeps its `hero_rpc_osis_benches`
name so `cargo bench -p hero_rpc_osis_benches --bench index_perf` is
unchanged. The crate retains its in-process direct-handler bootstrap
(no lab subprocess — hero_rpc is the library that *defines*
`MultiDomainBuilder`; calling lab from it would be circular). The
workspace member entry and a `BENCH_RESULTS.md` path reference are
the only edits beyond the rename.

Tests
-----

Adds five scaffolder tests:

  - `test_scaffold_tests_cargo_toml_has_serial_test_dev_dep`
  - `test_scaffold_emits_examples_crate`
  - `test_scaffold_emits_benches_crate`
  - `test_workspace_cargo_toml_lists_examples_and_benches`
  - `test_workspace_cargo_toml_omits_examples_and_benches_when_disabled`

29/29 scaffolder tests green; `cargo check --workspace` green
including the relocated `hero_rpc_osis_benches`.

Decisions taken without confirmation
------------------------------------

1. `examples/` is a real workspace member (with its own `Cargo.toml`
   and `src/lib.rs`) rather than a bare directory of `.rs` files at
   workspace root. Cargo can only compile examples that belong to a
   package, so a virtual workspace can't host a "loose" examples/
   directory. Making it a workspace member is the smallest change
   that lets `cargo run -p <name>_examples --example <foo>` work
   (which is what `lab service <name> --example <foo>` will dispatch
   to in the hero_skills follow-up). Each `.rs` file under
   `examples/` is registered as an explicit `[[example]]` so the file
   sits at the package root, not in a nested `examples/examples/`.

2. `benches/` gated on `generate_tests`. The starter shape re-exports
   `<name>_tests::spin_up_service`; without `tests/` that path dep
   would dangle. Opting out of tests but in to benches isn't a shape
   anyone has asked for, so the gate keeps the scaffolder honest.

3. New scaffolder flags default-on (`with_examples` / `with_benches`)
   mirroring the existing `with_tests` / `with_web` defaults. The lab
   CLI subcommand `--no-examples` / `--no-benches` is not surfaced in
   this PR — lab doesn't currently expose a scaffold verb at all (the
   audit pass turned up no scaffold callsite in
   `hero_skills/crates/lab/src/`). When/if a lab scaffold verb lands,
   wiring the two new flags is a one-line append per opt-out.

timur added 1 commit 2026-05-25 10:41:21 +00:00

chore(fmt): cargo fmt drift after scaffolder additions ... 054ce18106

CI flagged six files on the `Test / test (push)` run for this branch:

  crates/generator/src/build/scaffold.rs     (new tests + extracted helpers)
  crates/generator/src/build/layout.rs       (pre-existing long-string wrap)
  crates/generator/src/build/tests_emit.rs   (pre-existing import re-order)
  crates/generator/src/bin/scaffold.rs       (new --no-* flags)
  crates/osis/src/index/remote.rs            (pre-existing blank-line at fn open)
  crates/osis/src/rpc/bootstrap.rs           (pre-existing trailing blank line)

`cargo fmt --all` applied. No behavioural change — `cargo test -p
hero_rpc_generator --lib build::scaffold::` still 29/29 green after
the reformat. The four pre-existing files are bundled in this commit
(rather than split into a separate "chore: fmt drift on dev" PR)
because dev's CI is currently red on the same diffs and splitting
the work would block this PR on a chore PR that nobody is going to
prioritize.

timur merged commit 4b3bee48f9 into development 2026-05-25 10:47:23 +00:00

timur referenced this pull request from a commit 2026-05-25 10:47:24 +00:00

hero_rpc#129: scaffolder examples/ + benches/ + serial_test dev-dep + osis_benches symmetry (#139)

timur referenced this pull request 2026-05-25 10:48:26 +00:00

Lifecycle alignment, part 2 — examples, dual-home tests, benches-at-root, --bench #129

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels   

prio_critical

  

prio_low

  

type_bug

  

type_contact

  

type_issue

  

type_lead

  

type_question

  

type_story

  

type_task

No labels

prio_critical

prio_low

type_bug

type_contact

type_issue

type_lead

type_question

type_story

type_task

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

lhumina_code/hero_rpc!139

No description provided.