mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-08-28 05:27:41 +00:00
chore: move testing-strategy doc into docs-internal
The strategy doc lived alone under files-internal/ while every sibling strategy doc (logging, events, server-secrets) lived under docs-internal/. Move it next to the others and update plan/spec references. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Bryan Helmkamp
parent
a4c04a296e
commit
bebf472ad2
8 changed files with 15 additions and 15 deletions
|
|
@ -96,7 +96,7 @@ No billing / usage / reporting site reads `is_terminal()` — those roll up from
|
|||
|
||||
No `docs/solutions/` entries exist in this repo; the institutional-knowledge base is empty. Substitute docs to follow:
|
||||
- `docs-internal/events-strategy.md` (the 7-step event checklist)
|
||||
- `files-internal/testing-strategy.md` (layering: `cmd/*` for single-command CLI tests, `scenario/*` for cross-command lifecycle)
|
||||
- `docs-internal/testing-strategy.md` (layering: `cmd/*` for single-command CLI tests, `scenario/*` for cross-command lifecycle)
|
||||
- `AGENTS.md` §"API workflow" (OpenAPI source-of-truth and regen sequence) and §"Rust import style" (types by name, functions via parent module)
|
||||
|
||||
### External References
|
||||
|
|
@ -554,7 +554,7 @@ flowchart TB
|
|||
|
||||
- **Origin document:** [docs/brainstorms/2026-04-19-run-archived-status-requirements.md](../brainstorms/2026-04-19-run-archived-status-requirements.md)
|
||||
- **Events strategy:** [docs-internal/events-strategy.md](../../docs-internal/events-strategy.md)
|
||||
- **Testing strategy:** [files-internal/testing-strategy.md](../../files-internal/testing-strategy.md)
|
||||
- **Testing strategy:** [docs-internal/testing-strategy.md](../../docs-internal/testing-strategy.md)
|
||||
- **API workflow convention:** `AGENTS.md` §"API workflow"
|
||||
- **Bulk-by-ID CLI template:** `lib/crates/fabro-cli/src/commands/runs/rm.rs`
|
||||
- **Actor-carrying event precedent:** `lib/crates/fabro-workflow/src/event.rs:93-96` (`RunCancelRequested`)
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ Those behaviors were survivable when the CLI and server were assumed to live on
|
|||
### Institutional Learnings
|
||||
|
||||
- No `docs/solutions/` directory exists in this repository, so there are no institutional learnings to carry forward from that source.
|
||||
- `files-internal/testing-strategy.md` reinforces the right split for this work:
|
||||
- `docs-internal/testing-strategy.md` reinforces the right split for this work:
|
||||
- connection/auth selection logic should get crate-level tests
|
||||
- single-command contract regressions should stay in `tests/it/cmd`
|
||||
- cross-command auth or exec narratives should stay in `tests/it/scenario`
|
||||
|
|
@ -322,7 +322,7 @@ flowchart TB
|
|||
- Update docs/help copy anywhere it still implies that explicit `--server` may inherit local daemon identity or local dev-token convenience.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `files-internal/testing-strategy.md` placement rules for crate-level vs `cmd/*` vs `scenario/*`
|
||||
- `docs-internal/testing-strategy.md` placement rules for crate-level vs `cmd/*` vs `scenario/*`
|
||||
- existing real auth harness organization in `lib/crates/fabro-cli/tests/it/support/auth_harness.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
|
|
@ -386,4 +386,4 @@ flowchart TB
|
|||
- `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/support/auth_harness.rs`
|
||||
- Repo guidance:
|
||||
- `files-internal/testing-strategy.md`
|
||||
- `docs-internal/testing-strategy.md`
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ These were all reasonable while the client had exactly one caller. They prevent
|
|||
|
||||
- No `docs/solutions/` directory in this repo — no prior captured learnings apply. Historical plans in `docs/plans/` around CLI/server boundary (`2026-04-02-001-feat-server-daemon-management-plan.md`, `2026-04-05-cli-deglobalize-server-url-and-storage-dir-plan.md`, `2026-04-20-001-fix-cli-server-same-host-assumptions-plan.md`) have tightened the target-resolution contract progressively. This plan's `fabro-client` extraction is the next step in that direction: after target resolution became disciplined, pull the pure client *out* of the CLI and make its purity enforceable by the crate graph.
|
||||
- `CLAUDE.md` reminds: "We want the simplest change possible. We don't care about migration. Code readability matters most, and we're happy to make bigger changes to achieve it." We lean on this for the `ServerTarget` canonicalization change and the "delete the alias" step in the `Client` rename we just finished.
|
||||
- `files-internal/testing-strategy.md` — most existing CLI tests exercise the client through CLI-level commands; those tests continue to live in `fabro-cli` and don't need to migrate. Tests of internal helpers (auth-store round-trips, `ServerTargetKey` canonicalization, loopback classification, SSE parsing, dev-token resolution) fall into three buckets: (a) auth-store/SSE/loopback/ServerTarget tests migrate to `fabro-client`; (b) dev-token resolution tests stay in `fabro-cli`; (c) server-client unit tests for refresh-token transport checks migrate.
|
||||
- `docs-internal/testing-strategy.md` — most existing CLI tests exercise the client through CLI-level commands; those tests continue to live in `fabro-cli` and don't need to migrate. Tests of internal helpers (auth-store round-trips, `ServerTargetKey` canonicalization, loopback classification, SSE parsing, dev-token resolution) fall into three buckets: (a) auth-store/SSE/loopback/ServerTarget tests migrate to `fabro-client`; (b) dev-token resolution tests stay in `fabro-cli`; (c) server-client unit tests for refresh-token transport checks migrate.
|
||||
|
||||
### External References
|
||||
|
||||
|
|
|
|||
|
|
@ -51,7 +51,7 @@ That mismatch leaks implementation history into the domain model and makes every
|
|||
- `lib/crates/fabro-workflow/src/lifecycle/git.rs` and `lib/crates/fabro-workflow/src/pipeline/finalize.rs` still use phase-specific `RunDump` constructors and a `checkpoint.json`-oriented metadata helper.
|
||||
- `lib/crates/fabro-workflow/src/operations/{fork.rs,rewind.rs,rebuild_meta.rs}` plus `lib/crates/fabro-cli/src/commands/run/rewind.rs` are the critical metadata readers/writers that must switch from standalone `checkpoint.json` and `start.json` reads to projection reads.
|
||||
- `lib/crates/fabro-types/src/stage_id.rs` already defines `Display` as `{node_id}@{visit}`, which should become the on-disk stage directory name.
|
||||
- `files-internal/testing-strategy.md` says CLI integration tests should remain command-driven and black-box; layout-specific assertions belong in the right layer rather than by planting run internals by hand.
|
||||
- `docs-internal/testing-strategy.md` says CLI integration tests should remain command-driven and black-box; layout-specific assertions belong in the right layer rather than by planting run internals by hand.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
|
|
@ -95,7 +95,7 @@ That mismatch leaks implementation history into the domain model and makes every
|
|||
|
||||
- Exact helper names for the new metadata commit writer (`write_snapshot`, `write_projection_commit`, etc.). The plan fixes the API shape and intent, but the final Rust name can be chosen during implementation.
|
||||
- Whether the shared export builder stays in `lib/crates/fabro-workflow/src/run_dump.rs` or moves to a nearby module. The key constraint is one authoritative layout builder, not a specific file name.
|
||||
- Whether any low-value tests should move layers while being updated. Follow `files-internal/testing-strategy.md` if implementation reveals a better layer, but do not turn this refactor into a broad test reorganization.
|
||||
- Whether any low-value tests should move layers while being updated. Follow `docs-internal/testing-strategy.md` if implementation reveals a better layer, but do not turn this refactor into a broad test reorganization.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
|
|
@ -299,11 +299,11 @@ Durable event store
|
|||
**Approach:**
|
||||
- Update retro agent instructions and sandbox uploads so the agent reads `run.json` projection data plus `graph.fabro` and stage files instead of `checkpoint.json` and `start.json`.
|
||||
- Rename or replace tests that currently assert `conclusion.json` or old `nodes/...` layouts so they assert conclusion presence inside `run.json` and stage files under `stages/`.
|
||||
- Keep CLI integration tests black-box per `files-internal/testing-strategy.md`; layout assertions should come from public command behavior or crate-level tests, not hand-planted run internals.
|
||||
- Keep CLI integration tests black-box per `docs-internal/testing-strategy.md`; layout assertions should come from public command behavior or crate-level tests, not hand-planted run internals.
|
||||
- Review snapshot diffs before accepting them because this refactor intentionally changes many file paths and exported filenames.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Snapshot discipline in `files-internal/testing-strategy.md`
|
||||
- Snapshot discipline in `docs-internal/testing-strategy.md`
|
||||
- Existing retro upload flow in `lib/crates/fabro-retro/src/retro_agent.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
|
|
@ -351,4 +351,4 @@ Durable event store
|
|||
- `lib/crates/fabro-checkpoint/src/metadata.rs`
|
||||
- `lib/crates/fabro-workflow/src/operations/{fork.rs,rewind.rs,rebuild_meta.rs}`
|
||||
- `lib/crates/fabro-cli/src/commands/{store/dump.rs,store/run_export.rs,run/rewind.rs}`
|
||||
- Related guidance: `files-internal/testing-strategy.md`
|
||||
- Related guidance: `docs-internal/testing-strategy.md`
|
||||
|
|
|
|||
|
|
@ -132,7 +132,7 @@ behavior and avoids turning `CommandContext` into a new god object.
|
|||
`lib/crates/fabro-cli/src/commands/provider/mod.rs` — the clearest
|
||||
examples of raw `process_local_json` still being threaded despite the
|
||||
rest of the state already belonging to the invocation.
|
||||
- `files-internal/testing-strategy.md` — CLI integration tests should
|
||||
- `docs-internal/testing-strategy.md` — CLI integration tests should
|
||||
stay command-driven and black-box, with implementation-facing behavior
|
||||
covered by unit tests near the code.
|
||||
- `lib/crates/fabro-cli/src/commands/sandbox/mod.rs` — the real public
|
||||
|
|
@ -828,7 +828,7 @@ command tree is consistently aligned on `CommandContext`.
|
|||
`lib/crates/fabro-cli/src/commands/auth/mod.rs`
|
||||
`lib/crates/fabro-cli/src/commands/provider/mod.rs`
|
||||
`lib/crates/fabro-cli/src/commands/system/mod.rs`
|
||||
- Testing guidance: `files-internal/testing-strategy.md`
|
||||
- Testing guidance: `docs-internal/testing-strategy.md`
|
||||
- Related history:
|
||||
`93b6577cd simplify: drop duplicate settings plumbing from cli/server refactor`
|
||||
`367fd9302 refactor(cli): centralize command settings and server access`
|
||||
|
|
|
|||
|
|
@ -987,7 +987,7 @@ impl fabro_options_metadata::OptionsMetadata for RunArgs {
|
|||
- **fabro strategy docs:**
|
||||
- `docs-internal/logging-strategy.md` (Phase 2 alignment)
|
||||
- `docs-internal/server-secrets-strategy.md` (Phase 1 constraint: no env mutation)
|
||||
- `files-internal/testing-strategy.md` (Phase 3 guidance)
|
||||
- `docs-internal/testing-strategy.md` (Phase 3 guidance)
|
||||
- **AGENTS.md:** `/Users/bhelmkamp/p/fabro-sh/fabro-3/AGENTS.md` (nightly clippy, strum, insta workflow, refresh-spa mandate).
|
||||
- **External docs:**
|
||||
- `miette`: https://docs.rs/miette/
|
||||
|
|
|
|||
|
|
@ -346,7 +346,7 @@ Install-mode failures report to Sentry via `fabro-telemetry` with the existing a
|
|||
|
||||
## Testing strategy
|
||||
|
||||
Per `files-internal/testing-strategy.md` (re-read before implementing).
|
||||
Per `docs-internal/testing-strategy.md` (re-read before implementing).
|
||||
|
||||
### Unit tests (`fabro-install` crate)
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue