mirror of
https://github.com/fabro-sh/fabro.git
synced 2026-11-15 09:11:22 +00:00
Remove AI-generated plans and reviews from Git
Stop tracking 180 AI-generated working files (plans, reviews, and related artifacts) and ignore the .ai/ folder. The files stay on local disk and in Git history. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
parent
9fd2075a9d
commit
1f7c2c25c9
181 changed files with 3 additions and 60317 deletions
|
|
@ -1,35 +0,0 @@
|
|||
Provide a code review for this branch relative to the base branch for bugs and defects.
|
||||
|
||||
To do this, follow these steps precisely:
|
||||
|
||||
1. Use Git to retrieve a list of modified files in this branch.
|
||||
2. Use a Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root CLAUDE.md file (if one exists), as well as any CLAUDE.md files in the directories whose files the pull request modified
|
||||
3. Use a Haiku agent to view the branch's diff, and ask the agent to return a summary of the change
|
||||
4. Then, launch 5 parallel Opus agents to independently code review the change for production bugs and vulnerabilities.
|
||||
a. Agent #1: Read the git blame and history of the code modified, to identify any bugs in light of that historical context
|
||||
b. Agent #2: Read code comments in the modified files, and make sure the changes in the pull request comply with any guidance in the comments.
|
||||
c. Agent #3-5: Read the file changes in this branch, then do a scan for potential bugs. Focus on bugs with production / end-user impact, and avoid small issues and nitpicks.
|
||||
|
||||
Output a report with all the bugs using this format:
|
||||
|
||||
<code_review>
|
||||
<bug>
|
||||
<title>title of bug</title>
|
||||
<description>brief description of bug</description>
|
||||
<location>
|
||||
<file>lib/apps/fabro-cli/src/commands/resume.rs</file>
|
||||
<start_line>115</start_line>
|
||||
<end_line>115</end_line>
|
||||
</location>
|
||||
<severity>critical/high/medium/low</severity>
|
||||
</bug>
|
||||
<bug>...</bug>
|
||||
</code_review>
|
||||
|
||||
Write the report to: `.ai/tmp/candidate_bugs.xml`
|
||||
|
||||
Notes:
|
||||
|
||||
- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
|
||||
- Include all potential bugs of all severity (critical/high/medium/low) that have production / end-user impact. (We will analyze them separately later.)
|
||||
- Make a todo list first
|
||||
|
|
@ -1,110 +0,0 @@
|
|||
Provide a code review for this branch relative to the base branch for bugs and defects.
|
||||
|
||||
We have a report of candidate bugs which you need to analyze.
|
||||
|
||||
To do this, follow these steps precisely:
|
||||
|
||||
1. Use Git to retrieve a list of modified files in this branch.
|
||||
2. View the branch's diff and understand the changes
|
||||
3. Then, launch 5 parallel Opus agents to independently assess the candidate bugs. For each bug, investigate it thoroughly in order to produce the report in the format below. If the candidate bug is not valid, then discard it.
|
||||
|
||||
Input: Read from `.ai/tmp/candidate_bugs.xml`
|
||||
|
||||
Output a report with all the bugs using this format:
|
||||
|
||||
```xml
|
||||
<code_review>
|
||||
<bug>
|
||||
<summary>up to 3 sentences</summary>
|
||||
<severity>important OR nit</severity>
|
||||
<pre_existing>yes OR no</pre_existing>
|
||||
<location>
|
||||
<file>lib/apps/fabro-cli/src/commands/resume.rs</file>
|
||||
<start_line>115</start_line>
|
||||
<end_line>115</end_line>
|
||||
</location>
|
||||
<extended_reasoning>
|
||||
<what_the_bug_is>...</what_the_bug_is>
|
||||
<the_specific_code_path_that_triggers_it>...</the_specific_code_path_that_triggers_it>
|
||||
<why_existing_code_does_not_prevent_it>...</why_existing_code_does_not_prevent_it>
|
||||
<impact>...</impact>
|
||||
<how_to_fix_it>...</how_to_fix_it>
|
||||
<step_by_step_proof>
|
||||
<step>first step</step>
|
||||
<step>second step</step>
|
||||
<step>...</step>
|
||||
<step>bug</step>
|
||||
</step_by_step_proof>
|
||||
</extended_reasoning>
|
||||
</bug>
|
||||
<bug>...</bug>
|
||||
</code_review>
|
||||
```
|
||||
|
||||
Here is a real-world example:
|
||||
|
||||
```xml
|
||||
<bug>
|
||||
<summary>
|
||||
`prepare_from_checkpoint` unconditionally creates a `LocalSandbox` via `local_sandbox_with_callback`, completely ignoring the `--sandbox` flag and TOML config. A user running `fabro resume --checkpoint logs/checkpoint.json --workflow w.fabro --sandbox docker` will silently get a local sandbox instead of Docker; to fix this, call `resolve_sandbox_provider(args.sandbox.map(Into::into), None, run_defaults)` just as `prepare_from_branch` does.
|
||||
</summary>
|
||||
<severity>important</severity>
|
||||
<pre_existing>no</pre_existing>
|
||||
<location>
|
||||
<file>lib/apps/fabro-cli/src/commands/resume.rs</file>
|
||||
<start_line>208</start_line>
|
||||
<end_line>208</end_line>
|
||||
</location>
|
||||
<extended_reasoning>
|
||||
<what_the_bug_is>
|
||||
`prepare_from_checkpoint` (resume.rs, around line 196) always wires up a `LocalSandbox` regardless of what sandbox the caller requested:
|
||||
|
||||
```rust
|
||||
let sandbox: Arc<dyn Sandbox> = local_sandbox_with_callback(original_cwd, Arc::clone(&emitter));
|
||||
let sandbox: Arc<dyn Sandbox> = Arc::new(fabro_agent::ReadBeforeWriteSandbox::new(sandbox));
|
||||
```
|
||||
|
||||
The `args.sandbox` field (a `Option<CliSandboxProvider>`) is populated by clap but never read inside this function. No error is raised and no warning is printed.
|
||||
</what_the_bug_is>
|
||||
<the_specific_code_path_that_triggers_it>
|
||||
When a user invokes `fabro resume --checkpoint path/to/checkpoint.json --workflow w.fabro --sandbox docker`, `resume_command` sees `args.checkpoint.is_some()` and dispatches to `prepare_from_checkpoint`. That function builds the `ResumeContext` with a `LocalSandbox` and returns. The `--sandbox docker` value stored in `args.sandbox` is forwarded to `run_resumed` but by then the sandbox is already constructed and the field is never consulted.
|
||||
</the_specific_code_path_that_triggers_it>
|
||||
<why_existing_code_does_not_prevent_it>
|
||||
`prepare_from_branch` — the sibling function for the run-ID path — correctly calls `resolve_sandbox_provider(args.sandbox.map(Into::into), None, run_defaults)` and dispatches through a `match sandbox_provider { ... }` that handles `Local`, `Docker`, `Ssh`, `Exe`, and `Daytona`. The checkpoint-file path was clearly authored separately and the sandbox resolution step was simply omitted. Additionally, the old `fabro run --resume checkpoint.json --sandbox docker` path ran through `run_command`, which performed sandbox resolution before the checkpoint branch — so this is a genuine regression of a previously-working feature.
|
||||
</why_existing_code_does_not_prevent_it>
|
||||
<impact>
|
||||
Any user relying on `--sandbox docker` (for reproducibility, filesystem isolation, or container-specific tooling), `--sandbox ssh` (remote host execution), or `--sandbox exe` when resuming from a checkpoint file will silently run against the local filesystem instead. There is no error, no warning, and the job may produce different results or corrupt local state. The flag is prominently documented in both `docs/reference/cli.mdx` and the `--help` output, so users have every reason to expect it to work.
|
||||
</impact>
|
||||
<how_to_fix_it>
|
||||
Replace the hardcoded `local_sandbox_with_callback` call in `prepare_from_checkpoint` with the same sandbox-resolution logic used by `prepare_from_branch`:
|
||||
|
||||
```rust
|
||||
let sandbox_provider = if args.dry_run {
|
||||
SandboxProvider::Local
|
||||
} else {
|
||||
resolve_sandbox_provider(args.sandbox.map(Into::into), None, run_defaults)?
|
||||
};
|
||||
// then match sandbox_provider { ... } as prepare_from_branch does
|
||||
```
|
||||
|
||||
Note that `run_defaults` must also be threaded into `prepare_from_checkpoint` (currently it is not passed to this function), matching the signature of `prepare_from_branch`.
|
||||
</how_to_fix_it>
|
||||
<step_by_step_proof>
|
||||
<step>User runs: `fabro resume --checkpoint ~/.fabro/runs/20260321-01ABC.../checkpoint.json --workflow deploy.fabro --sandbox docker`</step>
|
||||
<step>`resume_command` evaluates `args.checkpoint.is_some()` → `true` → calls `prepare_from_checkpoint(&args, ...)`.</step>
|
||||
<step>Inside `prepare_from_checkpoint`, `args.sandbox` holds `Some(CliSandboxProvider::Docker)` but is never read.</step>
|
||||
<step>Line ~196: `let sandbox = local_sandbox_with_callback(original_cwd, Arc::clone(&emitter));` — a `LocalSandbox` is constructed unconditionally.</step>
|
||||
<step>`ResumeContext { sandbox, ... }` is returned with the local sandbox.</step>
|
||||
<step>`run_resumed` receives this context and runs the entire workflow inside the local sandbox.</step>
|
||||
<step>Docker is never launched; no diagnostic message is emitted.</step>
|
||||
</step_by_step_proof>
|
||||
</extended_reasoning>
|
||||
</bug>
|
||||
```
|
||||
|
||||
Write the output to `.ai/tmp/analyzed_bugs.xml`
|
||||
|
||||
Notes:
|
||||
|
||||
- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
|
||||
- Make a todo list first
|
||||
|
|
@ -1,33 +0,0 @@
|
|||
Filter the bugs identified by code review to the bugs worth fixing.
|
||||
|
||||
We have a report of analyzed bugs which you need to filter.
|
||||
|
||||
To do this, follow these steps precisely:
|
||||
|
||||
1. Use Git to retrieve a list of modified files in this branch.
|
||||
2. Use a Haiku agent to view the branch's diff, and ask the agent to return a summary of the change
|
||||
3. For each bug assess if it is a false positive based on the criteria below.
|
||||
|
||||
Input: Read from `.ai/tmp/analyzed_bugs.xml`
|
||||
|
||||
Filter out the false positives. Examples of false positives:
|
||||
|
||||
- Nits
|
||||
- Something that looks like a bug but is not actually a bug
|
||||
- Pedantic issues that a senior engineer wouldn't call out
|
||||
- Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
|
||||
- General code quality issues (eg. lack of test coverage, general security issues, poor documentation)
|
||||
- Maintainability, code smells, etc.
|
||||
- Changes in functionality that are likely intentional or are directly related to the broader change
|
||||
- Real issues, but are not related to the changes in the branch
|
||||
|
||||
Ouput:
|
||||
|
||||
1. Write to `.ai/tmp/valid_bugs.xml` in the same XML format with the false positives filtered out.
|
||||
2. Write to `.ai/tmp/false_positives.md` a summary of the false positives you filtered out and why.
|
||||
|
||||
Notes:
|
||||
|
||||
- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
|
||||
- Make a todo list first
|
||||
- It is OK to keep bugs which are pre-existing, if and only if they are both A) important and B) relevant to the changes being made.
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
---
|
||||
allowed-tools: Bash(gh issue view:*), Bash(gh search:*), Bash(gh issue list:*), Bash(gh pr comment:*), Bash(gh pr diff:*), Bash(gh pr view:*), Bash(gh pr list:*)
|
||||
description: Code review a pull request
|
||||
disable-model-invocation: false
|
||||
---
|
||||
|
||||
Provide a code review for the given pull request.
|
||||
|
||||
To do this, follow these steps precisely:
|
||||
|
||||
1. Use a Haiku agent to check if the pull request (a) is closed, (b) is a draft, (c) does not need a code review (eg. because it is an automated pull request, or is very simple and obviously ok), or (d) already has a code review from you from earlier. If so, do not proceed.
|
||||
2. Use another Haiku agent to give you a list of file paths to (but not the contents of) any relevant CLAUDE.md files from the codebase: the root CLAUDE.md file (if one exists), as well as any CLAUDE.md files in the directories whose files the pull request modified
|
||||
3. Use a Haiku agent to view the pull request, and ask the agent to return a summary of the change
|
||||
4. Then, launch 5 parallel Sonnet agents to independently code review the change. The agents should do the following, then return a list of issues and the reason each issue was flagged (eg. CLAUDE.md adherence, bug, historical git context, etc.):
|
||||
a. Agent #1: Audit the changes to make sure they compily with the CLAUDE.md. Note that CLAUDE.md is guidance for Claude as it writes code, so not all instructions will be applicable during code review.
|
||||
b. Agent #2: Read the file changes in the pull request, then do a shallow scan for obvious bugs. Avoid reading extra context beyond the changes, focusing just on the changes themselves. Focus on large bugs, and avoid small issues and nitpicks. Ignore likely false positives.
|
||||
c. Agent #3: Read the git blame and history of the code modified, to identify any bugs in light of that historical context
|
||||
d. Agent #4: Read previous pull requests that touched these files, and check for any comments on those pull requests that may also apply to the current pull request.
|
||||
e. Agent #5: Read code comments in the modified files, and make sure the changes in the pull request comply with any guidance in the comments.
|
||||
5. For each issue found in #4, launch a parallel Haiku agent that takes the PR, issue description, and list of CLAUDE.md files (from step 2), and returns a score to indicate the agent's level of confidence for whether the issue is real or false positive. To do that, the agent should score each issue on a scale from 0-100, indicating its level of confidence. For issues that were flagged due to CLAUDE.md instructions, the agent should double check that the CLAUDE.md actually calls out that issue specifically. The scale is (give this rubric to the agent verbatim):
|
||||
a. 0: Not confident at all. This is a false positive that doesn't stand up to light scrutiny, or is a pre-existing issue.
|
||||
b. 25: Somewhat confident. This might be a real issue, but may also be a false positive. The agent wasn't able to verify that it's a real issue. If the issue is stylistic, it is one that was not explicitly called out in the relevant CLAUDE.md.
|
||||
c. 50: Moderately confident. The agent was able to verify this is a real issue, but it might be a nitpick or not happen very often in practice. Relative to the rest of the PR, it's not very important.
|
||||
d. 75: Highly confident. The agent double checked the issue, and verified that it is very likely it is a real issue that will be hit in practice. The existing approach in the PR is insufficient. The issue is very important and will directly impact the code's functionality, or it is an issue that is directly mentioned in the relevant CLAUDE.md.
|
||||
e. 100: Absolutely certain. The agent double checked the issue, and confirmed that it is definitely a real issue, that will happen frequently in practice. The evidence directly confirms this.
|
||||
6. Filter out any issues with a score less than 80. If there are no issues that meet this criteria, do not proceed.
|
||||
7. Use a Haiku agent to repeat the eligibility check from #1, to make sure that the pull request is still eligible for code review.
|
||||
8. Finally, use the gh bash command to comment back on the pull request with the result. When writing your comment, keep in mind to:
|
||||
a. Keep your output brief
|
||||
b. Avoid emojis
|
||||
c. Link and cite relevant code, files, and URLs
|
||||
|
||||
Examples of false positives, for steps 4 and 5:
|
||||
|
||||
- Pre-existing issues
|
||||
- Something that looks like a bug but is not actually a bug
|
||||
- Pedantic nitpicks that a senior engineer wouldn't call out
|
||||
- Issues that a linter, typechecker, or compiler would catch (eg. missing or incorrect imports, type errors, broken tests, formatting issues, pedantic style issues like newlines). No need to run these build steps yourself -- it is safe to assume that they will be run separately as part of CI.
|
||||
- General code quality issues (eg. lack of test coverage, general security issues, poor documentation), unless explicitly required in CLAUDE.md
|
||||
- Issues that are called out in CLAUDE.md, but explicitly silenced in the code (eg. due to a lint ignore comment)
|
||||
- Changes in functionality that are likely intentional or are directly related to the broader change
|
||||
- Real issues, but on lines that the user did not modify in their pull request
|
||||
|
||||
Notes:
|
||||
|
||||
- Do not check build signal or attempt to build or typecheck the app. These will run separately, and are not relevant to your code review.
|
||||
- Use `gh` to interact with Github (eg. to fetch a pull request, or to create inline comments), rather than web fetch
|
||||
- Make a todo list first
|
||||
- You must cite and link each bug (eg. if referring to a CLAUDE.md, you must link it)
|
||||
- For your final comment, follow the following format precisely (assuming for this example that you found 3 issues):
|
||||
|
||||
---
|
||||
|
||||
### Code review
|
||||
|
||||
Found 3 issues:
|
||||
|
||||
1. <brief description of bug> (CLAUDE.md says "<...>")
|
||||
|
||||
<link to file and line with full sha1 + line range for context, note that you MUST provide the full sha and not use bash here, eg. https://github.com/anthropics/claude-code/blob/1d54823877c4de72b2316a64032a54afc404e619/README.md#L13-L17>
|
||||
|
||||
2. <brief description of bug> (some/other/CLAUDE.md says "<...>")
|
||||
|
||||
<link to file and line with full sha1 + line range for context>
|
||||
|
||||
3. <brief description of bug> (bug due to <file and code snippet>)
|
||||
|
||||
<link to file and line with full sha1 + line range for context>
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.ai/code)
|
||||
|
||||
<sub>- If this code review was useful, please react with 👍. Otherwise, react with 👎.</sub>
|
||||
|
||||
---
|
||||
|
||||
- Or, if you found no issues:
|
||||
|
||||
---
|
||||
|
||||
### Code review
|
||||
|
||||
No issues found. Checked for bugs and CLAUDE.md compliance.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.ai/code)
|
||||
|
||||
- When linking to code, follow the following format precisely, otherwise the Markdown preview won't render correctly: https://github.com/anthropics/claude-cli-internal/blob/c21d3c10bc8e898b7ac1a2d745bdc9bc4e423afe/package.json#L10-L15
|
||||
- Requires full git sha
|
||||
- You must provide the full sha. Commands like `https://github.com/owner/repo/blob/$(git rev-parse HEAD)/foo/bar` will not work, since your comment will be directly rendered in Markdown.
|
||||
- Repo name must match the repo you're code reviewing
|
||||
- # sign after the file name
|
||||
- Line range format is L[start]-L[end]
|
||||
- Provide at least 1 line of context before and after, centered on the line you are commenting about (eg. if you are commenting about lines 5-6, you should link to `L4-7`)
|
||||
|
|
@ -1,249 +0,0 @@
|
|||
# Calibration Adjudication
|
||||
|
||||
Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
Cartography: v1 at `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`.
|
||||
The only later commit adds cartography artifacts, so the mapped code paths are
|
||||
unchanged at the assessed revision.
|
||||
|
||||
Sample: `fabro-workflow`, `fabro-http`, `fabro-web-app`, `repository-ci`.
|
||||
Control: `fabro-checkpoint`.
|
||||
|
||||
## Independent Score Matrix
|
||||
|
||||
Cells list reviewer 1 / reviewer 2 / reviewer 3.
|
||||
|
||||
| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge |
|
||||
|---|---:|---:|---:|---:|
|
||||
| `fabro-workflow` | 2 / 3 / 4 | 2 / 2 / 2 | 2 / 3 / 2 | 2 / 2 / 2 |
|
||||
| `fabro-http` | 4 / 4 / 4 | 4 / 4 / 4 | 4 / 3 / 4 | 3 / 4 / 4 |
|
||||
| `fabro-web-app` | 4 / 4 / 3 | 2 / 2 / 2 | 2 / 2 / 2 | 2 / 2 / 2 |
|
||||
| `repository-ci` | 4 / 4 / 3 | 3 / 3 / 3 | 2 / 3 / 2 | 2 / 2 / 2 |
|
||||
|
||||
Unanimous pairs establish that central machinery may still have a stable path:
|
||||
`fabro-workflow` is 2 for simplicity and duplication; `fabro-web-app` is 2 for
|
||||
simplicity, domain model, and duplication; and `repository-ci` is 3 for
|
||||
simplicity and 2 for duplication. `fabro-http` is unanimously 4 for ownership
|
||||
and simplicity.
|
||||
|
||||
## Material Disagreements
|
||||
|
||||
### `fabro-workflow` × ownership and boundaries — 2 / 3 / 4
|
||||
|
||||
- **Evidence:** `pipeline/mod.rs` and `pipeline/types.rs` give the normal run
|
||||
explicit phase owners; `lifecycle/mod.rs:WorkflowLifecycle` owns callback
|
||||
ordering through focused delegates.
|
||||
- **Counterevidence:** terminal completion and failure are also constructed in
|
||||
`pipeline/finalize.rs:build_terminal_event`,
|
||||
`operations/start.rs:emit_workflow_run_failed`,
|
||||
`operations/start.rs:persist_terminal_engine_failure`, completion/drop
|
||||
guards, retry, and archive operations.
|
||||
- **Ambiguous rule:** two reviewers judged the clear normal path; one judged
|
||||
whether the same lifecycle has one home across normal and exceptional paths.
|
||||
- **Discriminator:** inspect every recurring terminal path. A routine
|
||||
terminal-contract change crossing several operation owners is score-2
|
||||
ownership pressure even when the success path is well partitioned.
|
||||
- **Draft adjudication:** 2.
|
||||
|
||||
### `fabro-workflow` × domain model — 2 / 3 / 2
|
||||
|
||||
- **Evidence:** `pipeline/types.rs` encodes phase states and canonical product
|
||||
records are reused.
|
||||
- **Counterevidence:** `event/events.rs:Event::StageCompleted` carries a string
|
||||
status; `lifecycle/event.rs:EventLifecycle::after_node` serializes a typed
|
||||
outcome and `event/convert.rs:stage_status_from_string` reparses it with an
|
||||
unknown-value fallback.
|
||||
- **Ambiguous rule:** whether a typed durable event isolates an invalid
|
||||
intermediate representation on the common producer path.
|
||||
- **Discriminator:** common-path invalid intermediate states are central even
|
||||
when the durable result is typed.
|
||||
- **Draft adjudication:** 2.
|
||||
|
||||
### `fabro-http` × domain model — 4 / 3 / 4
|
||||
|
||||
- **Evidence:** `ProxyPolicy`, `resolve_with_env_value`, and
|
||||
`HttpClientBuildError` form a closed policy with explicit precedence and
|
||||
rejection.
|
||||
- **Counterevidence:** public builders expose both
|
||||
`proxy_policy(ProxyPolicy::Disabled)` and lower-level `no_proxy()`.
|
||||
- **Ambiguous rule:** whether a lower-level transport control creates a second
|
||||
meaning for the repository policy.
|
||||
- **Discriminator:** an escape hatch does not split the canonical concept when
|
||||
the typed policy remains closed and its precedence is enforced.
|
||||
- **Draft adjudication:** 4.
|
||||
|
||||
### `fabro-http` × duplication of knowledge — 3 / 4 / 4
|
||||
|
||||
- **Evidence:** `define_builder!` is the shared async/blocking authority and
|
||||
`ProxyPolicy::resolve` owns precedence.
|
||||
- **Counterevidence:** adding a policy variant synchronizes the enum, parser,
|
||||
expected-value error text, behavior match, and tests.
|
||||
- **Ambiguous rule:** whether co-location and exhaustive matching make all
|
||||
policy vocabulary authoritative.
|
||||
- **Discriminator:** hypothetical variants do not establish routine
|
||||
recurrence; exhaustive compiler-checked behavior remains one authority
|
||||
unless direct evidence shows recurring manual synchronization.
|
||||
- **Draft adjudication:** 4.
|
||||
|
||||
### `fabro-web-app` × ownership and boundaries — 4 / 4 / 3
|
||||
|
||||
- **Evidence:** `entry.tsx`, route graphs, `lib/api-client.ts`, queries,
|
||||
mutations, effect hooks, and the build script give shared responsibilities
|
||||
visible homes.
|
||||
- **Counterevidence:** `install-app.tsx` and `routes/run-stages.tsx` contain
|
||||
several central transformations and presentation concerns.
|
||||
- **Ambiguous rule:** whether a busy but clearly identified route owner is
|
||||
boundary pressure or simplicity pressure.
|
||||
- **Discriminator:** do not lower ownership for internal complexity unless
|
||||
routine changes cross another owner or reverse the mapped dependency
|
||||
direction.
|
||||
- **Draft adjudication:** 4.
|
||||
|
||||
### `repository-ci` × ownership and boundaries — 4 / 4 / 3
|
||||
|
||||
- **Evidence:** Rust and TypeScript workflows have distinct validation jobs,
|
||||
narrow permissions, and delegate build procedures to repository commands.
|
||||
- **Counterevidence:** the Rust clippy job embeds the repository's legacy-auth
|
||||
vocabulary check.
|
||||
- **Ambiguous rule:** whether enforcement of a product migration invariant is
|
||||
misplaced when CI owns validation but not the underlying vocabulary.
|
||||
- **Discriminator:** a named invariant check may live in CI, but its product
|
||||
vocabulary must remain authoritative elsewhere; this isolated boundary
|
||||
friction fits 3.
|
||||
- **Draft adjudication:** 3.
|
||||
|
||||
### `repository-ci` × domain model — 2 / 3 / 2
|
||||
|
||||
- **Evidence:** job, runner, permission, and test-mode vocabulary is otherwise
|
||||
coherent.
|
||||
- **Counterevidence:** `rust.yml:on.*.paths` names nonexistent `openapi/**`
|
||||
rather than `docs/public/api-reference/fabro-api.yaml`, and
|
||||
`zizmor.yml:rules.stale-action-refs.ignore` identifies exceptions by stale
|
||||
line positions.
|
||||
- **Ambiguous rule:** whether configuration references are domain vocabulary
|
||||
or only duplicated operational data.
|
||||
- **Discriminator:** identifiers that control central behavior are domain
|
||||
vocabulary; missing or stale referents create score-2 pressure.
|
||||
- **Draft adjudication:** 2.
|
||||
|
||||
## Draft Anchor Decisions
|
||||
|
||||
- Anchor score 4 on a positive enforcing mechanism, never absence of a defect.
|
||||
- Separate owner clarity from the amount of machinery inside that owner.
|
||||
- Treat invalid common-path intermediate states as domain-model pressure.
|
||||
- Treat repeated semantic decisions as duplication only when routine changes
|
||||
require manual synchronization.
|
||||
- Treat mapped configuration identifiers as domain vocabulary.
|
||||
- Reserve N/E for a lens without direct evidence; no sampled pair required it.
|
||||
|
||||
## Consistency Review
|
||||
|
||||
The fresh reviewer applied only the written draft to `fabro-checkpoint` and
|
||||
reported:
|
||||
|
||||
| Lens | Score | Evidence confidence |
|
||||
|---|---:|---|
|
||||
| Ownership and boundaries | 2 | Medium |
|
||||
| Simplicity | 3 | High |
|
||||
| Domain model | 2 | High |
|
||||
| Duplication of knowledge | 2 | High |
|
||||
|
||||
The control exposed four material wording problems:
|
||||
|
||||
1. The draft did not say how a component-level score combines several
|
||||
responsibilities, or whether positive mechanisms and friction can coexist
|
||||
at score 4.
|
||||
2. Necessary layered delegation could satisfy the original ownership and
|
||||
simplicity score-2 wording.
|
||||
3. The domain rules did not say when a public low-level API is an escape hatch
|
||||
or what score a common invalid intermediate implies.
|
||||
4. Decision rule 5 contradicted the duplication anchor by assigning routine
|
||||
string synchronization to score 3.
|
||||
|
||||
The revision now says that a central concern caps rather than averages, score 4
|
||||
requires a positive production mechanism without material friction, public
|
||||
surface alone does not establish routine work, and missing paths are not
|
||||
negative without mapped-purpose evidence. The anchors now distinguish competing
|
||||
owners from necessary delegation and maintainer navigation from runtime
|
||||
layering. Decision rules 2–6 resolve scoped lifecycle handoff, necessary
|
||||
delegation, common-path invalid states, direct evidence of recurring
|
||||
synchronization, and configuration identifiers. Tests corroborate production
|
||||
authorities but are not second authorities merely because they restate a
|
||||
contract.
|
||||
|
||||
All 16 wording observations in `consistency-review.md` are covered by those
|
||||
changes or by the existing primary-lens and confidence sections. No consistency
|
||||
objection remains open before validation.
|
||||
|
||||
## Validation
|
||||
|
||||
### Round 1
|
||||
|
||||
| Assignment | Validator 1 | Validator 2 | Validator 3 | Result |
|
||||
|---|---:|---:|---:|---|
|
||||
| `fabro-workflow` × ownership | 2 | 2 | 2 | Resolved |
|
||||
| `fabro-workflow` × domain | 2 | 2 | 2 | Resolved |
|
||||
| `fabro-http` × domain | 4 | 4 | 4 | Resolved |
|
||||
| `fabro-http` × duplication | 4 | 4 | 3 | Repeated adjacent split |
|
||||
| `fabro-web-app` × ownership | 4 | 4 | 4 | Resolved |
|
||||
| `repository-ci` × ownership | 4 | 2 | 4 | Non-adjacent split |
|
||||
| `repository-ci` × domain | 2 | 2 | 2 | Resolved |
|
||||
| Control × ownership | 2 | 4 | 2 | Non-adjacent split |
|
||||
| Control × simplicity | 4 | 4 | 3 | Adjacent split |
|
||||
| Control × domain | 2 | 3 | 2 | Adjacent split |
|
||||
| Control × duplication | 3 | 2 | 3 | Adjacent split |
|
||||
|
||||
The sample's workflow lifecycle, event status, HTTP policy model, web
|
||||
composition, and CI identifier anchors now converge. Six assignments require
|
||||
the permitted final simplification:
|
||||
|
||||
- HTTP diagnostic allowed-value text is a concrete second semantic
|
||||
representation, even though the macro is the behavioral authority.
|
||||
- A CI check owns trigger coverage for every path its embedded policy scans;
|
||||
this is distinct from the domain meaning of a nonexistent selector.
|
||||
- Control ownership is judged against the mapped metadata-branch purpose, not
|
||||
against narrower names on `Store` and `BranchStore`.
|
||||
- The control's unused dependency and unused parallel entry layer are isolated
|
||||
simplicity friction rather than evidence-free public breadth.
|
||||
- Validation in an external caller does not make an invalid-capable mapped
|
||||
entry type enforce its own legal shape.
|
||||
- Repeated fixed Git protocol syntax is a concrete second representation, but
|
||||
multiple current call sites alone do not make changing that protocol an
|
||||
ordinary mapped change.
|
||||
|
||||
Decision rules 2–6 now state those discriminators directly. Round 2 will
|
||||
re-score only the six unresolved assignments.
|
||||
|
||||
### Round 2
|
||||
|
||||
| Assignment | Validator 1 | Validator 2 | Validator 3 | Result |
|
||||
|---|---:|---:|---:|---|
|
||||
| `fabro-http` × duplication | 3 | 3 | 3 | Resolved |
|
||||
| `repository-ci` × ownership | 2 | 2 | 2 | Resolved |
|
||||
| Control × ownership | 2 | 2 | 2 | Resolved |
|
||||
| Control × simplicity | 3 | 3 | 3 | Resolved |
|
||||
| Control × domain | 2 | 2 | 2 | Resolved |
|
||||
| Control × duplication | 3 | 3 | 3 | Resolved |
|
||||
|
||||
All round-2 scores converge. The final control baseline is ownership 2
|
||||
(High), simplicity 3 (High), domain model 2 (Medium), and duplication of
|
||||
knowledge 3 (Medium). Domain confidence remains Medium because one validator
|
||||
found a material ambiguity over whether low-level Git path validation belongs
|
||||
inside the component. Duplication confidence remains Medium because stable
|
||||
protocol syntax is concrete repetition but has limited demonstrated change
|
||||
burden.
|
||||
|
||||
Across both validation rounds, the final disputed sample scores are:
|
||||
|
||||
| Component | Ownership and boundaries | Domain model | Duplication of knowledge |
|
||||
|---|---:|---:|---:|
|
||||
| `fabro-workflow` | 2 | 2 | — |
|
||||
| `fabro-http` | — | 4 | 3 |
|
||||
| `fabro-web-app` | 4 | — | — |
|
||||
| `repository-ci` | 2 | 2 | — |
|
||||
|
||||
No non-adjacent or repeated adjacent split remains.
|
||||
|
||||
## Open Questions
|
||||
|
||||
None.
|
||||
|
|
@ -1,112 +0,0 @@
|
|||
# Chisel Consistency Review: `fabro-checkpoint`
|
||||
|
||||
Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
Scope: `lib/components/fabro-checkpoint/**` only. The scored evidence is the manifest, production source, and unit tests at the pinned revision. I did not inspect callers, sample reviews, adjudication, or any other file under `.chisel/calibration/work/`.
|
||||
|
||||
## Scores
|
||||
|
||||
| Lens | Score | Confidence |
|
||||
|---|---:|---|
|
||||
| `ownership-boundaries` | 2 | Medium |
|
||||
| `simplicity` | 3 | High |
|
||||
| `domain-model` | 2 | High |
|
||||
| `duplication-knowledge` | 2 | High |
|
||||
|
||||
Confidence here describes this reading's evidence quality. The rubric's additional requirement that a final High confidence needs independent convergence can only be decided during adjudication.
|
||||
|
||||
## `ownership-boundaries`: 2
|
||||
|
||||
The central branch lifecycle crosses two public owners. `BranchStore` stores the branch name and owns bootstrap plus normal branch reads and writes (`branch.rs:20-209`), but branch cleanup is exposed only as `Store::delete_ref(branch)` (`git.rs:215-226`). `BranchStore` keeps both its `Store` reference and branch name private and has no cleanup/archive operation. A caller therefore has to retain the same raw branch identity and leave the branch-scoped interface for cleanup. Bootstrap sequencing is also caller-owned: `BranchStore::new` does not establish the branch, writes fail when it is absent, and every writable test explicitly calls `ensure_branch` first (`branch.rs:26-81, 282-343`). This is recurring lifecycle work rather than an isolated edge, especially under decision rule 1. Primary tags: `lifecycle`, `ownership`.
|
||||
|
||||
Strongest counterevidence: once initialized, `BranchStore::write_with` keeps the read-modify-write sequence together and delegates only Git object/ref primitives to `Store` (`branch.rs:56-82`). The dependency direction is stable: branch storage depends on the lower-level Git store, not vice versa.
|
||||
|
||||
Why adjacent scores do not fit:
|
||||
|
||||
- **1 does not fit:** `BranchStore` is a stable, identifiable owner for the common branch-scoped read/write responsibility, and `Store` is a coherent lower-level Git owner.
|
||||
- **3 does not fit:** the split includes explicit bootstrap and cleanup paths. Decision rule 1 says recurring terminal ownership cannot be treated as isolated merely because the success path is clear.
|
||||
|
||||
Confidence is Medium because the split is direct, but the scoped evidence cannot show whether archive, retry, and cleanup are deliberately owned by a higher-level caller.
|
||||
|
||||
## `simplicity`: 3
|
||||
|
||||
The common write path is directly traceable: `write_entry`/`write_entries` prepare blobs, `write_with` reads the tip tree, applies one mutation, writes one commit, and advances one ref (`branch.rs:56-109`). `Store::read_tree` and `Store::write_tree` use a single flat `TreeEntries` representation with private recursive helpers (`git.rs:39-99, 141-159, 229-310`). These are positive reinforcing mechanisms, not just an absence of complexity.
|
||||
|
||||
The remaining simplicity pressure is isolated configuration burden. The manifest declares `fabro-store`, `serde`, and the dev dependency `chrono` (`Cargo.toml:16-28`), but none is referenced anywhere in the component source or tests at this revision. The public `Store::repo` escape hatch (`git.rs:112-114`) and the lower-level object API also add surface area, but normal branch writes do not have to choose among competing implementations. Primary tag: `configuration-sprawl`.
|
||||
|
||||
Strongest counterevidence to lowering the score: the component has one linear common mutation path, and its indirection corresponds directly to Git's blob/tree/commit/ref structure.
|
||||
|
||||
Why adjacent scores do not fit:
|
||||
|
||||
- **2 does not fit:** ordinary reads and writes do not repeatedly traverse competing orchestration paths or configuration machinery; the `BranchStore` to `Store` layering is stable and direct.
|
||||
- **4 does not fit:** the centralized mutation path is a qualifying positive mechanism, but the unused manifest dependencies are concrete unnecessary configuration rather than necessary machinery.
|
||||
|
||||
Confidence is High because all component files are in scope, so the dependency non-use and the full common write path are directly observable.
|
||||
|
||||
## `domain-model`: 2
|
||||
|
||||
The common tree-entry producer accepts invalid intermediate path states. `TreeEntries` hides its map, but its public `set` accepts any `Into<String>` without validating a relative Git path (`git.rs:46-61`). Both `BranchStore::write_entry` and `write_entries` feed caller-provided `&str` paths directly into it (`branch.rs:84-109`), and `build_dir_node` later assigns meaning by splitting the strings on `/` (`git.rs:270-294`). Empty components, leading/trailing separators, and file/directory prefix collisions are therefore representable in the canonical intermediate type and reach late Git-tree construction rather than being rejected at the common boundary. Branch identity is likewise an arbitrary `String` until `git2` receives the synthesized ref name (`branch.rs:20-38`, `git.rs:182-197`). This is central invalid-state pressure under decision rule 3, not an isolated low-level escape hatch. Primary tag: `invalid-states`.
|
||||
|
||||
The small helper `sharded_path` is corroborating boundary evidence: its contract says the input is a hex ID, but its public signature accepts any `&str` and slices at a caller-provided byte offset (`branch.rs:211-220`), so a non-ASCII input can panic rather than be rejected as invalid input.
|
||||
|
||||
Strongest counterevidence: `FileMode` is a closed enum and `TreeEntries` keeps ordering and representation private (`git.rs:13-99`). `Error` also distinguishes a missing branch from generic Git failures (`error.rs:5-18`). The component therefore has stable concepts even though common constructors do not preserve all their invariants.
|
||||
|
||||
Why adjacent scores do not fit:
|
||||
|
||||
- **1 does not fit:** branch storage, tree entries, file modes, authors, and trailers all have recognizable, stable meanings.
|
||||
- **3 does not fit:** raw paths and branch names enter the common public read/write boundary, so validation friction is not isolated outside routine use.
|
||||
|
||||
Confidence is High because the accepting producers and their downstream interpretation are both visible within the scoped common path.
|
||||
|
||||
## `duplication-knowledge`: 2
|
||||
|
||||
The transformation “find a path in a commit tree, treat only `NotFound` as absence, load the entry as a blob, and copy its bytes” is independently implemented by `BranchStore::read_entry`, `BranchStore::read_entries`, and `Store::read_blob_at` (`branch.rs:119-158`, `git.rs:200-213`). An ordinary maintenance change to missing-entry or entry-kind behavior must synchronize all three common read locations. Ref qualification is also repeated in `update_ref`, `resolve_ref`, and `delete_ref` (`git.rs:182-226`).
|
||||
|
||||
Trailer grammar supplies independent corroboration at the commit-message edge: `": "` formatting/detection is separately encoded by `append`, `parse`, `format_message`, and `has_trailing_trailer_block` (`trailer.rs:9-25, 28-42, 45-65, 68-87`). Primary tags: `repeated-transformation`, `repeated-policy`.
|
||||
|
||||
Strongest counterevidence: important write knowledge is authoritative. `BranchStore::write_with` centralizes tip loading, parent linkage, commit creation, and ref advancement, while `GitAuthor::default` centralizes the fallback identity (`branch.rs:56-82`, `author.rs:13-35`).
|
||||
|
||||
Why adjacent scores do not fit:
|
||||
|
||||
- **1 does not fit:** the repeated implementations currently agree, and stable authorities exist for branch mutation, author defaults, and file-mode conversion.
|
||||
- **3 does not fit:** the repeated blob-read transformation appears on the public latest-entry and multi-entry common paths, so a routine storage-policy change encounters it centrally rather than only at an edge.
|
||||
|
||||
Confidence is High because the repeated transformations and the mechanisms that are already centralized can both be enumerated completely inside the scoped component.
|
||||
|
||||
## Rubric wording audit
|
||||
|
||||
The following rules or anchors were ambiguous or non-discriminating in this application. I resolved each explicitly rather than silently choosing an interpretation.
|
||||
|
||||
1. **One component score across several responsibilities.** The instruction says to judge “each mapped component,” while the anchors use singular phrases such as “a mapped responsibility” and “a core concept.” It does not say whether to average sub-responsibilities, take the worst concern, or weight by centrality. I scored the mapped checkpoint-storage responsibility and let a directly evidenced central concern cap the lens; isolated author/trailer helpers could affect a score only at 3 versus 4.
|
||||
|
||||
2. **How to establish “routine” and “central” with component-only evidence.** A public method may be a mapped entry point without being frequent, and scoped evidence cannot establish caller frequency. I treated bootstrap, latest reads/writes, and cleanup as routine because they are ordinary lifecycle operations implied by branch storage. I did not infer frequency for unrelated external call sites.
|
||||
|
||||
3. **N/E threshold versus an absent lifecycle path.** “Use N/E when evidence is insufficient” does not say whether a missing archive/retry API is negative evidence, out of scope, or grounds for N/E. I scored paths that are directly present (bootstrap, normal operation, cleanup), did not penalize an unobserved archive/retry design, and lowered ownership confidence for the coverage gap.
|
||||
|
||||
4. **Score 3 and score 4 overlap in every lens.** A positive reinforcing mechanism can coexist with isolated friction, so the score-4 requirement and score-3 anchor can both be true. I treated any evidenced unnecessary/frictional mechanism as a cap at 3; score 4 requires both a positive mechanism and no material friction in the mapped responsibility. This is why the unused manifest dependencies keep simplicity at 3 despite `write_with`.
|
||||
|
||||
5. **What qualifies as a “positive reinforcing mechanism.”** The rubric does not say whether tests, encapsulation alone, or a production authority qualifies. I required an operative production mechanism that funnels behavior or rejects invalid construction. Tests alone did not qualify.
|
||||
|
||||
6. **Ownership score 2 versus ordinary delegation.** “Cross recurring owners or dependency boundaries” could penalize every layered implementation. Decision rule 2 partly resolves this, but “same responsibility” remains subjective. I treated `BranchStore` calling `Store` during a write as ordinary delegation; I counted cleanup only because the caller must leave the branch-scoped owner and supply its identity again.
|
||||
|
||||
7. **Decision rule 1 when terminal operations live at a lower abstraction.** The rule says not to isolate recurring terminal owners but does not define whether a lower-level deletion primitive is a second owner or a delegate. Because `BranchStore` offers no cleanup interface and keeps the needed state private, I treated `Store::delete_ref` as a lifecycle-owner crossing, not merely internal machinery.
|
||||
|
||||
8. **Simplicity score 2’s “repeatedly traverse.”** It is unclear whether this means runtime calls passing through multiple necessary layers, or maintainers choosing among competing paths repeatedly. I used the latter interpretation, consistent with the lens question and decision rule 2; necessary Git layers did not lower the score.
|
||||
|
||||
9. **Decision rule 2’s “simplicity pressure.”** The rule labels machinery inside an owner as pressure even though the lens expressly permits necessary complexity and gives no score consequence for “pressure.” I treated machinery as evidence to test for necessity, not as an automatic deduction.
|
||||
|
||||
10. **Domain score 4 versus decision rule 4’s escape hatch.** “Every common boundary” is not defined, and a public low-level API can be called common or an escape hatch depending on external usage. I treated `TreeEntries::set` as common because `BranchStore::write_with`, `write_entry`, and `write_entries` use it directly; `Store::repo` was treated as an escape hatch.
|
||||
|
||||
11. **Decision rule 3 does not identify a score boundary.** It says a typed durable value does not “repair domain pressure,” but does not say whether a common invalid intermediate means 2 or merely prevents 4. I mapped common-path invalid intermediates to the score-2 anchor (“routine changes reconcile ... invalid intermediate states”); isolated invalid intermediates would map to 3.
|
||||
|
||||
12. **Duplication score 2 versus decision rule 5.** Rule 5 says to score 3 when a routine vocabulary change requires synchronization, while the score-2 anchor says routine synchronization of the same policy/invariant/transformation is score 2. Those statements conflict unless “vocabulary” is an unstated special case. I treated rule 5 narrowly as an exception for localized, string-only vocabulary at an edge. The score-2 finding here rests instead on repeated behavioral blob-read transformations on common paths.
|
||||
|
||||
13. **What test repetition counts as knowledge duplication.** The `repeated-test-knowledge` tag suggests tests can count, but the anchors do not distinguish duplicated policy from assertions that intentionally restate expected behavior. I did not count an assertion of a production contract as a second authority. Repeated test fixture setup was only isolated counterevidence and did not drive a numeric score.
|
||||
|
||||
14. **Decision rule 6 lacks a lens and defines neither “current referent” nor “line selector.”** Its opening phrase points toward `domain-model`, while duplicated CI selectors could point toward `duplication-knowledge`; its mandatory score 2 also bypasses centrality analysis. It had no referent in this component, so I did not apply it. If applicable, I would classify a single invalid identifier under domain model and synchronized copies under duplication.
|
||||
|
||||
15. **The “primary lens only” rule does not explain multi-causal facts.** Raw strings can simultaneously expose invalid states, repeat vocabulary, and force lifecycle handoffs. I assigned each negative fact once by its primary question: lifecycle handoff to ownership, unused dependencies to simplicity, raw path legality to domain, and repeated lookup/ref/trailer behavior to duplication.
|
||||
|
||||
16. **Confidence High cannot be finalized by one reviewer.** “Final High also requires independent readings to converge” is not decidable during an independent review. I reported evidence-quality confidence now and left final convergence to adjudication.
|
||||
|
||||
All other score-1 versus score-2 distinctions were discriminating here: the component consistently has identifiable owners, paths, concepts, and intended policies, so none of the “no stable ... can be identified” anchors fit.
|
||||
|
|
@ -1,182 +0,0 @@
|
|||
# Calibration review — reviewer 1
|
||||
|
||||
Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
Scope: `fabro-workflow`, `fabro-http`, `fabro-web-app`, and `repository-ci` as routed by `.chisel/cartography/codebase-map.md`. I excluded `apps/fabro-web/app/components/playground/**` from `fabro-web-app`, and limited `repository-ci` to `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, and `.github/zizmor.yml`. The routed paths have no changes between the map revision and the reviewed revision.
|
||||
|
||||
## Provisional ratings
|
||||
|
||||
| Component | Ownership boundaries | Simplicity | Domain model | Duplication of knowledge |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| `fabro-workflow` | **2 — High** | **2 — High** | **2 — High** | **2 — High** |
|
||||
| `fabro-http` | **4 — High** | **4 — High** | **4 — High** | **3 — High** |
|
||||
| `fabro-web-app` | **4 — High** | **2 — High** | **2 — High** | **2 — High** |
|
||||
| `repository-ci` | **4 — High** | **3 — High** | **2 — High** | **2 — High** |
|
||||
|
||||
## `fabro-workflow`
|
||||
|
||||
### Ownership boundaries — 2, High confidence
|
||||
|
||||
The component has a clear top-level phase boundary: `pipeline/mod.rs` orders parse, transform, validate, initialize, execute, finalize, and pull-request processing; `pipeline/types.rs` gives those phases distinct result types. `pipeline/execute.rs:execute`, `graph.rs:WorkflowGraph`, and `node_handler.rs:WorkflowNodeHandler` also make the boundary with the generic `fabro-core` executor explicit. `lifecycle/mod.rs:WorkflowLifecycle` composes named lifecycle owners instead of placing every callback in the executor.
|
||||
|
||||
The pressure appears in terminal-run ownership. The normal path is owned by `pipeline/finalize.rs:finalize` and `pipeline/finalize.rs:build_terminal_event`, while engine/bootstrap failures are handled by `operations/start.rs:emit_workflow_run_failed`, `operations/start.rs:persist_terminal_engine_failure`, and the completion/drop guards in `operations/start.rs`. Retry and archive operations also synthesize terminal events in `operations/retry.rs` and `operations/archive.rs`. These paths are understandable individually, but terminal state, persistence, and event emission do not have one stable lifecycle home.
|
||||
|
||||
A representative routine change is adding terminal metadata that must be present for every failed or concluded run. It would require checking or changing `pipeline/finalize.rs:build_terminal_event`, `pipeline/finalize.rs:finalize`, `operations/start.rs:emit_workflow_run_failed`, `operations/start.rs:persist_terminal_engine_failure`, the start-operation guards, and the corresponding terminal paths in `operations/retry.rs` and `operations/archive.rs`.
|
||||
|
||||
Strongest counterevidence: the main successful-run path is explicit and strongly partitioned, and `WorkflowLifecycle` plus `RunServices` give many responsibilities named owners.
|
||||
|
||||
Why adjacent scores do not fit: 3 understates the issue because terminal completion is a central lifecycle concern, not an edge-only exception; an ordinary terminal-contract change must inspect several authorities. 1 does not fit because the normal path and the exceptional paths are still traceable and deliberately named.
|
||||
|
||||
### Simplicity — 2, High confidence
|
||||
|
||||
The top-level flow is readable, but routine run startup crosses a large amount of central wiring. `operations/start.rs:start` enters `execute_persisted_run`, constructs `RunSession`, and then `RunSession::run` coordinates logging, SHA listeners, initialization, cleanup/drain guards, execution, finalization, and pull-request handling. `pipeline/types.rs:InitOptions` carries a large set of run inputs, and `operations/start.rs:RunSession::run` assembles them before handing control to `pipeline/initialize.rs`. The resulting services are then repartitioned through `services.rs:RunServices`, `services.rs:EngineServices`, and `pipeline/execute.rs:execute`.
|
||||
|
||||
A representative routine change is adding a run-scoped service needed by node handlers. It would pass through `operations/start.rs:StartServices` or `RunSession`, `pipeline/types.rs:InitOptions`, `pipeline/initialize.rs:initialize`, `pipeline/types.rs:Initialized`, `services.rs:RunServices`, `services.rs:EngineServices`, and the destructuring/building in `pipeline/execute.rs:execute`.
|
||||
|
||||
Strongest counterevidence: the phase result types in `pipeline/types.rs` and the extracted executor/lifecycle adapters make the long path navigable; the complexity is structured rather than accidental.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the pressure is on the common startup and execution path, and a small run-scoped dependency change propagates through several central handoff types. 1 does not fit because the ordered pipeline and named handoffs still provide a stable path through the component.
|
||||
|
||||
### Domain model — 2, High confidence
|
||||
|
||||
The strongest positive mechanism is the phase model in `pipeline/types.rs`: `Parsed`, `Transformed`, `Validated`, `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` constrain which data exists at each stage. Canonical run records are reused from `fabro-types`, and `services.rs:RunServices` documents cancellation ownership.
|
||||
|
||||
However, the core event path weakens those guarantees. `event/events.rs:Event::StageCompleted` carries `status: String`; lifecycle code such as `lifecycle/event.rs` converts `StageOutcome` to a string, and `event/convert.rs:stage_status_from_string` parses it back when creating the durable event. An unknown value is not rejected: it is warned about and converted to `StageOutcome::Failed`. The durable model in `fabro-types` is typed, but the internal central event model permits invalid status values and gives them a lossy fallback meaning. `WorkflowRunCompleted` similarly carries a string status internally.
|
||||
|
||||
Strongest counterevidence: the durable event body and most run/pipeline records use named enums and phase-specific types, so this is not a component with generally unmodeled state.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because stage and run outcomes are central workflow vocabulary used on every execution, and the internal-to-durable boundary permits and silently reinterprets invalid values. 1 does not fit because canonical typed outcomes exist and dominate downstream storage; the break is concentrated at the internal event boundary.
|
||||
|
||||
### Duplication of knowledge — 2, High confidence
|
||||
|
||||
Adding an event requires coordinated knowledge in several central authorities. The internal variant lives in `event/events.rs:Event`; its wire name is separately selected by `event/names.rs:event_name`; durable fields are declared in `fabro-types::EventBody`; conversion is implemented in `event/convert.rs:event_body_from_event`; stored-field behavior is selected in `event/stored_fields.rs:stored_event_fields_for_variant`; and tracing behavior is implemented on `Event`. `docs/internal/events-strategy.md` documents this multi-site procedure, confirming that this is the expected recurring event-evolution path rather than a one-off remnant.
|
||||
|
||||
A representative routine change is adding a persisted workflow event. It touches `event/events.rs:Event`, `event/names.rs:event_name`, the `Event` tracing method, `fabro_types::EventBody`, `event/convert.rs:event_body_from_event`, `event/stored_fields.rs:stored_event_fields_for_variant`, emitters, and any event consumers.
|
||||
|
||||
Strongest counterevidence: `event/emitter.rs:Emitter::emit_with_scope` constructs the canonical run event once before dispatch, exhaustive matches make omissions visible to the compiler, and the strategy document gives maintainers one checklist.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because event evolution is frequent, central workflow work and requires synchronized changes across representations and crates. 1 does not fit because each representation has a stated role and there is a single canonicalization point before dispatch.
|
||||
|
||||
Lens-boundary note: the internal `Event`/durable `EventBody` split could be described as a domain-model issue or duplication. I treated the repeated declarations and conversion sites as duplication of knowledge; the separate `String`-to-`StageOutcome` loss of meaning is the domain-model issue. Likewise, repeated terminal constructors are secondary duplication, but I classified the primary problem as ownership because the key question is which operation owns terminal lifecycle completion.
|
||||
|
||||
## `fabro-http`
|
||||
|
||||
### Ownership boundaries — 4, High confidence
|
||||
|
||||
`lib/foundation/fabro-http/src/lib.rs` is a small, focused owner for HTTP client construction and proxy policy. Callers get approved async or blocking builders and convenience clients from this crate. Repository lint policy in `clippy.toml` disallows direct `reqwest` constructors and points callers to `fabro-http`, so the boundary is reinforced rather than merely conventional. `ProxyPolicy::resolve` also owns the environment-variable authority through `fabro_static::EnvVars::FABRO_HTTP_PROXY_POLICY`.
|
||||
|
||||
Strongest counterevidence: the crate deliberately re-exports several `reqwest` types and carries lint exceptions for those facade exports, so callers are not isolated from every transport detail.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because construction policy, environment precedence, test defaults, and transport facade all have one enforced home with no observed competing builder authority.
|
||||
|
||||
### Simplicity — 4, High confidence
|
||||
|
||||
The common path is short: choose `HttpClientBuilder` or `BlockingHttpClientBuilder`, optionally configure it, resolve `ProxyPolicy`, and build the underlying client. `define_builder!` generates the shared async/blocking surface once, while the async-only `read_timeout` extension remains plainly visible next to the macro invocation. Convenience functions such as `http_client`, `blocking_http_client`, `test_http_client`, and `blocking_test_http_client` expose the common cases directly.
|
||||
|
||||
Strongest counterevidence: macro generation means the two concrete builder implementations are not visible as ordinary source, and async-only options must be added outside the shared definition.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the macro removes rather than creates routine common-option work: a shared builder option is added in one readable location, while the generated types remain thin wrappers.
|
||||
|
||||
### Domain model — 4, High confidence
|
||||
|
||||
`ProxyPolicy` names the only supported policies, `ProxyPolicy::parse` rejects unknown values, and `ProxyPolicy::resolve_with_env_value` makes precedence explicit: a caller override wins, then the environment value, then the system default. Test helpers force `Disabled`, making local test semantics deliberate. `HttpClientBuildError` distinguishes policy configuration failure from transport construction failure.
|
||||
|
||||
Strongest counterevidence: callers can express no-proxy behavior through both `proxy_policy(ProxyPolicy::Disabled)` and the lower-level `no_proxy()` builder method, and the facade re-exports lower-level proxy types.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the overlapping entry points do not introduce an ambiguous stored state or silent fallback: the policy values and their precedence are explicit, and invalid environment vocabulary fails closed.
|
||||
|
||||
### Duplication of knowledge — 3, High confidence
|
||||
|
||||
The builder macro is a strong anti-duplication mechanism for async and blocking clients. The remaining policy vocabulary is manually repeated: `ProxyPolicy` variants, `ProxyPolicy::parse`, the expected-value text in `HttpClientBuildError::InvalidProxyPolicy`, and the policy match in the generated `build` method must agree.
|
||||
|
||||
A representative routine change is adding another supported proxy policy. It would touch `ProxyPolicy`, `ProxyPolicy::parse`, the expected-value message on `HttpClientBuildError::InvalidProxyPolicy`, the `define_builder!` build-time match, and policy tests in the same source file.
|
||||
|
||||
Strongest counterevidence: every repeated policy decision is co-located in one small file, and the exhaustive build match makes a missing behavioral branch a compile error.
|
||||
|
||||
Why adjacent scores do not fit: 4 does not fit because the accepted vocabulary and error vocabulary are independently maintained strings. 2 does not fit because the synchronization is confined to one authority and does not force routine callers or neighboring components to change.
|
||||
|
||||
Lens-boundary note: macro use could be counted as simplicity indirection, but its primary effect here is eliminating async/blocking duplication. The generated control flow is small enough that I did not lower simplicity for it.
|
||||
|
||||
## `fabro-web-app`
|
||||
|
||||
### Ownership boundaries — 4, High confidence
|
||||
|
||||
The app has explicit composition points. `app/entry.tsx` selects normal or install mode and installs shared providers; `app/router.tsx` and `app/install-router.tsx` own the two route trees. `app/lib/api-client.ts` owns generated-client construction and uniform API errors, `app/lib/query-keys.ts` owns cache keys, and `app/lib/queries.ts` owns shared reads. The React effects policy is embodied by approved wrappers in `app/hooks/effects.ts`; direct effect usage is concentrated in hooks and live-event libraries rather than route/component bodies. `scripts/build.ts` separately owns deterministic asset building and atomic publication.
|
||||
|
||||
Strongest counterevidence: some cache mutation and API-write coordination remains in route handlers, particularly in the large run and installation screens, so not every server interaction passes through a single application-service layer.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because routing, reads, client configuration, effects, and build publication each have a visible and consistently used owner; route-local writes are appropriate UI orchestration rather than a competing global authority.
|
||||
|
||||
### Simplicity — 2, High confidence
|
||||
|
||||
The normal routing shell is simple, but two central screens concentrate substantial policy and presentation. `app/routes/run-stages.tsx` combines event-to-turn reduction, event filtering, grouping, stage/activity interpretation, row and panel rendering, stage renderer selection, and the route page. `app/install-app.tsx` similarly combines installation state transitions, controller behavior, forms, and view composition. Cross-tab stream coordination in `app/lib/cross-tab-sse.ts` is another large central mechanism.
|
||||
|
||||
A representative routine change is showing a new kind of stage activity in the run timeline. It requires following `app/lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES`, `app/routes/run-stages.tsx:STAGE_ACTIVITY_EVENT_SET`, `app/routes/run-stages.tsx:buildStageActivity`, the route's turn/activity types, and the corresponding render helpers in the same large route module.
|
||||
|
||||
Strongest counterevidence: shared event lists, query keys, generated API types, and route helpers provide landmarks, and the activity reducer is deterministic rather than dispersed among many components.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because run-stage interpretation is a common product path and small presentation changes require navigating large modules that mix reduction and rendering concerns. 1 does not fit because the route and install flows remain typed, testable, and traceable from explicit entry points.
|
||||
|
||||
### Domain model — 2, High confidence
|
||||
|
||||
Generated API types provide a strong canonical model for ordinary request/response queries, and several local models use discriminated unions. The live-event boundary is weaker. `app/lib/sse.ts:EventPayload` permits an optional event name plus arbitrary fields. `app/lib/run-events.ts:RunEventPayload` and `app/lib/live-events.ts:LiveEventPayload` repeat mostly optional envelope fields with `properties: unknown`. `app/lib/sse.ts:subscribeToSharedEventSource` parses JSON and casts it to the requested payload type without runtime validation. Common live UI behavior therefore accepts payloads that lack the fields implied by their event names.
|
||||
|
||||
There is additional vocabulary translation in `app/data/runs.ts:RunStatus`, which locally reproduces API run-state kinds and adds presentation state, and compatibility shape probing in `app/lib/run-sandbox-lifecycle.ts:sandboxLifecycleKind` and `sandboxInstance`.
|
||||
|
||||
Strongest counterevidence: generated types remain the authority for normal API calls, `session-stream.ts` and query paths use generated event-envelope types where possible, and the local run status adds a genuine presentation concept rather than merely renaming every API state.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because SSE drives common live run behavior and its central payload model makes invalid event/field combinations representable and unchecked. 1 does not fit because static generated models are sound and the weak representation is concentrated at live and compatibility boundaries.
|
||||
|
||||
### Duplication of knowledge — 2, High confidence
|
||||
|
||||
Live refresh policy is repeated in separate manually curated authorities. `app/lib/run-events.ts:RUN_SUMMARY_EVENTS` lists events that invalidate run summaries, while `app/lib/board-events.ts:BOARD_STATUS_EVENTS` independently lists many of the same run, interview, and pull-request lifecycle events for board refresh. The duplicated payload interfaces in `run-events.ts` and `live-events.ts` add another synchronization surface.
|
||||
|
||||
A representative routine change is adding a lifecycle event that changes both a run summary and its board status. It requires updating `app/lib/run-events.ts:RUN_SUMMARY_EVENTS` and `app/lib/board-events.ts:BOARD_STATUS_EVENTS`, then checking phase derivation in `app/lib/run-phases.ts:deriveRunPhases` and live consumers if the event also changes the visible run phase.
|
||||
|
||||
Strongest counterevidence: stage activity vocabulary is centralized in `app/lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES` and imported by the run-stages route; query keys and server contract types are also centralized or generated.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the repeated invalidation lists govern common live behavior, and a missing update produces stale UI rather than a compile-time failure. 1 does not fit because each list has a clear local purpose and several other high-change vocabularies already have a single authority.
|
||||
|
||||
Lens-boundary note: the repeated loose live-event interfaces are both duplicate declarations and a weak model. I treated representable invalid payloads and unchecked casts as the domain-model finding; I used independently maintained event-invalidation sets as the primary duplication finding. The size of `run-stages.tsx` is primarily simplicity pressure, not evidence that its route ownership is unclear.
|
||||
|
||||
## `repository-ci`
|
||||
|
||||
### Ownership boundaries — 4, High confidence
|
||||
|
||||
`.github/workflows/rust.yml` and `.github/workflows/typescript.yml` have an explicit language split and named jobs for formatting, linting, generated documentation, tests, type checking, and builds. Each workflow sets narrow permissions, concurrency behavior is visible, and toolchain/action versions are pinned. The TypeScript build job's Rust build step has a clear purpose: verify the embedded production SPA through the repository's actual build command.
|
||||
|
||||
Strongest counterevidence: the Rust clippy job contains a repository-specific legacy-auth `git grep` policy check, rather than delegating that policy to a named script or dedicated job.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the special check is still plainly owned by repository validation, while language-level checks, permissions, and production build validation have unambiguous homes and no competing workflow was observed.
|
||||
|
||||
### Simplicity — 3, High confidence
|
||||
|
||||
The workflows are short and linear, with direct commands corresponding to local development commands. Friction is isolated: setup steps are repeated across jobs, the clippy job embeds a multi-pattern shell assertion for legacy auth identity removal, and the ignored twin E2E selection is encoded directly in a long `nextest` expression. These cost attention but do not obscure the overall validation flow.
|
||||
|
||||
A representative routine change is adding a new TypeScript validation job. It would repeat the checkout, Bun setup, and dependency-install sequence already present in `.github/workflows/typescript.yml:jobs.typecheck`, `jobs.test`, and `jobs.build`, then add the new command.
|
||||
|
||||
Strongest counterevidence: each job can be understood independently, commands are explicit, and there is no multi-layer reusable-workflow indirection.
|
||||
|
||||
Why adjacent scores do not fit: 4 does not fit because repeated setup and inline special policies add avoidable local friction. 2 does not fit because ordinary check changes still have a direct path through one small workflow and do not cross a complex control structure.
|
||||
|
||||
### Domain model — 2, High confidence
|
||||
|
||||
Some configuration identifiers no longer denote repository reality. Both push and pull-request triggers in `.github/workflows/rust.yml` refer to `openapi/**`, but that path does not exist; the actual API contract is `docs/public/api-reference/fabro-api.yaml`, which the same workflow's legacy-auth check names directly. `.github/workflows/typescript.yml` also omits that contract path even though the TypeScript API client is generated from it. A contract-only change can therefore fall outside the configured validation vocabulary.
|
||||
|
||||
`.github/zizmor.yml:rules.stale-action-refs.ignore` identifies three exceptions by `rust.yml` source line. History shows those locations originally denoted Rust toolchain actions, while the current line numbers point elsewhere after workflow edits. The exception's identity is coupled to incidental layout rather than the action it is meant to describe.
|
||||
|
||||
Strongest counterevidence: jobs, test modes, toolchain versions, permissions, and build profiles are otherwise named explicitly and line up with repository commands.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the stale/nonexistent identifiers affect whether central source-of-truth changes are validated and whether static-validation exceptions retain their intended meaning. 1 does not fit because most CI vocabulary remains stable and the affected values can be corrected from clear repository authorities.
|
||||
|
||||
### Duplication of knowledge — 2, High confidence
|
||||
|
||||
Trigger-path knowledge is repeated in every workflow and twice within each workflow: `.github/workflows/rust.yml:on.push.paths` duplicates `on.pull_request.paths`, and `.github/workflows/typescript.yml` does the same. Cross-language contract inputs then require synchronized edits in both files. The stale `openapi/**` entry and omission of `docs/public/api-reference/fabro-api.yaml` are direct evidence that this repeated knowledge has drifted.
|
||||
|
||||
A representative routine change is moving or adding a source-of-truth file that must trigger all relevant CI. It requires updating `rust.yml:on.push.paths`, `rust.yml:on.pull_request.paths`, `typescript.yml:on.push.paths`, and `typescript.yml:on.pull_request.paths`; there is no shared authority that makes one update cover the four consumers.
|
||||
|
||||
Strongest counterevidence: commands and action versions are local to their jobs, so much of the visible repetition is deliberate job isolation, and each language workflow is small.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because trigger selection is central to CI's purpose, the synchronization crosses both event sections and language workflows, and actual drift is present. 1 does not fit because the duplicated lists are easy to locate and most entries still agree.
|
||||
|
||||
Lens-boundary note: the stale OpenAPI trigger could be scored only as duplicate path knowledge. I used the repeated four-list maintenance burden for duplication, while treating the fact that `openapi/**` currently has no referent—and that line-based Zizmor identities no longer name the intended actions—as domain vocabulary drift.
|
||||
|
|
@ -1,176 +0,0 @@
|
|||
# Calibration Sample Review — Reviewer 2
|
||||
|
||||
Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
This review uses the component boundaries in `.chisel/cartography/codebase-map.md`. In particular, `fabro-web-app` excludes `apps/fabro-web/app/components/playground/**`, and `repository-ci` contains only `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, and `.github/zizmor.yml`.
|
||||
|
||||
## Score summary
|
||||
|
||||
| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge |
|
||||
|---|---:|---:|---:|---:|
|
||||
| `fabro-workflow` | 3 (Medium) | 2 (High) | 3 (Medium) | 2 (High) |
|
||||
| `fabro-http` | 4 (High) | 4 (High) | 3 (High) | 4 (High) |
|
||||
| `fabro-web-app` | 4 (Medium) | 2 (Medium) | 2 (Medium) | 2 (Medium) |
|
||||
| `repository-ci` | 4 (High) | 3 (High) | 3 (High) | 2 (High) |
|
||||
|
||||
## `fabro-workflow`
|
||||
|
||||
### `ownership-boundaries` — 3, Medium confidence
|
||||
|
||||
The component has a recognizable high-level owner and intended dependency direction. `lib/components/fabro-workflow/src/operations/mod.rs` owns run-level operations, while `lib/components/fabro-workflow/src/pipeline/mod.rs` owns the ordered phase API. `lib/components/fabro-workflow/src/pipeline/types.rs:Parsed`, `Transformed`, `Validated`, `Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` make phase ownership explicit. `lib/components/fabro-workflow/src/services.rs:RunServices` and `EngineServices` distinguish run-lifetime services from node-execution services, and `lib/components/fabro-workflow/src/node_handler.rs:WorkflowNodeHandler` is a visible adapter to `fabro-core`.
|
||||
|
||||
The friction is at the public edge: `lib/components/fabro-workflow/src/lib.rs` exposes operations, pipeline phases, handlers, records, services, runtime storage, and several `#[doc(hidden)]` modules. Callers can therefore enter below the complete lifecycle as well as through `lib/components/fabro-workflow/src/operations/start.rs:start`. This weakens containment, but it does not create a competing production owner.
|
||||
|
||||
**Strongest counterevidence:** The typed phase outputs and the `RunServices`/`EngineServices` split strongly reinforce one workflow lifecycle.
|
||||
|
||||
**Why adjacent scores do not fit:** A 4 does not fit because the broad facade exposes enough lifecycle internals to make the boundary porous. A 2 does not fit because the normal `start` path and each phase owner remain identifiable and dependencies are delegated to dedicated crates.
|
||||
|
||||
### `simplicity` — 2, High confidence
|
||||
|
||||
The stable common path is traceable, but routine work crosses substantial central machinery: `lib/components/fabro-workflow/src/operations/start.rs:start` → `execute_persisted_run` → `RunSession::new` → `RunSession::run` → `pipeline::initialize` → `pipeline::execute` → `pipeline::finalize` → `pipeline::pull_request`. Along that path, `StartServices`, `RunSession`, and `lib/components/fabro-workflow/src/pipeline/types.rs:InitOptions` each carry many run concerns, while bootstrap, completion, cleanup, steering-drain, sandbox, and event-flush guards add multiple exit paths. `lib/components/fabro-workflow/src/pipeline/initialize.rs:initialize` also coordinates sandbox creation/reconnection, hooks, credentials, Git setup, handler construction, and resume state.
|
||||
|
||||
**Representative routine change:** Adding one run-scoped execution service would normally thread through `operations/start.rs:StartServices`, `RunSession`, and `RunSession::new`; `pipeline/types.rs:InitOptions`; `pipeline/initialize.rs:initialize`; and `services.rs:RunServices` or `EngineServices`.
|
||||
|
||||
**Strongest counterevidence:** `operations/start.rs:RunSession::run` presents the main phases in a linear order, and the phase-specific types preserve that order despite the setup machinery.
|
||||
|
||||
**Why adjacent scores do not fit:** A 3 does not fit because the pressure is on the main run path rather than at an edge. A 1 does not fit because there is a stable phase sequence and named service bundles to follow.
|
||||
|
||||
### `domain-model` — 3, Medium confidence
|
||||
|
||||
The strongest mechanism is the phase-state model in `lib/components/fabro-workflow/src/pipeline/types.rs`; private fields on `Validated` and `Persisted` and opaque `ResumeState` prevent several invalid transitions. `lib/components/fabro-workflow/src/pipeline/finalize.rs:classify_engine_result` is also a clear authority for translating an engine result into `StageOutcome`, failure detail, and `RunStatus`.
|
||||
|
||||
The main friction is the extensible, string-valued handler vocabulary on the common graph path. `lib/components/fabro-workflow/src/handler/mod.rs:HandlerRegistry::resolve` works with type strings and falls back to the default handler, while `default_registry` registers the built-in strings. Validation in `fabro-validate` protects normal runs, but execution itself does not carry a closed built-in handler type.
|
||||
|
||||
**Strongest counterevidence:** `pipeline/types.rs:ResumeState::from_projection`, the phase output types, and `pipeline/finalize.rs:classify_engine_result` give important workflow concepts one enforced shape.
|
||||
|
||||
**Why adjacent scores do not fit:** A 4 does not fit because handler identity remains string-valued and default-resolved through a central execution boundary. A 2 does not fit because validation and typed phase states canonicalize the normal run before execution.
|
||||
|
||||
### `duplication-knowledge` — 2, High confidence
|
||||
|
||||
Event knowledge is repeated across central authorities. `lib/components/fabro-workflow/src/event/events.rs:Event` defines the emitter-facing shape, `lib/components/fabro-workflow/src/event/convert.rs:event_body_from_event` translates it to the stored `fabro_types::EventBody`, `lib/components/fabro-workflow/src/event/names.rs:event_name` separately assigns wire names, and `lib/components/fabro-workflow/src/event/stored_fields.rs:stored_event_fields_for_variant` separately assigns envelope metadata. These exhaustive matches help detect omissions, but every ordinary event extension still requires synchronized semantic decisions.
|
||||
|
||||
**Representative routine change:** Adding a stored workflow event can touch `event/events.rs:Event`, `event/convert.rs:event_body_from_event`, `event/names.rs:event_name`, `event/stored_fields.rs:stored_event_fields_for_variant`, and the canonical `lib/foundation/fabro-types/src/run_event/mod.rs:EventBody` authority.
|
||||
|
||||
**Strongest counterevidence:** `event/convert.rs:to_run_event_at` is the single assembly point, and Rust's exhaustive matches turn many missed updates into compile failures.
|
||||
|
||||
**Why adjacent scores do not fit:** A 3 does not fit because event emission and persistence are central, recurring behavior. A 1 does not fit because the authorities are explicit and compiler-checked rather than unidentifiable.
|
||||
|
||||
## `fabro-http`
|
||||
|
||||
### `ownership-boundaries` — 4, High confidence
|
||||
|
||||
`lib/foundation/fabro-http/src/lib.rs` has one focused transport-construction boundary. `HttpClientBuilder`, `BlockingHttpClientBuilder`, `ProxyPolicy`, the client aliases, and the production/test constructors all live there; the crate depends only on `fabro-static`, `reqwest`, and `thiserror`. Repository policy reinforces the boundary through `clippy.toml:disallowed-methods`, which directs raw reqwest construction to this facade.
|
||||
|
||||
**Strongest counterevidence:** The public reqwest aliases and re-exports make the abstraction intentionally permeable, so it does not own higher-level request behavior.
|
||||
|
||||
**Why the adjacent score does not fit:** A 3 does not fit because exposing reqwest types is part of the mapped purpose, while construction policy and proxy resolution still have one clear owner.
|
||||
|
||||
### `simplicity` — 4, High confidence
|
||||
|
||||
`lib/foundation/fabro-http/src/lib.rs:define_builder` expresses shared async/blocking forwarding once. Both builders end at the same short `ProxyPolicy::resolve` and `build` path, and `http_client`, `test_http_client`, `blocking_http_client`, and `blocking_test_http_client` are thin named entry points. A shared reqwest builder option is normally added once to the macro.
|
||||
|
||||
**Strongest counterevidence:** The macro hides generated methods, and async-only `HttpClientBuilder::read_timeout` must sit outside it.
|
||||
|
||||
**Why the adjacent score does not fit:** A 3 does not fit because this indirection directly removes twin implementations and leaves callers with a single conventional builder path.
|
||||
|
||||
### `domain-model` — 3, High confidence
|
||||
|
||||
`lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` gives the repository policy two named states, `ProxyPolicy::resolve_with_env_value` defines explicit-over-environment precedence, and `HttpClientBuildError::InvalidProxyPolicy` rejects unknown values. The tests cover default, environment, invalid, and explicit-override cases.
|
||||
|
||||
The isolated ambiguity is that `HttpClientBuilder::no_proxy` and `HttpClientBuilder::proxy_policy(ProxyPolicy::Disabled)` both publicly express disabled proxy behavior, but `no_proxy` mutates the inner builder without updating the policy field. Their relationship is not represented or documented in the type.
|
||||
|
||||
**Strongest counterevidence:** The closed enum, typed error, and resolver tests make the environment-facing policy meaning unusually explicit.
|
||||
|
||||
**Why adjacent scores do not fit:** A 4 does not fit because two public controls overlap without an encoded relationship. A 2 does not fit because the overlap is local and every normal constructor still passes through one two-state resolver.
|
||||
|
||||
### `duplication-knowledge` — 4, High confidence
|
||||
|
||||
The builder macro is the authority for behavior shared by synchronous and asynchronous clients, and every constructor delegates to those builders. The production/test and async/blocking helper names repeat syntax, not policy: test behavior is expressed once as `ProxyPolicy::Disabled`.
|
||||
|
||||
**Strongest counterevidence:** Four constructor helpers and the separate async-only impl are superficially repetitive.
|
||||
|
||||
**Why the adjacent score does not fit:** A 3 does not fit because changing proxy precedence or disabled behavior has one authority; the remaining repetition does not require synchronized policy decisions.
|
||||
|
||||
## `fabro-web-app`
|
||||
|
||||
### `ownership-boundaries` — 4, Medium confidence
|
||||
|
||||
The main browser lifecycle has clear homes. `apps/fabro-web/app/entry.tsx` selects install or normal routing and owns root providers; `app/router.tsx:routes` owns the product route graph; `app/install-router.tsx:installRoutes` owns first-run routing; `app/lib/api-client.ts` owns HTTP normalization; `app/lib/queries.ts` and `app/lib/mutations.ts` own shared server access; and `app/hooks/effects.ts` contains reusable browser-effect lifecycles. Route modules own page-specific composition. The separately mapped playground enters through `app/router.tsx` without its excluded implementation being absorbed into this assessment.
|
||||
|
||||
**Strongest counterevidence:** `app/routes/run-stages.tsx` and `app/install-app.tsx` each combine page state, domain projection, and rendering in one route-owned file.
|
||||
|
||||
**Why the adjacent score does not fit:** A 3 does not fit because those combinations create local complexity, but no competing owner or reversed dependency was identified; shared cross-route responsibilities still have clear modules.
|
||||
|
||||
### `simplicity` — 2, Medium confidence
|
||||
|
||||
Two common product paths carry central transformation machinery. `apps/fabro-web/app/routes/run-stages.tsx` turns event envelopes into `TurnType` values in `buildStageActivity`, then separately groups, filters, timelines, labels, summarizes, and renders them through `buildChatItems`, `groupConsecutiveTools`, `filterDisplayItems`, `buildThreadDnaItems`, and the route's view components. `apps/fabro-web/app/install-app.tsx` similarly contains the install reducer, session hydration, controller, step forms, review, finishing, payload construction, and supporting controls in one flow.
|
||||
|
||||
**Representative routine change:** Changing how a tool event appears on the stage page requires tracing `run-stages.tsx:buildStageActivity`, `buildChatItems`/`groupConsecutiveTools`, `buildThreadDnaItems`, `turnLabel`, `turnSummary`, `EventDetails`, and `StageChatView`.
|
||||
|
||||
**Strongest counterevidence:** The stage path uses discriminated unions and mostly pure exported transformations with focused tests, so each individual step can be reasoned about.
|
||||
|
||||
**Why adjacent scores do not fit:** A 3 does not fit because the long transformation chains are central to major routes. A 1 does not fit because the named pure functions provide a stable trace through both flows.
|
||||
|
||||
### `domain-model` — 2, Medium confidence
|
||||
|
||||
Generated API types provide a useful boundary, but the central event path accepts several simultaneous shapes. `apps/fabro-web/app/lib/run-events.ts:RunEventPayload` makes event identity and metadata optional and `stageIdFromPayload` falls back from `stage_id` to `node_id` to `properties.node_id`. `app/routes/run-stages.tsx:activityEventStageId` repeats that shape tolerance for stored `EventEnvelope`s, while `buildStageActivity` reads tool, text, argument, and output values from both `properties` and legacy top-level fields via `app/lib/unknown.ts`.
|
||||
|
||||
**Representative routine change:** Moving one stage-event field to its canonical envelope location can require coordinated interpretation changes in `lib/run-events.ts:RunEventPayload` and `stageIdFromPayload`, plus `routes/run-stages.tsx:activityEventStageId` and `buildStageActivity`.
|
||||
|
||||
**Strongest counterevidence:** Once parsed, `run-stages.tsx:TurnType`, `StageRenderer`, and generated `StageHandler`/`StageState` types give the UI clear closed shapes.
|
||||
|
||||
**Why adjacent scores do not fit:** A 3 does not fit because the multi-shape event interpretation is on live invalidation and the main stage view, not an edge. A 1 does not fit because generated types and discriminated UI projections establish a stable canonical shape after parsing.
|
||||
|
||||
### `duplication-knowledge` — 2, Medium confidence
|
||||
|
||||
Stage-state presentation policy is authoritative in several common views. `apps/fabro-web/app/lib/stage-sidebar.ts:ACTIVE_STAGE_STATES`, `IN_FLIGHT_STAGE_STATES`, `SUCCEEDED_STAGE_STATES`, `STAGE_STATUS_TONE`, and `STAGE_STATUS_LABEL` define classifications and visuals, while `app/components/stage-sidebar.tsx:statusConfig`, `app/components/run-waterfall.tsx:stageBarClass` and `isStageInFlight`, and `app/components/stage-popover.tsx:StatusPill` make parallel state decisions.
|
||||
|
||||
**Representative routine change:** Adding a generated `StageState` requires reviewing or changing all of those authorities so the sidebar, waterfall, and popover agree on activity, success, label, and tone.
|
||||
|
||||
**Strongest counterevidence:** Generated `StageState` plus exhaustive `Record<StageState, ...>` mappings catch many omissions, and `lib/stage-sidebar.ts` already centralizes several shared classifications.
|
||||
|
||||
**Why adjacent scores do not fit:** A 3 does not fit because stage status is central to multiple routine run views and synchronization is recurring. A 1 does not fit because the generated enum is a clear semantic authority and TypeScript catches many missing cases.
|
||||
|
||||
## `repository-ci`
|
||||
|
||||
### `ownership-boundaries` — 4, High confidence
|
||||
|
||||
The two workflows divide validation by ecosystem: `.github/workflows/rust.yml:jobs` owns Rust format, lint, generated-doc, workspace test, twin-mode ignored tests, and manual macOS validation; `.github/workflows/typescript.yml:jobs` owns web/client typecheck, web tests, and the embedded-SPA production build. Both use top-level empty permissions and job-local read permission. The cross-language Cargo build in the TypeScript build job validates the mapped embedded-SPA integration rather than creating a second build owner.
|
||||
|
||||
**Strongest counterevidence:** The Rust clippy job contains a repository-wide legacy-auth guard that also scans TypeScript and API paths.
|
||||
|
||||
**Why the adjacent score does not fit:** A 3 does not fit because that cross-language invariant remains an explicitly named CI check, while job and workflow lifecycle ownership stays clear.
|
||||
|
||||
### `simplicity` — 3, High confidence
|
||||
|
||||
The main flow is explicit: named jobs perform checkout, tool setup, and one or two direct repository commands. The isolated friction is `.github/workflows/rust.yml:jobs.clippy.steps.Verify legacy auth identity removal`, where a long regular expression and shell exit-status protocol are embedded in a lint job. The twin-mode test semantics also need a substantial comment and package expression in `jobs.test`.
|
||||
|
||||
**Strongest counterevidence:** Separate jobs, direct commands, pinned tools, and no reusable-workflow indirection make routine CI behavior easy to locate.
|
||||
|
||||
**Why adjacent scores do not fit:** A 4 does not fit because the legacy guard and twin-mode selection require non-obvious local interpretation. A 2 does not fit because that machinery is isolated and ordinary check changes still follow a direct job structure.
|
||||
|
||||
### `domain-model` — 3, High confidence
|
||||
|
||||
Job names, triggers, permissions, platforms, and commands have consistent meanings in the GitHub Actions structure. Exact action SHAs and named modes such as `--profile ci` reduce ambiguity. The main gap is that `.github/workflows/rust.yml:jobs.test` relies on the external default meaning of `FABRO_TEST_MODE` for its twin run rather than setting the mode in the workflow; the comment is the only local declaration of that state.
|
||||
|
||||
**Strongest counterevidence:** The command, package selector, and explanation tightly describe the intended twin-only behavior, and every job has an explicit runner and permission set.
|
||||
|
||||
**Why adjacent scores do not fit:** A 4 does not fit because a central test mode is implicit in an external default. A 2 does not fit because the rest of the workflow vocabulary is coherent and the implicit state is limited to one documented test step.
|
||||
|
||||
### `duplication-knowledge` — 2, High confidence
|
||||
|
||||
Trigger policy is repeated verbatim between `on.push.paths` and `on.pull_request.paths` in both workflow files. Action versions and bootstrap steps are also copied across every job. `.github/zizmor.yml:rules.stale-action-refs.ignore` adds line-number references to `rust.yml`, creating another manually synchronized representation; at this revision its listed lines 37, 49, and 62 are respectively a blank line, the `fmt` job key, and a Cargo command rather than action references.
|
||||
|
||||
**Representative routine change:** Adding a new Rust-owned source area requires matching edits to `.github/workflows/rust.yml:on.push.paths` and `on.pull_request.paths`; upgrading checkout requires synchronized edits in `jobs.fmt`, `clippy`, `generated-docs`, `test`, and `test-macos`, followed by review of `.github/zizmor.yml:rules.stale-action-refs.ignore`.
|
||||
|
||||
**Strongest counterevidence:** The duplication is explicit and small enough to inspect, and each actual validation command appears once in its intended job.
|
||||
|
||||
**Why adjacent scores do not fit:** A 3 does not fit because triggers and action versions are central, recurring maintenance knowledge and the stale line selectors demonstrate drift. A 1 does not fit because the canonical workflows and intended checks remain identifiable.
|
||||
|
||||
## Lens-boundary confusion
|
||||
|
||||
- The `fabro-workflow` `Event`/`EventBody` split could be described as two domain shapes. I assigned its score effect to `duplication-knowledge` because the discriminating problem is the synchronized event name, conversion, and envelope-field decisions, not an inability to identify either type's meaning.
|
||||
- The size and mixed contents of `fabro-web-app` route files could look like misplaced responsibility. I assigned the main effect to `simplicity` because the route remains the clear owner; the problem is tracing the amount of local machinery.
|
||||
- Repeated `StageState` maps could be treated as domain drift. I assigned them to `duplication-knowledge` because the generated enum preserves meaning and the observed burden is repeating presentation/classification policy across views.
|
||||
- The `.github/zizmor.yml` line selectors could be treated as invalid configuration meaning. I assigned their main effect to `duplication-knowledge` because the failure mechanism is manual synchronization with line positions; `repository-ci` domain scoring instead uses the implicit twin-mode default.
|
||||
- `fabro-http`'s macro could be treated as simplicity indirection, while its two proxy-disable controls could be treated as duplicate policy. I treated the macro as a positive simplicity/duplication mechanism and the overlapping controls as `domain-model` friction because the unresolved question is what each public control means.
|
||||
|
|
@ -1,490 +0,0 @@
|
|||
# Calibration Sample Review — Reviewer 3
|
||||
|
||||
Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
Scope follows `.chisel/cartography/codebase-map.md`: `fabro-workflow`,
|
||||
`fabro-http`, `fabro-web-app`, and `repository-ci`. The `fabro-web-app`
|
||||
reading excludes `apps/fabro-web/app/components/playground/**`;
|
||||
`repository-ci` includes only `.github/workflows/rust.yml`,
|
||||
`.github/workflows/typescript.yml`, and `.github/zizmor.yml`.
|
||||
|
||||
## Provisional Matrix
|
||||
|
||||
| Component | Ownership and boundaries | Simplicity | Domain model | Duplication of knowledge |
|
||||
|---|---:|---:|---:|---:|
|
||||
| `fabro-workflow` | 4 / High | 2 / High | 2 / High | 2 / High |
|
||||
| `fabro-http` | 4 / High | 4 / High | 4 / High | 4 / High |
|
||||
| `fabro-web-app` | 3 / High | 2 / High | 2 / High | 2 / High |
|
||||
| `repository-ci` | 3 / High | 3 / High | 2 / High | 2 / High |
|
||||
|
||||
## `fabro-workflow`
|
||||
|
||||
### `ownership-boundaries` — 4, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `lib/components/fabro-workflow/src/pipeline/mod.rs` exposes an ordered phase
|
||||
facade, while `pipeline/types.rs:Parsed`, `Transformed`, `Validated`,
|
||||
`Persisted`, `Initialized`, `Executed`, `Concluded`, and `Finalized` give each
|
||||
phase an explicit handoff.
|
||||
- `lib/components/fabro-workflow/src/handler/mod.rs:Handler` and
|
||||
`HandlerRegistry` own workflow-specific dispatch;
|
||||
`src/node_handler.rs:WorkflowNodeHandler` is the narrow adapter to
|
||||
`fabro_core::handler::NodeHandler`.
|
||||
- `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` states
|
||||
that it owns callback ordering and delegates event, hook, fidelity,
|
||||
auto-status, circuit-breaker, Git, and artifact work to focused lifecycle
|
||||
objects.
|
||||
- `lib/components/fabro-workflow/Cargo.toml:[dependencies]` points from the
|
||||
orchestrator to parsing, validation, sandbox, persistence, model, and generic
|
||||
execution crates; generic traversal remains in `fabro-core`.
|
||||
|
||||
Strongest counterevidence: startup state is carried through
|
||||
`operations/start.rs:StartServices`, `RunSession`,
|
||||
`pipeline/types.rs:InitOptions`, and `services.rs:RunServices` /
|
||||
`EngineServices`, so the lifecycle boundary has substantial wiring.
|
||||
|
||||
Why adjacent scores do not fit: 3 would treat that wiring as unclear ownership,
|
||||
but the common path consistently identifies phase, handler, lifecycle, and
|
||||
generic-executor owners. The counterevidence is primarily machinery inside the
|
||||
intended orchestration owner, not a competing dependency direction or lifecycle
|
||||
home.
|
||||
|
||||
### `simplicity` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- The normal start path crosses
|
||||
`operations/start.rs:start` → `execute_persisted_run` →
|
||||
`RunSession::new` → `RunSession::run` →
|
||||
`pipeline::initialize` → `pipeline::execute` →
|
||||
`pipeline::finalize` → `pipeline::pull_request`.
|
||||
- The same run-scoped collaborators are reshaped across
|
||||
`operations/start.rs:StartServices`, `RunSession`,
|
||||
`pipeline/types.rs:InitOptions`, `services.rs:RunServices`, and
|
||||
`EngineServices`.
|
||||
- `lifecycle/mod.rs:WorkflowLifecycle::new` takes the full set of lifecycle
|
||||
collaborators and has an explicit `too_many_arguments` exception before
|
||||
constructing seven sub-lifecycles with shared coordination state.
|
||||
|
||||
Strongest counterevidence: the phase-state types in
|
||||
`pipeline/types.rs` and the focused handler/lifecycle modules make this
|
||||
machinery traceable; the common path is not hidden.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because every ordinary run
|
||||
traverses the service reshaping and multi-stage cleanup/finalization path; this
|
||||
is central rather than edge friction. 1 does not fit because the named phase
|
||||
sequence and handoff types provide a stable path through the machinery.
|
||||
|
||||
Representative routine change: adding a run-scoped execution-audit sink for
|
||||
handlers would require threading it through
|
||||
`operations/start.rs:StartServices`, `RunSession`,
|
||||
`RunSession::new`, `RunSession::run`,
|
||||
`pipeline/types.rs:InitOptions`, `pipeline/initialize.rs:initialize`, and
|
||||
`services.rs:RunServices` or `EngineServices`.
|
||||
|
||||
### `domain-model` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- Positive mechanisms are substantial:
|
||||
`pipeline/types.rs:Validated` hides its graph and exposes validation
|
||||
operations, `ResumeState::from_projection` creates opaque resume state, and
|
||||
`run_status.rs` plus `outcome.rs` reuse canonical types from `fabro-types` and
|
||||
`fabro-core`.
|
||||
- A central exception remains:
|
||||
`event/events.rs:Event::StageCompleted` represents `status` as `String`, while
|
||||
execution uses typed `outcome.rs:StageOutcome`.
|
||||
`event/convert.rs:stage_status_from_string` reparses the string and maps every
|
||||
unknown value to a failed outcome.
|
||||
- The common producer
|
||||
`lifecycle/event.rs:EventLifecycle::after_node` converts the typed outcome to
|
||||
a string before the canonical event conversion converts it back.
|
||||
|
||||
Strongest counterevidence: the pipeline phase types, `RunStatus`,
|
||||
`StageOutcome`, `StageId`, and the durable `fabro_types::EventBody` otherwise
|
||||
give the main workflow concepts canonical typed shapes.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because stage completion is on
|
||||
the execution hot path and accepts states the canonical outcome enum rejects.
|
||||
1 does not fit because the canonical types and phase states still give the
|
||||
workflow a coherent vocabulary overall.
|
||||
|
||||
Representative routine change: adding or changing a stage outcome would touch
|
||||
the canonical `lib/foundation/fabro-core/src/outcome.rs:StageOutcome`, string
|
||||
construction in `lifecycle/event.rs:EventLifecycle::after_node`,
|
||||
`event/events.rs:Event::StageCompleted`,
|
||||
`event/convert.rs:stage_status_from_string`, and terminal interpretation in
|
||||
`pipeline/finalize.rs:classify_engine_result`.
|
||||
|
||||
### `duplication-knowledge` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `event/events.rs:Event` defines the internal event shape,
|
||||
`event/names.rs:event_name` independently maps every variant to its external
|
||||
name, `event/stored_fields.rs:stored_event_fields` independently selects
|
||||
envelope fields, and `event/convert.rs:event_body_from_event` constructs the
|
||||
canonical `fabro_types::EventBody`.
|
||||
- `docs/internal/events-strategy.md:Adding A New Event` explicitly requires
|
||||
synchronized edits to the internal event, tracing, external name,
|
||||
`EventBody`, stored fields, conversion, and consumers.
|
||||
- Exhaustive matches make omissions visible, but they do not make one of those
|
||||
mappings authoritative for the others.
|
||||
|
||||
Strongest counterevidence: `event/emitter.rs:Emitter` canonicalizes each emitted
|
||||
event once, all listeners receive the same `RunEvent`, and exhaustive matching
|
||||
plus conversion tests detect much of the synchronization drift.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because adding an event is a
|
||||
routine extension to this component and centrally requires several independent
|
||||
authorities. 1 does not fit because the events strategy clearly identifies all
|
||||
authorities and the compiler/test suite gives a stable update path.
|
||||
|
||||
Representative routine change: adding `run.suspended` would touch
|
||||
`event/events.rs:Event`, `events.rs:Event::trace`,
|
||||
`event/names.rs:event_name`,
|
||||
`lib/foundation/fabro-types/src/run_event/mod.rs:EventBody`,
|
||||
`event/stored_fields.rs:stored_event_fields`,
|
||||
`event/convert.rs:event_body_from_event`, and relevant store/UI consumers.
|
||||
|
||||
## `fabro-http`
|
||||
|
||||
### `ownership-boundaries` — 4, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- The component is one focused source module:
|
||||
`lib/foundation/fabro-http/src/lib.rs` owns the reqwest facade,
|
||||
`ProxyPolicy`, client builders, build errors, and deterministic test clients.
|
||||
- `src/lib.rs:HttpClientBuilder::build` and
|
||||
`BlockingHttpClientBuilder::build` are the construction boundary where the
|
||||
process proxy policy is applied.
|
||||
- `clippy.toml:disallowed-methods` denies direct reqwest client constructors and
|
||||
points callers to this component; `fabro_static::EnvVars` supplies the one
|
||||
environment-variable name without introducing higher-level configuration.
|
||||
|
||||
Strongest counterevidence: the facade deliberately re-exports many reqwest
|
||||
types, and exceptional consumers still carry direct reqwest dependencies for
|
||||
generated clients or incompatible dependency versions.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the normal async,
|
||||
blocking, production, and test construction paths all converge on the same
|
||||
owned policy, with a repository lint reinforcing that boundary.
|
||||
|
||||
### `simplicity` — 4, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `src/lib.rs:define_builder!` expresses the common async/blocking builder once;
|
||||
the four convenience constructors are thin calls to the same builders.
|
||||
- The common flow is direct:
|
||||
`HttpClientBuilder::new` → optional reqwest options →
|
||||
`HttpClientBuilder::build` → `ProxyPolicy::resolve` → reqwest build.
|
||||
- The only async-only option is visibly isolated in
|
||||
`HttpClientBuilder::read_timeout`.
|
||||
|
||||
Strongest counterevidence: the macro hides the two generated impls and every
|
||||
new exposed reqwest option requires another forwarding method.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the macro removes a real
|
||||
parallel API synchronization burden while leaving the common client-building
|
||||
path locally readable; its indirection is not encountered beyond this file.
|
||||
|
||||
### `domain-model` — 4, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `src/lib.rs:ProxyPolicy` has exactly the two supported states,
|
||||
`ProxyPolicy::resolve_with_env_value` makes explicit configuration override
|
||||
environment fallback, and invalid/non-Unicode values become
|
||||
`HttpClientBuildError`.
|
||||
- `src/lib.rs:HttpClientBuildError` distinguishes invalid policy from underlying
|
||||
reqwest construction failure.
|
||||
- `test_http_client` and `blocking_test_http_client` select the typed
|
||||
`ProxyPolicy::Disabled` rather than relying on ambient test environment state.
|
||||
|
||||
Strongest counterevidence: the environment boundary is necessarily stringly,
|
||||
and `ProxyPolicy::parse` accepts case variants before producing the enum.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because invalid strings are
|
||||
rejected at the boundary, precedence is explicit, and all downstream paths use
|
||||
the closed enum.
|
||||
|
||||
### `duplication-knowledge` — 4, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `src/lib.rs:define_builder!` is the single authority for shared async and
|
||||
blocking options and policy application.
|
||||
- `ProxyPolicy::resolve` is the single production authority for explicit/env/
|
||||
default precedence.
|
||||
- `clippy.toml:disallowed-methods` prevents ordinary callers from silently
|
||||
recreating client-construction policy outside the component.
|
||||
|
||||
Strongest counterevidence: async and blocking convenience constructors remain
|
||||
as four syntactically similar functions, and `read_timeout` cannot live in the
|
||||
shared macro surface.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because the remaining repetition
|
||||
does not duplicate a policy or require independent decisions; it exposes
|
||||
parallel entry points backed by the same authority.
|
||||
|
||||
## `fabro-web-app`
|
||||
|
||||
### `ownership-boundaries` — 3, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `apps/fabro-web/app/entry.tsx:AppRuntime` owns browser bootstrap and global
|
||||
runtime providers; `router.tsx:routes` and
|
||||
`install-router.tsx:installRoutes` own the two route graphs.
|
||||
- `app/lib/queries.ts` and `app/lib/mutations.ts` own server reads and writes;
|
||||
`app/lib/api-client.ts` owns transport/error normalization.
|
||||
- `app/hooks/effects.ts` and purpose-named hooks such as
|
||||
`useRunEvents` and `useInstallRestartHealthPolling` contain browser resource
|
||||
lifecycles rather than leaving them in route rendering.
|
||||
- `routes/run-detail.tsx:RunDetail` delegates its header, actions, model,
|
||||
lifecycle-toast, tab-shell, and docked-control responsibilities to the
|
||||
`routes/run-detail/**` modules.
|
||||
|
||||
Strongest counterevidence: two mapped common paths still concentrate several
|
||||
responsibilities:
|
||||
`install-app.tsx:InstallApp` / `useInstallController` contains state,
|
||||
hydration, submission, step routing, payload construction, and rendering, while
|
||||
`routes/run-stages.tsx:RunStages` / `buildStageActivity` contains event
|
||||
interpretation and a large part of stage presentation.
|
||||
|
||||
Why adjacent scores do not fit: 4 does not fit because those central route
|
||||
modules are not merely edge exceptions. 2 does not fit because routes, API
|
||||
access, queries, mutations, browser effects, and build lifecycle still have
|
||||
stable homes and dependencies generally point through those homes.
|
||||
|
||||
### `simplicity` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- The first-run common path is concentrated in
|
||||
`install-app.tsx:installReducer`, `useInstallController`, `InstallApp`,
|
||||
`LlmStep`, `ObjectStoreStep`, `SandboxStep`, `GithubStep`,
|
||||
`buildObjectStorePayload`, and `buildSandboxPayload`.
|
||||
- The run-stage common path combines
|
||||
`routes/run-stages.tsx:selectStageRenderer`,
|
||||
`buildStageActivity`, filtering, debug views, waterfall construction, and
|
||||
`RunStages`.
|
||||
- Cross-tab event sharing introduces a second substantial state machine at
|
||||
`app/lib/cross-tab-sse.ts:CrossTabSseCoordinator`, beneath the already
|
||||
separate shared-event-source logic in `app/lib/sse.ts:subscribeToSharedEventSource`.
|
||||
|
||||
Strongest counterevidence: reducers, discriminated unions, shared query hooks,
|
||||
purpose-named integration hooks, and extracted run-detail modules make many
|
||||
individual flows explicit and testable.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because installation, run-stage
|
||||
inspection, and live refresh are mapped common paths, not optional edge
|
||||
machinery. 1 does not fit because each path still has identifiable entry
|
||||
points, state machines, and tests.
|
||||
|
||||
Representative routine change: adding an installation step for telemetry would
|
||||
touch `install-app.tsx:INSTALL_STEPS`, `InstallState`, `InstallAction`,
|
||||
`installReducer`, `useInstallController`, `InstallApp`, a new step component,
|
||||
review-summary helpers, `install-api.ts`, and the generated install API
|
||||
authority in `docs/public/api-reference/fabro-api.yaml`.
|
||||
|
||||
### `domain-model` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- Positive mechanisms include generated API types throughout the query and
|
||||
route layers, `mode.ts:FabroMode`, and exhaustive display maps such as
|
||||
`lib/sandbox-state.ts:SANDBOX_STATE_DISPLAY`.
|
||||
- The central SSE boundary instead uses
|
||||
`lib/sse.ts:EventPayload`, where `event` is optional and all other fields are
|
||||
unknown, then extends it as
|
||||
`lib/run-events.ts:RunEventPayload` with optional string identifiers and
|
||||
another untyped `properties` map.
|
||||
- `lib/run-events.ts:stageIdFromPayload` accepts `stage_id`, `node_id`, or
|
||||
`properties.node_id` as the stage identity.
|
||||
- `lib/run-sandbox-lifecycle.ts:sandboxLifecycleKind` and `sandboxInstance`
|
||||
cast generated values into compatibility shapes and infer lifecycle from
|
||||
either `kind`, `instance`, or legacy `runtime` / `provider` fields.
|
||||
|
||||
Strongest counterevidence: normal HTTP reads and writes use
|
||||
`@qltysh/fabro-api-client` types, and `Record<GeneratedEnum, ...>` display maps
|
||||
make many API vocabulary changes compile-visible.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because SSE drives normal run
|
||||
refresh and stage views while permitting absent event and identity fields with
|
||||
multiple meanings. 1 does not fit because generated HTTP types and local
|
||||
discriminated unions still provide a coherent model for most operations.
|
||||
|
||||
Representative routine change: making stage identity canonical across live
|
||||
events would touch the wire authority
|
||||
`docs/public/api-reference/fabro-api.yaml`,
|
||||
`lib/sse.ts:EventPayload`, `lib/run-events.ts:RunEventPayload`,
|
||||
`stageIdFromPayload`, and consumers such as
|
||||
`routes/run-stages.tsx:buildStageActivity`.
|
||||
|
||||
### `duplication-knowledge` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `lib/board-events.ts:BOARD_STATUS_EVENTS` independently decides which run
|
||||
events refresh lists, while `lib/run-events.ts:RUN_SUMMARY_EVENTS`,
|
||||
`TERMINAL_EVENTS`, and other sets decide detail invalidations.
|
||||
- `lib/run-phases.ts:deriveRunPhases` independently matches the same lifecycle
|
||||
event vocabulary to build the pre-stage timeline.
|
||||
- `lib/run-events.ts:STAGE_ACTIVITY_EVENT_TYPES` is a positive local authority
|
||||
shared with `routes/run-stages.tsx:buildStageActivity`, but it covers only one
|
||||
slice of the broader manual event policy.
|
||||
|
||||
Strongest counterevidence: list and detail invalidation are genuinely different
|
||||
consumer decisions, `query-keys.ts:queryKeys` centralizes cache identities, and
|
||||
the stage-activity list is deliberately shared with its reducer.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because a normal lifecycle-event
|
||||
extension that affects board and run detail requires synchronized policy edits
|
||||
in separate common subscriptions. 1 does not fit because each consumer's
|
||||
authority is named, localized, and covered by focused tests.
|
||||
|
||||
Representative routine change: adding a `run.suspended` transition that should
|
||||
refresh both list and detail views would touch
|
||||
`board-events.ts:BOARD_STATUS_EVENTS`,
|
||||
`run-events.ts:RUN_SUMMARY_EVENTS` (and possibly `TERMINAL_EVENTS` if its
|
||||
semantics require it), `board-events.test.tsx`, `run-events.test.tsx`, and the
|
||||
upstream event/OpenAPI authorities.
|
||||
|
||||
## `repository-ci`
|
||||
|
||||
### `ownership-boundaries` — 3, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `.github/workflows/rust.yml:jobs` owns Rust formatting, lint, generated-doc,
|
||||
Linux test, twin-E2E, and manual macOS validation.
|
||||
- `.github/workflows/typescript.yml:jobs` owns browser/client typecheck, web
|
||||
tests, and the embedded-SPA release build.
|
||||
- Both workflows set top-level empty permissions and grant only
|
||||
`contents: read` per job; all third-party actions are commit-pinned.
|
||||
- Generated-document and embedded-SPA behavior is delegated to
|
||||
`cargo dev docs check` and `cargo dev build`, leaving those build procedures
|
||||
in `fabro-build-tooling`.
|
||||
|
||||
Strongest counterevidence:
|
||||
`.github/workflows/rust.yml:jobs.clippy.steps[name="Verify legacy auth identity removal"]`
|
||||
contains an authentication-migration vocabulary grep inside the general CI
|
||||
workflow, so an auth-domain transition also has a policy home here.
|
||||
|
||||
Why adjacent scores do not fit: 4 does not fit because that product-domain
|
||||
policy crosses into the CI owner and the trigger boundary has drift discussed
|
||||
under domain model. 2 does not fit because the normal validation jobs and their
|
||||
delegated build/test authorities remain clearly owned and directional.
|
||||
|
||||
Representative routine change: renaming or restoring an authentication identity
|
||||
would require changing the product types and also the legacy-name authority in
|
||||
`.github/workflows/rust.yml:jobs.clippy.steps[name="Verify legacy auth identity removal"]`.
|
||||
|
||||
### `simplicity` — 3, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- Each job is a short checkout/setup/command sequence, and the two workflows
|
||||
split by the repository's Rust and Bun validation surfaces.
|
||||
- `.github/workflows/rust.yml:jobs.test` explains the non-obvious twin-mode
|
||||
expression and why it must not use the strict E2E profile.
|
||||
- `.github/workflows/typescript.yml:jobs.build` delegates the mixed Rust/SPA
|
||||
build to one repository command rather than reproducing its internals.
|
||||
|
||||
Strongest counterevidence: checkout, tool setup, install, permissions, runner,
|
||||
and cache declarations are repeated across every job; the inline legacy-auth
|
||||
shell condition is more elaborate than the surrounding declarative checks.
|
||||
|
||||
Why adjacent scores do not fit: 4 does not fit because routine maintenance must
|
||||
scan repeated job scaffolding and one bespoke shell policy. 2 does not fit
|
||||
because a contributor can still trace each common validation path directly
|
||||
from one named job to one repository command.
|
||||
|
||||
### `domain-model` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- `.github/workflows/rust.yml:on.push.paths` and `on.pull_request.paths` contain
|
||||
`openapi/**`, but that directory does not exist at the assessed revision.
|
||||
- The actual contract authority is
|
||||
`docs/public/api-reference/fabro-api.yaml`, as named by
|
||||
`AGENTS.md:API workflow`,
|
||||
`lib/foundation/fabro-api/build.rs:main`, and
|
||||
`lib/packages/fabro-api-client/package.json:scripts.generate`.
|
||||
- Neither `.github/workflows/rust.yml:on.*.paths` nor
|
||||
`.github/workflows/typescript.yml:on.*.paths` names that actual contract
|
||||
path, even though both generated clients depend on it.
|
||||
|
||||
Strongest counterevidence: job names, Rust versus TypeScript scope, twin versus
|
||||
live test meaning, and toolchain versions are otherwise explicit; the commands
|
||||
the jobs run correspond to checked-in project commands.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because an ordinary edit to the
|
||||
HTTP source of truth falls outside both central validation trigger models. 1
|
||||
does not fit because the workflows still have a stable and mostly accurate
|
||||
vocabulary for jobs, branches, tools, and commands.
|
||||
|
||||
Representative routine change: editing only
|
||||
`docs/public/api-reference/fabro-api.yaml` should exercise Rust generation and
|
||||
TypeScript typecheck/build, but its meaning would have to be repaired in
|
||||
`.github/workflows/rust.yml:on.push.paths`,
|
||||
`.github/workflows/rust.yml:on.pull_request.paths`,
|
||||
`.github/workflows/typescript.yml:on.push.paths`, and
|
||||
`.github/workflows/typescript.yml:on.pull_request.paths`.
|
||||
|
||||
### `duplication-knowledge` — 2, High confidence
|
||||
|
||||
Evidence:
|
||||
|
||||
- Each workflow repeats its path set under both `on.push.paths` and
|
||||
`on.pull_request.paths`; a new CI-relevant repository path has two authorities
|
||||
per language.
|
||||
- `.github/workflows/rust.yml:jobs.fmt`, `jobs.clippy`,
|
||||
`jobs.generated-docs`, `jobs.test`, and `jobs.test-macos` independently repeat
|
||||
checkout pins, credential policy, runner/toolchain setup, and often cache
|
||||
setup.
|
||||
- `.github/workflows/typescript.yml:jobs.typecheck`, `jobs.test`, and
|
||||
`jobs.build` independently repeat checkout, Bun setup, and frozen install.
|
||||
|
||||
Strongest counterevidence: independent jobs preserve failure isolation and
|
||||
least-privilege permissions, while the substantive docs/build procedures are
|
||||
delegated to repository commands rather than copied into YAML.
|
||||
|
||||
Why adjacent scores do not fit: 3 does not fit because path and tool-bootstrap
|
||||
knowledge is repeated on every routine trigger or tool-version update. 1 does
|
||||
not fit because all copies remain confined to two small workflow files and the
|
||||
substantive check authorities are still identifiable.
|
||||
|
||||
Representative routine change: adding a new Rust-relevant `tools/**` tree would
|
||||
require synchronized edits to
|
||||
`.github/workflows/rust.yml:on.push.paths` and
|
||||
`on.pull_request.paths`; updating the Rust checkout/toolchain baseline requires
|
||||
reviewing the pins in every `rust.yml:jobs.*.steps` copy.
|
||||
|
||||
## Lens-Boundary Notes
|
||||
|
||||
- The repeated startup carriers in `fabro-workflow` could be labeled ownership
|
||||
or simplicity. I counted their unclear amount of machinery under simplicity;
|
||||
ownership was judged from whether each phase, resource lifecycle, and
|
||||
dependency direction has a named home.
|
||||
- The workflow's internal `Event` and durable `EventBody` have documented
|
||||
distinct meanings. I therefore counted the many synchronized mappings under
|
||||
duplication, not domain model. The separate `StageCompleted.status: String`
|
||||
finding drives the domain-model score because it admits invalid states.
|
||||
- Large web route files are not ownership findings merely because they are
|
||||
large. They lower simplicity where common behavior is difficult to trace; the
|
||||
ownership score moves only where several responsibilities remain concentrated
|
||||
despite otherwise clear route/data/effect homes.
|
||||
- In the web event layer, optional/untyped payload shape is a domain-model
|
||||
finding. Repeating lifecycle-event policy across list, detail, and phase
|
||||
consumers is a duplication finding.
|
||||
- In CI, the stale `openapi/**` referent is a domain-model finding because the
|
||||
path no longer means the API authority it purports to cover. Repeating trigger
|
||||
and setup lists is separately a duplication finding.
|
||||
- The `fabro-http` builder macro adds local indirection, but its primary effect
|
||||
is to make shared async/blocking policy authoritative. I treated it as a
|
||||
positive duplication mechanism rather than simplicity friction.
|
||||
|
|
@ -1,424 +0,0 @@
|
|||
# Chisel calibration validation 1
|
||||
|
||||
Revision: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
This is an independent reading of only the requested assignments. Scores use the
|
||||
mapped purposes and the final calibration rubric. Boundary evidence is included
|
||||
where it establishes whether a scoped mechanism is on a production common path.
|
||||
|
||||
## Summary
|
||||
|
||||
| Component | Lens | Score | Evidence confidence |
|
||||
|---|---|---:|---|
|
||||
| `fabro-workflow` | `ownership-boundaries` | 2 | High |
|
||||
| `fabro-workflow` | `domain-model` | 2 | High |
|
||||
| `fabro-http` | `domain-model` | 4 | High |
|
||||
| `fabro-http` | `duplication-knowledge` | 4 | High |
|
||||
| `fabro-web-app` | `ownership-boundaries` | 4 | Medium |
|
||||
| `repository-ci` | `ownership-boundaries` | 4 | Medium |
|
||||
| `repository-ci` | `domain-model` | 2 | High |
|
||||
| `fabro-checkpoint` | `ownership-boundaries` | 2 | High |
|
||||
| `fabro-checkpoint` | `simplicity` | 4 | Medium |
|
||||
| `fabro-checkpoint` | `domain-model` | 2 | High |
|
||||
| `fabro-checkpoint` | `duplication-knowledge` | 3 | Medium |
|
||||
|
||||
## `fabro-workflow`
|
||||
|
||||
### `ownership-boundaries`: 2
|
||||
|
||||
- **Evidence:** `lifecycle/mod.rs:53-80` presents `WorkflowLifecycle` as the
|
||||
callback owner, and `lifecycle/git.rs:77-93, 397-401` gives `GitLifecycle`
|
||||
its own `last_git_sha` state. The normal `RunSession::run` path nevertheless
|
||||
creates a second `last_git_sha`, reconstructs it by listening to emitted
|
||||
checkpoint, terminal, and Git events, then passes it back into finalization
|
||||
(`operations/start.rs:821-856, 914-923`). Terminal responsibility is split
|
||||
again: engine outcomes become terminal events in
|
||||
`pipeline/finalize.rs:524-596`, while bootstrap, initialization, and
|
||||
finalization errors become `run.failed` through the outer operation in
|
||||
`operations/start.rs:176-285, 288-346`. These crossings occur on the normal
|
||||
run and error paths, not at an optional edge.
|
||||
- **Strongest counterevidence:** `operations/start.rs:796-953` is a recognizable
|
||||
top-level owner for the initialize → execute → finalize → pull-request
|
||||
sequence, and `WorkflowLifecycle` explicitly orders focused delegates for
|
||||
each executor callback (`lifecycle/mod.rs:221-469`).
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the caller always
|
||||
mirrors and resupplies Git identity on the common run path, and terminal
|
||||
failure handling routinely selects between two owners. 1 does not fit because
|
||||
both the executor callback owner and the outer run-session owner are stable
|
||||
and traceable; the problem is their competition, not the absence of owners.
|
||||
- **Rule discrimination:** Decision rule 2 is decisive for the mirrored
|
||||
`last_git_sha`. The phrase “complete lifecycle” is otherwise ambiguous about
|
||||
whether an executor lifecycle may end before durability finalization; the
|
||||
explicit state round-trip makes the result 2 without relying on that
|
||||
ambiguity.
|
||||
|
||||
### `domain-model`: 2
|
||||
|
||||
- **Evidence:** The internal durable event shape stores
|
||||
`Event::StageCompleted.status` as `String`
|
||||
(`event/events.rs:264-272`). Both synthetic terminal-stage completion and
|
||||
ordinary successful stage completion stringify the canonical
|
||||
`StageOutcome` (`lifecycle/event.rs:215-240, 355-366`), after which the
|
||||
mandatory event conversion reparses it and converts an unknown value to
|
||||
`Failed` (`event/convert.rs:14-24, 309-333`). This typed → string → typed path
|
||||
is part of every successful stage-completion event.
|
||||
- **Strongest counterevidence:** `fabro_types::StageOutcome` is a stable
|
||||
canonical type, most event fields are typed, and the fallback prevents an
|
||||
unrecognized string from escaping into the stored projection.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because common production
|
||||
completion events depend on the invalid intermediate rather than using it as
|
||||
a compatibility edge. 1 does not fit because the canonical status meaning is
|
||||
clear and the conversion point is explicit.
|
||||
- **Rule discrimination:** Decision rule 4 and the rubric's repository example
|
||||
make this assignment unambiguous.
|
||||
|
||||
## `fabro-http`
|
||||
|
||||
### `domain-model`: 4
|
||||
|
||||
- **Evidence:** `ProxyPolicy` is a closed `System | Disabled` vocabulary;
|
||||
parsing rejects every other boundary value
|
||||
(`src/lib.rs:23-35`). Resolution gives explicit configuration precedence over
|
||||
the environment, defaults absence to `System`, and rejects non-Unicode input
|
||||
(`src/lib.rs:38-60`). Every async and blocking builder reaches that resolver
|
||||
before construction (`src/lib.rs:160-166, 172-193`), while the deterministic
|
||||
test helpers select the typed `Disabled` value
|
||||
(`src/lib.rs:195-213`).
|
||||
- **Strongest counterevidence:** The builder also exposes raw `no_proxy()` and
|
||||
`proxy()` operations (`src/lib.rs:96-106`), so callers can combine an
|
||||
underlying reqwest choice with `ProxyPolicy`; Unix-socket production callers
|
||||
do use `no_proxy()` (`lib/foundation/fabro-client/src/client.rs:2123-2134`).
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the common
|
||||
policy-controlled constructors never interpret an invalid policy: they
|
||||
return `HttpClientBuildError`. The raw builder operations represent valid
|
||||
per-client transport configuration, not a second string vocabulary. 2 and 1
|
||||
do not fit because no common-path conversion or unstable meaning is present.
|
||||
- **Rule discrimination:** Decision rule 4 is potentially non-discriminating
|
||||
if every forwarded low-level builder method is called an “escape hatch.”
|
||||
Here `no_proxy()` carries no invalid intermediate and does not weaken
|
||||
`ProxyPolicy::resolve`, so treating it as ordinary typed builder
|
||||
configuration preserves the rule's distinction.
|
||||
|
||||
### `duplication-knowledge`: 4
|
||||
|
||||
- **Evidence:** `define_builder!` holds the complete shared async/blocking
|
||||
builder policy once, including proxy resolution and construction
|
||||
(`src/lib.rs:72-170`), and is instantiated for the two reqwest client kinds
|
||||
(`src/lib.rs:172-193`). The four convenience constructors delegate to those
|
||||
builders rather than reproducing policy (`src/lib.rs:195-213`).
|
||||
- **Strongest counterevidence:** The generated facade necessarily lists each
|
||||
forwarded reqwest method, and the test and non-test convenience constructors
|
||||
have similar bodies.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the similar
|
||||
forwarding and wrappers are syntax over one policy authority, not separately
|
||||
maintained transport knowledge. 2 does not fit because a proxy-policy change
|
||||
is made once in the macro/resolver, not synchronized across async and
|
||||
blocking implementations. 1 does not fit because the authority is explicit.
|
||||
- **Rule discrimination:** The rubric's `define_builder!` example directly
|
||||
distinguishes shared macro expansion from semantic duplication; no material
|
||||
ambiguity remains.
|
||||
|
||||
## `fabro-web-app`
|
||||
|
||||
### `ownership-boundaries`: 4
|
||||
|
||||
- **Evidence:** `entry.tsx:17-49` owns browser startup, chooses the normal or
|
||||
installation route graph once, and installs shared SWR runtime policy.
|
||||
`router.tsx:97-184` owns normal route composition. Shared transport and error
|
||||
handling live in `lib/api-client.ts:64-160, 213-310`; shared reads such as
|
||||
`useRun` and `useRunState` live in `lib/queries.ts:182-193`; run mutations and
|
||||
their cache lifecycle live in `lib/mutations.ts:65-132`; and run-scoped SSE
|
||||
subscription, invalidation, resync, and cleanup live in
|
||||
`lib/run-events.ts:129-309`. The representative busy route composes those
|
||||
owners rather than reimplementing them
|
||||
(`routes/run-detail.tsx:79-145, 313-379`).
|
||||
- **Strongest counterevidence:** Some route-local CRUD actions call the shared
|
||||
API facade directly, and `run-detail.tsx:193-205` coordinates delete state,
|
||||
cache invalidation, toast, and navigation in the route.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the counterevidence
|
||||
is local page UX ownership; it does not split a shared transport, read,
|
||||
mutation, or subscription lifecycle. 2 does not fit because routine run-page
|
||||
changes use the established owners rather than coordinating competing ones.
|
||||
1 does not fit because startup, routing, transport, caching, and streaming
|
||||
each have readily identifiable homes.
|
||||
- **Rule discrimination:** “One owner” is mildly non-discriminating for a large
|
||||
browser application unless responsibility is evaluated at lifecycle
|
||||
granularity. Using the rubric's `apiData`/`useRun` example, route composition
|
||||
is not itself a second owner. Confidence is Medium because this is the
|
||||
largest sampled scope.
|
||||
|
||||
## `repository-ci`
|
||||
|
||||
### `ownership-boundaries`: 4
|
||||
|
||||
- **Evidence:** `rust.yml:3-40` owns Rust branch/PR/manual triggers and
|
||||
concurrency, while its jobs contain format, lint, generated-doc, Linux test,
|
||||
twin E2E, and manual macOS lifecycles (`rust.yml:48-147`).
|
||||
`typescript.yml:3-34` owns the corresponding TypeScript triggers and
|
||||
concurrency, and its jobs contain typecheck, test, and integrated SPA/Rust
|
||||
build lifecycles (`typescript.yml:36-77`). Delegation to `cargo dev` is the
|
||||
mapped dependency on build tooling, not reverse ownership.
|
||||
- **Strongest counterevidence:** The TypeScript build invokes a Rust build
|
||||
(`typescript.yml:75-77`), and invalid path selectors mean some intended
|
||||
changes do not start the declared workflows.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the cross-language
|
||||
build is the intentional embedded-SPA integration boundary, not friction, and
|
||||
selector validity is classified under domain model by decision rule 6. 2
|
||||
does not fit because no routine job requires coordination between competing
|
||||
CI owners. 1 does not fit because the two language validation homes and their
|
||||
dependency direction are explicit.
|
||||
- **Rule discrimination:** The score-4 phrase “complete lifecycle” is
|
||||
non-discriminating for hosted CI if it is read to require repository
|
||||
ownership of GitHub's runner lifecycle. This score treats the checked-in
|
||||
trigger/job lifecycle as the mapped responsibility and the platform as an
|
||||
intended boundary.
|
||||
|
||||
### `domain-model`: 2
|
||||
|
||||
- **Evidence:** Both Rust trigger selectors name `openapi/**`
|
||||
(`rust.yml:18,34`), but that revision has no tracked target there; the actual
|
||||
API contract is `docs/public/api-reference/fabro-api.yaml`, which the
|
||||
TypeScript client generation command consumes
|
||||
(`lib/packages/fabro-api-client/package.json:7`). The real contract path is
|
||||
absent from both workflow path filters. In addition, all three zizmor
|
||||
`stale-action-refs` identifiers target `rust.yml:37`, `:49`, and `:62`
|
||||
(`zizmor.yml:1-6`), which are respectively the end of trigger setup, the
|
||||
`fmt` job key, and a `run` command—not action references at this revision.
|
||||
These invalid identifiers sit directly in trigger and static-validation
|
||||
configuration.
|
||||
- **Strongest counterevidence:** The workflow/job vocabulary itself is stable,
|
||||
all jobs and action pins have clear meanings, and changes under the large
|
||||
valid Rust and TypeScript source selectors do trigger their expected suites.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the dead OpenAPI
|
||||
selector is present in both routine branch and PR paths, while every scoped
|
||||
zizmor exception lacks a current target. 1 does not fit because the overall
|
||||
workflow and job model remains stable; the defect is a recurring set of
|
||||
invalid identifiers.
|
||||
- **Rule discrimination:** Decision rule 6 is decisive that these are domain
|
||||
pressure rather than ownership or duplication. It does not state when one or
|
||||
more dead selectors move from 3 to 2; centrality in both trigger modes and
|
||||
total staleness of the scoped zizmor selectors supply that discrimination
|
||||
here.
|
||||
|
||||
## Control: `fabro-checkpoint`
|
||||
|
||||
### `ownership-boundaries`: 2
|
||||
|
||||
- **Evidence:** The mapped component claims metadata branches, but its
|
||||
production boundary consumer owns the metadata writer's branch, parent OID,
|
||||
discovery, remote, and push lifecycle
|
||||
(`fabro-workflow/src/run_metadata.rs:272-282, 313-439`). On every snapshot,
|
||||
that caller validates entries, individually drives `Store` through blobs,
|
||||
tree, commit, and ref update, and retains the parent identity for the next
|
||||
write (`run_metadata.rs:313-350`). `BranchStore` provides a contained
|
||||
read-modify-write owner (`branch.rs:17-24, 42-81`) but has no production
|
||||
caller at this revision.
|
||||
- **Strongest counterevidence:** The dependency direction is intended
|
||||
(`fabro-workflow` depends on `fabro-checkpoint`), and the low-level `Store`
|
||||
consistently owns Git object/ref operations (`git.rs:101-227`).
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because the lifecycle
|
||||
crossing occurs on every metadata snapshot, not in an isolated adapter. 1
|
||||
does not fit because low-level Git ownership and the caller's higher-level
|
||||
writer ownership are both stable; the problem is the split between them.
|
||||
- **Rule discrimination:** Decision rule 2 applies because the caller retains
|
||||
and resupplies branch/parent identity to complete successive writes. The
|
||||
rubric does not say whether a deliberately low-level `Store` narrows the
|
||||
mapped ownership claim; the explicit mapped claim to metadata branches makes
|
||||
this crossing discriminating.
|
||||
|
||||
### `simplicity`: 4
|
||||
|
||||
- **Evidence:** The production `Store` has direct blob, tree, commit, and ref
|
||||
operations (`git.rs:123-226`). Tree conversion is a single read recursion and
|
||||
a single bottom-up write path (`git.rs:229-310`). At the higher level,
|
||||
`BranchStore::write_with` is a linear resolve → read → mutate → write → commit
|
||||
→ update sequence (`branch.rs:56-81`), and entry operations are small
|
||||
delegates (`branch.rs:84-117`). Necessary Git layering is visible rather than
|
||||
hidden behind competing configuration machinery.
|
||||
- **Strongest counterevidence:** There are two entry levels, and the production
|
||||
metadata writer uses the lower-level `Store` instead of `BranchStore`.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because choosing the
|
||||
low-level entry is required for replace-whole-tree and remote-parent behavior,
|
||||
not unnecessary indirection. 2 does not fit because the scoped common
|
||||
operations do not navigate competing implementations or configuration. 1
|
||||
does not fit because both paths are directly traceable.
|
||||
- **Rule discrimination:** Ownership rule 2 could otherwise cause the
|
||||
out-of-scope metadata writer's machinery to be counted again as simplicity
|
||||
friction. The lens exclusions make that non-discriminating evidence here;
|
||||
within the scoped implementation, the production primitives are direct.
|
||||
|
||||
### `domain-model`: 2
|
||||
|
||||
- **Evidence:** `TreeEntries::set` accepts any `String` path without validation
|
||||
(`git.rs:46-60`), and `write_tree` later interprets it by splitting on `/`
|
||||
(`git.rs:149-153, 270-293`). The common metadata caller must therefore define
|
||||
and apply `validate_metadata_path` outside this component before every
|
||||
`TreeEntries` construction
|
||||
(`fabro-workflow/src/run_metadata.rs:313-332, 471-480`). The component also
|
||||
maps every unrecognized Git file mode to `Blob`
|
||||
(`git.rs:21-35, 229-250`) rather than rejecting an unsupported state.
|
||||
- **Strongest counterevidence:** `FileMode` is otherwise a closed enum, Git
|
||||
object IDs use `git2::Oid`, and the current production metadata caller does
|
||||
reject empty, absolute, dot-segment, and empty-segment paths before writing.
|
||||
- **Why adjacent scores do not fit:** 3 does not fit because external path
|
||||
validation is mandatory on every common metadata snapshot and the canonical
|
||||
`TreeEntries` shape can always hold an invalid path. 1 does not fit because
|
||||
the intended path and mode meanings remain clear and production does have a
|
||||
validation step.
|
||||
- **Rule discrimination:** Decision rule 4 clearly places the caller-validated
|
||||
`TreeEntries` intermediate at 2. Whether unknown Git modes are a compatibility
|
||||
escape hatch is ambiguous by itself, but it is not needed to choose the
|
||||
score.
|
||||
|
||||
### `duplication-knowledge`: 3
|
||||
|
||||
- **Evidence:** Branch-to-full-ref formatting is repeated in `Store::update_ref`,
|
||||
`resolve_ref`, and `delete_ref` (`git.rs:182-225`), and the boundary metadata
|
||||
writer has another `full_ref` transformation
|
||||
(`fabro-workflow/src/run_metadata.rs:364-439`). `BranchStore::read_entry`,
|
||||
`read_entries`, `list_entries`, and `tip_tree` also repeat parts of branch-tip
|
||||
resolution (`branch.rs:119-184`). These repetitions are local and stable, but
|
||||
there is no single helper enforcing them.
|
||||
- **Strongest counterevidence:** Mutation sequencing is authoritative in
|
||||
`BranchStore::write_with` (`branch.rs:56-81`), metadata branch naming has one
|
||||
`META_BRANCH_PREFIX` constant (`lib.rs:7`), Git-author defaults have one
|
||||
`Default` implementation (`author.rs:13-20`), and the repeated ref syntax is a
|
||||
fixed Git protocol form rather than frequently changing Fabro policy.
|
||||
- **Why adjacent scores do not fit:** 4 does not fit because ref normalization
|
||||
and branch-tip traversal are still represented in several places. 2 does not
|
||||
fit because there is no direct evidence that a routine checkpoint change
|
||||
must alter those stable protocol transformations in sync; the repetitions are
|
||||
isolated implementation knowledge. 1 does not fit because each policy has an
|
||||
identifiable local authority even where a helper is absent.
|
||||
- **Rule discrimination:** Decision rule 5 leaves a real 3-versus-4 ambiguity:
|
||||
repeated `refs/heads/` can be classified as harmless protocol syntax. I score
|
||||
3 because the same branch-to-ref transformation crosses the component
|
||||
boundary, but do not score 2 without evidence of routine synchronization.
|
||||
|
||||
## Overall rubric observations
|
||||
|
||||
- Decision rule 2 successfully distinguishes focused delegates from a lifecycle
|
||||
that sends identity back through an event/caller round trip.
|
||||
- Decision rule 6 prevents dead CI selectors from being double-counted as
|
||||
ownership defects, but needs centrality/recurrence evidence to distinguish 2
|
||||
from 3.
|
||||
- “One owner” and “complete lifecycle” need responsibility-sized interpretation
|
||||
for route trees and hosted CI; otherwise healthy composition cannot reach 4.
|
||||
- Decision rule 5 correctly keeps stable protocol repetition from automatically
|
||||
becoming score 2, but the line between harmless syntax and a repeated
|
||||
transformation remains the least discriminating part of this sample.
|
||||
|
||||
## Round 2 revalidation
|
||||
|
||||
| Component | Lens | Score | Confidence |
|
||||
|---|---|---:|---|
|
||||
| `fabro-http` | `duplication-knowledge` | 3 | Medium |
|
||||
| `repository-ci` | `ownership-boundaries` | 2 | High |
|
||||
| `fabro-checkpoint` | `ownership-boundaries` | 2 | High |
|
||||
| `fabro-checkpoint` | `simplicity` | 3 | High |
|
||||
| `fabro-checkpoint` | `domain-model` | 2 | High |
|
||||
| `fabro-checkpoint` | `duplication-knowledge` | 3 | Medium |
|
||||
|
||||
### `fabro-http` × `duplication-knowledge`: 3
|
||||
|
||||
- **Decisive evidence:** Proxy disabling has two concrete semantic
|
||||
representations in the mapped entry layer: callers may set
|
||||
`ProxyPolicy::Disabled` (`src/lib.rs:23-27, 90-94`), or call the separately
|
||||
exposed `no_proxy()` builder operation (`src/lib.rs:96-100`). The former is
|
||||
interpreted by calling the same underlying `inner.no_proxy()` transformation
|
||||
during `build` (`src/lib.rs:160-165`). Both forms are used on direct boundary
|
||||
paths: test constructors select the enum (`src/lib.rs:199-213`), while the
|
||||
Unix-socket transport selects `no_proxy()`
|
||||
(`lib/foundation/fabro-client/src/client.rs:2123-2134`).
|
||||
- **Adjacent scores:** 4 does not fit revised rule 6 because there is a concrete
|
||||
second representation of the same no-proxy decision. 2 does not fit because
|
||||
an ordinary proxy-policy extension does not require manually synchronizing
|
||||
those call sites; async and blocking policy construction still share the one
|
||||
`define_builder!` mechanism (`src/lib.rs:72-193`). 1 does not fit because the
|
||||
resolver remains a stable authority.
|
||||
- **Remaining ambiguity:** `no_proxy()` can reasonably be viewed as a lower-level
|
||||
reqwest operation rather than a second Fabro policy. Revised rule 6 makes 3
|
||||
the conservative result because `ProxyPolicy::Disabled` is implemented by
|
||||
that exact operation, but this classification keeps confidence at Medium.
|
||||
|
||||
### `repository-ci` × `ownership-boundaries`: 2
|
||||
|
||||
- **Decisive evidence:** The Rust check explicitly scans
|
||||
`docs/public/api-reference/fabro-api.yaml` in its legacy-identity guard
|
||||
(`rust.yml:80-92`), but neither push nor pull-request triggers include that
|
||||
real path (`rust.yml:3-35`); they include the nonexistent `openapi/**`
|
||||
selector instead (`rust.yml:18,34`). A routine API-contract change can
|
||||
therefore change a scanned target without starting its owning check.
|
||||
- **Adjacent scores:** 3 does not fit because the non-triggering target is on a
|
||||
routine branch/PR check path, not an isolated manual edge. 1 does not fit
|
||||
because the workflow, jobs, and intended trigger owner remain identifiable.
|
||||
4 is directly excluded by revised rule 3's trigger-coverage requirement.
|
||||
- **Remaining ambiguity:** `typescript.yml:76` also invokes a Rust build from a
|
||||
narrower trigger set, but that broader interpretation is unnecessary; the
|
||||
explicitly scanned, non-triggering API contract is sufficient for 2.
|
||||
|
||||
### `fabro-checkpoint` × `ownership-boundaries`: 2
|
||||
|
||||
- **Decisive evidence:** The mapped owner exposes low-level `Store` primitives,
|
||||
while the routine metadata caller reconstructs the mapped branch lifecycle:
|
||||
`RunMetadataWriter` owns branch, parent, and discovery state
|
||||
(`fabro-workflow/src/run_metadata.rs:272-282`), then validates entries and
|
||||
sequences blob, tree, commit, ref update, and retained parent state on every
|
||||
snapshot (`run_metadata.rs:313-350`). No production boundary uses the
|
||||
component's higher-level `BranchStore`.
|
||||
- **Adjacent scores:** 3 does not fit because every metadata snapshot traverses
|
||||
the split. 1 does not fit because the low-level Git owner and caller-side
|
||||
lifecycle are both stable. 4 is directly excluded by revised rule 2: the
|
||||
routine caller reconstructs a lifecycle the map assigns to this component.
|
||||
- **Remaining ambiguity:** A narrower map that assigned only Git object
|
||||
primitives to `fabro-checkpoint` could make this healthy delegation, but the
|
||||
actual map explicitly assigns metadata branches and checkpoint commits.
|
||||
|
||||
### `fabro-checkpoint` × `simplicity`: 3
|
||||
|
||||
- **Decisive evidence:** `Cargo.toml:16-24` carries `fabro-store` as a production
|
||||
dependency, but scoped production code does not use it. The component also
|
||||
exposes `BranchStore` as a parallel entry layer (`branch.rs:17-24`) that has
|
||||
no production caller at this revision; the common metadata path uses `Store`
|
||||
directly. The active `Store` path itself remains linear and direct
|
||||
(`git.rs:123-226`).
|
||||
- **Adjacent scores:** 4 is explicitly capped at 3 by revised rule 4 for the
|
||||
unused production dependency and parallel unused entry layer. 2 does not fit
|
||||
because routine production work does not repeatedly navigate those unused
|
||||
elements; its `Store` path is direct. 1 does not fit because a stable common
|
||||
path is easy to trace.
|
||||
- **Remaining ambiguity:** Either isolated fact independently supplies the
|
||||
revised rule's cap, so there is no material score ambiguity.
|
||||
|
||||
### `fabro-checkpoint` × `domain-model`: 2
|
||||
|
||||
- **Decisive evidence:** `TreeEntries::set` accepts arbitrary string paths
|
||||
(`git.rs:46-60`) before `write_tree` interprets them structurally
|
||||
(`git.rs:149-153, 270-293`). Every common metadata snapshot must validate
|
||||
those paths outside the mapped entry before constructing `TreeEntries`
|
||||
(`fabro-workflow/src/run_metadata.rs:313-332, 471-480`).
|
||||
- **Adjacent scores:** 3 does not fit revised rule 5 because caller validation
|
||||
does not isolate an invalid-capable mapped entry used on every snapshot. 1
|
||||
does not fit because path meaning is stable and the caller does enforce it.
|
||||
4 is excluded because the canonical entry type itself admits invalid states.
|
||||
- **Remaining ambiguity:** Unknown Git modes also collapse to `Blob`
|
||||
(`git.rs:21-35`), but that compatibility question is not needed for the
|
||||
score; the routine path shape is decisive.
|
||||
|
||||
### `fabro-checkpoint` × `duplication-knowledge`: 3
|
||||
|
||||
- **Decisive evidence:** The short branch name is converted to
|
||||
`refs/heads/{branch}` independently in `Store::update_ref`, `resolve_ref`, and
|
||||
`delete_ref` (`git.rs:182-225`), while the routine boundary writer carries a
|
||||
second `full_ref` conversion
|
||||
(`fabro-workflow/src/run_metadata.rs:364-439`). These are concrete repeated
|
||||
representations, but of stable Git protocol knowledge.
|
||||
- **Adjacent scores:** 4 does not fit revised rule 6 because the
|
||||
branch-to-full-ref transformation has a concrete second representation. 2
|
||||
does not fit because no ordinary mapped change is shown to require
|
||||
synchronizing the stable Git namespace transformations; repeated call sites
|
||||
alone are insufficient. 1 does not fit because the transformation and its
|
||||
local authorities are clear.
|
||||
- **Remaining ambiguity:** The literal can also be classified as harmless Git
|
||||
syntax, which the lens excludes. Its repetition across the mapped boundary
|
||||
supports 3, but the harmless-syntax distinction keeps confidence at Medium.
|
||||
|
|
@ -1,450 +0,0 @@
|
|||
# Chisel calibration validation 2
|
||||
|
||||
Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`
|
||||
|
||||
This is an independent reading of the final rubric. I did not seek or infer
|
||||
earlier scores.
|
||||
|
||||
## Scores
|
||||
|
||||
| Component | Lens | Score | Evidence confidence |
|
||||
|---|---|---:|---|
|
||||
| `fabro-workflow` | `ownership-boundaries` | 2 | High |
|
||||
| `fabro-workflow` | `domain-model` | 2 | High |
|
||||
| `fabro-http` | `domain-model` | 4 | High |
|
||||
| `fabro-http` | `duplication-knowledge` | 4 | Medium |
|
||||
| `fabro-web-app` | `ownership-boundaries` | 4 | Medium |
|
||||
| `repository-ci` | `ownership-boundaries` | 2 | High |
|
||||
| `repository-ci` | `domain-model` | 2 | High |
|
||||
| `fabro-checkpoint` | `ownership-boundaries` | 4 | Medium |
|
||||
| `fabro-checkpoint` | `simplicity` | 4 | Medium |
|
||||
| `fabro-checkpoint` | `domain-model` | 3 | Medium |
|
||||
| `fabro-checkpoint` | `duplication-knowledge` | 2 | Medium |
|
||||
|
||||
## Disputed assignments
|
||||
|
||||
### `fabro-workflow` × `ownership-boundaries` — 2
|
||||
|
||||
**Direct evidence.** `WorkflowLifecycle` is a real central owner for engine
|
||||
callback ordering: it contains the event, hook, fidelity, status, circuit
|
||||
breaker, git, and artifact delegates and orders them in every callback
|
||||
(`src/lifecycle/mod.rs:53-80`, `223-470`). The full run lifecycle nevertheless
|
||||
crosses that owner on normal paths. `WorkflowLifecycle::on_run_end` only runs
|
||||
the hook (`src/lifecycle/mod.rs:467-469`); `pipeline::finalize` separately builds
|
||||
and emits the terminal event and stops the sandbox
|
||||
(`src/pipeline/finalize.rs:524-635`); `RunSession::run` separately owns
|
||||
initialize/execute/finalize, progress flushing, steering drain, and a second
|
||||
sandbox cleanup guard (`src/operations/start.rs:796-953`); detached bootstrap
|
||||
and completion guards own additional terminal-failure paths
|
||||
(`src/operations/start.rs:956-1139`). A routine change to terminal ordering or
|
||||
cleanup must account for these owners.
|
||||
|
||||
**Strongest counterevidence.** The split is deliberate. In particular,
|
||||
`finalize` documents why the terminal event must follow metadata flushing, and
|
||||
the scope guards cover panic/interruption paths that an async lifecycle callback
|
||||
cannot reliably cover.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because the split is on
|
||||
every ordinary terminal path, not an isolated compatibility path. Score 1 does
|
||||
not fit because the owners and dependency direction are identifiable:
|
||||
`RunSession` is the outer orchestrator and `WorkflowLifecycle` consistently owns
|
||||
engine callbacks.
|
||||
|
||||
**Rule discrimination.** Decision rule 2 is useful here, but “complete routine
|
||||
lifecycle operations” must include terminal emission and resource cleanup, not
|
||||
only engine callbacks. Without that reading, the positive orchestrator example
|
||||
could make 3 and 2 hard to distinguish.
|
||||
|
||||
### `fabro-workflow` × `domain-model` — 2
|
||||
|
||||
**Direct evidence.** The canonical execution result is the typed
|
||||
`StageOutcome`, re-exported in `src/outcome.rs:1-12`. The common stage-completion
|
||||
event instead stores `status: String` (`src/event/events.rs:264-293`).
|
||||
`EventLifecycle::after_node` converts the typed value to a string for every
|
||||
successful completion (`src/lifecycle/event.rs:319-378`), and
|
||||
`event_body_from_event` reparses it into `StageOutcome`
|
||||
(`src/event/convert.rs:309-348`). Unknown strings are silently reinterpreted as
|
||||
a non-retryable failure (`src/event/convert.rs:14-24`). The same string
|
||||
intermediate is used for synthetic terminal stages
|
||||
(`src/lifecycle/event.rs:183-242`).
|
||||
|
||||
**Strongest counterevidence.** Durable `fabro_types::StageCompletedProps` is
|
||||
typed, and ordinary producers derive the string from a typed value rather than
|
||||
accepting arbitrary user text.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because the conversion
|
||||
and invalid intermediate occur on the common event path for every completed
|
||||
stage. Score 1 does not fit because `StageOutcome` supplies a stable canonical
|
||||
meaning and most execution code uses it directly.
|
||||
|
||||
**Rule discrimination.** Decision rule 4 and the repository example are
|
||||
decisive. The rule would be non-discriminating if “compatibility escape hatch”
|
||||
were allowed to describe the central `Event` type merely because the durable
|
||||
type is healthier.
|
||||
|
||||
### `fabro-http` × `domain-model` — 4
|
||||
|
||||
**Direct evidence.** `ProxyPolicy` is a closed two-variant vocabulary
|
||||
(`src/lib.rs:23-27`). The environment boundary parses case-insensitively and
|
||||
rejects every other value with a typed `HttpClientBuildError`
|
||||
(`src/lib.rs:29-70`). Explicit policy has a documented precedence in
|
||||
`resolve_with_env_value`, and both async and blocking builders resolve the
|
||||
policy immediately before applying it (`src/lib.rs:38-59`, `160-166`,
|
||||
`172-193`). The common production and test constructors all pass through those
|
||||
builders (`src/lib.rs:195-213`).
|
||||
|
||||
**Strongest counterevidence.** The builders also expose the lower-level
|
||||
`no_proxy()` and `proxy()` methods (`src/lib.rs:96-106`), so callers can express
|
||||
transport configuration outside the high-level enum.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because the lower-level
|
||||
methods are intentional reqwest-facade escape hatches; the common constructors
|
||||
and environment boundary do not rely on an invalid or ambiguous policy value.
|
||||
There is positive production enforcement rather than a test-only contract.
|
||||
|
||||
**Rule discrimination.** Decision rule 4 discriminates well if “low-level
|
||||
escape hatch” is read literally. If any alternate builder method were treated
|
||||
as a second domain meaning, scores 3 and 4 would become difficult to distinguish
|
||||
for facades.
|
||||
|
||||
### `fabro-http` × `duplication-knowledge` — 4
|
||||
|
||||
**Direct evidence.** `define_builder!` is one production mechanism for all
|
||||
shared async/blocking builder methods and for applying proxy policy
|
||||
(`src/lib.rs:72-170`); the two concrete builders are declarations of that
|
||||
mechanism (`src/lib.rs:172-193`). `ProxyPolicy::resolve` is the single authority
|
||||
for explicit-versus-environment precedence (`src/lib.rs:38-59`), and the four
|
||||
convenience constructors delegate to the builders (`src/lib.rs:195-213`).
|
||||
Workspace boundary evidence reinforces this authority: `clippy.toml` disallows
|
||||
raw reqwest client constructors in favor of these functions/builders.
|
||||
|
||||
**Strongest counterevidence.** The tokens `system` and `disabled` also appear in
|
||||
the human-readable error text, and the async/blocking test constructors repeat
|
||||
the choice of `ProxyPolicy::Disabled`.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because the repeated
|
||||
tokens and two one-line convenience constructors do not form independent
|
||||
authorities for a recurring transformation. The macro and resolver are what
|
||||
enforce behavior.
|
||||
|
||||
**Rule discrimination.** Decision rule 5 is useful but leaves a small judgment
|
||||
gap around repeated diagnostic vocabulary. Here that repetition is
|
||||
non-discriminating: adding a variant would make the exhaustive application
|
||||
match fail to compile, while one diagnostic sentence is not a second policy
|
||||
engine. This is why confidence is Medium rather than High.
|
||||
|
||||
### `fabro-web-app` × `ownership-boundaries` — 4
|
||||
|
||||
**Direct evidence.** Shared HTTP configuration, authentication redirect, and
|
||||
error normalization live in `app/lib/api-client.ts:64-160,213-309`. Read state
|
||||
and cache keys live in `app/lib/queries.ts` and
|
||||
`app/lib/query-keys.ts`; for example, `useRun` owns the run-detail fetch/cache
|
||||
lifecycle (`queries.ts:182-187`). Shared run mutations and their cache updates
|
||||
live in `app/lib/mutations.ts:42-208`. Run SSE connection sharing, cleanup, and
|
||||
cache invalidation live in `app/lib/sse.ts:42-189` and
|
||||
`app/lib/run-events.ts:129-308`. Browser resources with more specialized
|
||||
lifecycles are likewise contained: terminal WebSocket/xterm/listener cleanup is
|
||||
in `app/hooks/use-terminal-session.ts:62-229`, and install polling owns its
|
||||
timer, interval, and abort controller in
|
||||
`app/hooks/use-install-effects.ts:72-127`.
|
||||
|
||||
`RunDetail` composes these owners and retains view-local state and interaction
|
||||
ordering (`app/routes/run-detail.tsx:79-145,148-379`). Its size does not make it
|
||||
the owner of transport or resource cleanup.
|
||||
|
||||
**Strongest counterevidence.** Several feature routes perform feature-local
|
||||
create/edit/delete calls and SWR invalidation directly, and `RunDetail` owns the
|
||||
delete dialog, pending state, toast, list invalidation, and navigation
|
||||
(`run-detail.tsx:193-205`) rather than using a single mutation hook for that
|
||||
entire interaction.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit without a concrete
|
||||
isolated lifecycle that has competing owners. The direct route mutations keep
|
||||
their feature interaction lifecycle local and still use the shared transport;
|
||||
they are not evidence that ordinary reads, SSE, or browser resources leak into
|
||||
route composition.
|
||||
|
||||
**Rule discrimination.** The final repository example is discriminating:
|
||||
“busy route” must not itself count as boundary leakage. Confidence remains
|
||||
Medium because the application scope is broad, although the representative
|
||||
read, mutation, live-update, terminal, install, and route boundaries converge.
|
||||
|
||||
### `repository-ci` × `ownership-boundaries` — 2
|
||||
|
||||
**Direct evidence.** The Rust workflow’s Clippy job owns a repository-wide
|
||||
“legacy auth identity removal” guard that scans `lib/apps`, `lib/components`,
|
||||
`lib/foundation`, `apps`, `lib/packages`, and the OpenAPI document
|
||||
(`.github/workflows/rust.yml:80-91`). The workflow’s path filters do not include
|
||||
`apps/**`, `lib/packages/**`, or
|
||||
`docs/public/api-reference/fabro-api.yaml`
|
||||
(`rust.yml:3-35`). A routine change in a scanned TypeScript/package/API path can
|
||||
therefore introduce a forbidden identity without starting the job that owns the
|
||||
guard. The policy lifecycle is placed under a narrower Rust trigger than the
|
||||
responsibility it claims.
|
||||
|
||||
**Strongest counterevidence.** The primary Rust and TypeScript build/test
|
||||
responsibilities otherwise have clear workflow homes, read-only permissions,
|
||||
and stable concurrency ownership (`rust.yml:38-147`;
|
||||
`typescript.yml:30-77`). The TypeScript production build’s Rust step is a
|
||||
legitimate composition point because it builds the Rust binary with the
|
||||
embedded SPA.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because the trigger
|
||||
mismatch affects ordinary changes in multiple scanned source areas, not an
|
||||
isolated maintenance path. Score 1 does not fit because the two main language
|
||||
workflows and their jobs still have stable owners and dependency direction.
|
||||
|
||||
**Rule discrimination.** No final rule explicitly says how to classify a check
|
||||
whose declared scan scope exceeds its trigger scope. The ownership lens’s
|
||||
“complete lifecycle” language is sufficient, but an explicit trigger/target
|
||||
coverage rule would make 2 versus 3 less ambiguous.
|
||||
|
||||
### `repository-ci` × `domain-model` — 2
|
||||
|
||||
**Direct evidence.** Every value in `.github/zizmor.yml` is a line-addressed
|
||||
identifier: `rust.yml:37`, `rust.yml:49`, and `rust.yml:62`
|
||||
(`.github/zizmor.yml:1-6`). At this revision those lines are respectively a
|
||||
blank separator, the `fmt` job key, and a `run:` step—not action references.
|
||||
Thus none is a current target for the configured `stale-action-refs` ignores.
|
||||
Routine edits to `rust.yml` can change the accidental referents again without
|
||||
changing the selectors.
|
||||
|
||||
**Strongest counterevidence.** The syntax still communicates an intended
|
||||
workflow-and-line selector, and the main workflow job/status vocabulary is
|
||||
otherwise stable.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because all three
|
||||
values in the entire scoped zizmor configuration lack their intended current
|
||||
referent; this is not one isolated compatibility value. Score 1 does not fit
|
||||
because the selector format and intended concept remain identifiable even
|
||||
though the instances are stale.
|
||||
|
||||
**Rule discrimination.** Decision rule 6 is decisive and correctly keeps this
|
||||
under domain model rather than ownership. It would not by itself distinguish 2
|
||||
from 3; the fact that every configured identifier is stale and line edits make
|
||||
the condition recur supplies that distinction.
|
||||
|
||||
## Control: `fabro-checkpoint`
|
||||
|
||||
### `fabro-checkpoint` × `ownership-boundaries` — 4
|
||||
|
||||
**Direct evidence.** `git::Store` owns the `git2::Repository` and the low-level
|
||||
blob/tree/commit/ref operations (`src/git.rs:101-227`).
|
||||
`branch::BranchStore` owns branch identity, author identity, and the complete
|
||||
local read-modify-write lifecycle, including parent resolution, tree read,
|
||||
commit, and ref update (`src/branch.rs:17-82`). Author and trailer concerns are
|
||||
focused modules rather than state hidden in callers (`src/author.rs`;
|
||||
`src/trailer.rs`). Boundary evidence points in the intended direction:
|
||||
`fabro-workflow` depends on these primitives, while its
|
||||
`RunMetadataWriter` owns the additional temp repository, remote discovery,
|
||||
credentials, push, and degradation lifecycle. That is a higher-level owner
|
||||
using a lower-level delegate, not a reverse dependency.
|
||||
|
||||
**Strongest counterevidence.** The production metadata writer uses `Store`
|
||||
directly and manually sequences blob, tree, commit, and ref operations
|
||||
(`fabro-workflow/src/run_metadata.rs:313-361`) instead of using `BranchStore`.
|
||||
The crate name/description can make that look like the mapped checkpoint
|
||||
lifecycle has escaped the component.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit if responsibilities are
|
||||
classified by their actual state: `Store` owns local Git mechanics,
|
||||
`BranchStore` owns local branch writes, and `RunMetadataWriter` owns remote run
|
||||
metadata. No concrete resource is acquired by one of those owners and released
|
||||
by another.
|
||||
|
||||
**Rule discrimination.** Decision rule 2 is ambiguous for intentionally
|
||||
low-level facades. Passing a branch to `Store::update_ref` should not alone mean
|
||||
“resupplying identity” when the caller owns the higher-level remote branch
|
||||
lifecycle and `Store` never claimed it. If the mapped purpose is instead read
|
||||
as all run-checkpoint lifecycle, this assignment could become 2; that purpose
|
||||
boundary should be fixed before using the control for strict agreement.
|
||||
|
||||
### `fabro-checkpoint` × `simplicity` — 4
|
||||
|
||||
**Direct evidence.** The local branch write path is linear in
|
||||
`BranchStore::write_with`: resolve parent, read tree, apply one caller mutation,
|
||||
write tree, commit, update ref (`src/branch.rs:56-81`). Single-file,
|
||||
multi-file, and delete operations are thin delegates to that path
|
||||
(`src/branch.rs:84-117`). The lower-level tree conversion is one direct
|
||||
flat-to-nested algorithm (`src/git.rs:229-309`), and trailer formatting/parsing
|
||||
uses straightforward local control flow (`src/trailer.rs:9-87`).
|
||||
|
||||
**Strongest counterevidence.** `BranchStore` has no external production caller
|
||||
at this revision; the actual metadata path uses the lower-level `Store` API.
|
||||
There is also some unused-looking surface such as `MetadataError` and generic
|
||||
branch read/list/log helpers.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because no direct
|
||||
production evidence shows routine changes navigating the unused surface or
|
||||
competing implementations. The production `Store` call sequence is itself
|
||||
linear. The rubric explicitly says a public method alone does not establish
|
||||
frequency, so unused API breadth cannot by itself create common-path
|
||||
indirection.
|
||||
|
||||
**Rule discrimination.** The score-4 requirement for a “production mechanism”
|
||||
is mildly ambiguous when the clearest high-level mechanism has no production
|
||||
caller but its lower-level mechanism does. Treating compiled non-test code as
|
||||
sufficient would make the rule non-discriminating; this score instead relies on
|
||||
the directly used `Store` path also being traceable.
|
||||
|
||||
### `fabro-checkpoint` × `domain-model` — 3
|
||||
|
||||
**Direct evidence.** The common metadata boundary validates every path before
|
||||
putting it into `TreeEntries`
|
||||
(`fabro-workflow/src/run_metadata.rs:319-336,471-481`), explicitly selects
|
||||
`FileMode::Blob`, and converts author strings with the fallible
|
||||
`git2::Signature::now` before committing (`run_metadata.rs:337-345`). Within the
|
||||
control, `FileMode` and `TreeEntries` give Git tree entries a stable meaning
|
||||
(`src/git.rs:13-99`), and Git failures stay typed (`src/error.rs:3-32`).
|
||||
|
||||
There is nevertheless isolated model friction. `TreeEntries::set` accepts any
|
||||
string path with no invariant-bearing path type (`src/git.rs:59-61`);
|
||||
`FileMode::from_i32` maps every unrecognized Git mode to `Blob`
|
||||
(`src/git.rs:30-35`); `GitAuthor` has public raw string fields
|
||||
(`src/author.rs:6-11`); and `BranchStore` says trees grow monotonically while
|
||||
also exposing `delete_entry` (`src/branch.rs:17-19,111-117`).
|
||||
|
||||
**Strongest counterevidence.** These are not merely hypothetical invalid
|
||||
shapes: low-level public callers can bypass the production metadata-path
|
||||
validation, and Git supports meaningful modes omitted by `FileMode`.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 4 does not fit because the low-level
|
||||
types themselves do not reject invalid paths/authors or preserve every Git
|
||||
mode. Score 2 does not fit because the directly traced production metadata path
|
||||
validates before interpretation and does not depend on the fallback
|
||||
`from_i32`; the friction is in lower-level escape paths and the currently
|
||||
unused `BranchStore`, not every common snapshot.
|
||||
|
||||
**Rule discrimination.** Decision rule 4 is useful but ambiguous about whether
|
||||
a common caller validating raw values before a low-level API counts as a
|
||||
“common-path invalid intermediate.” The rule should distinguish an actually
|
||||
reparsed/ambiguous value from a raw value that has already passed one boundary
|
||||
check but lacks an invariant-bearing Rust type.
|
||||
|
||||
### `fabro-checkpoint` × `duplication-knowledge` — 2
|
||||
|
||||
**Direct evidence.** The branch-name-to-full-ref transformation
|
||||
`refs/heads/{branch}` is repeated independently in `Store::update_ref`,
|
||||
`Store::resolve_ref`, and `Store::delete_ref`
|
||||
(`src/git.rs:182-225`). The direct production boundary repeats it again in
|
||||
`RunMetadataWriter::full_ref`
|
||||
(`fabro-workflow/src/run_metadata.rs:425-439`). A routine addition or change to
|
||||
branch ref handling must preserve the same transformation in each location.
|
||||
The trailer grammar has a second, smaller recurrence: `": "` is independently
|
||||
formatted, parsed, and detected in `append`, `parse`, `format_message`, and
|
||||
`has_trailing_trailer_block` (`src/trailer.rs:11-12,28-40,45-59,68-86`).
|
||||
|
||||
**Strongest counterevidence.** Both grammars are tiny and stable, tests cover
|
||||
the trailer forms, and the three Store methods currently agree. A helper could
|
||||
look like cosmetic deduplication rather than a material abstraction.
|
||||
|
||||
**Why adjacent scores do not fit.** Score 3 does not fit because branch
|
||||
resolution/update/deletion are ordinary Store operations and direct boundary
|
||||
code already supplies a fourth recurrence; this is not only a hypothetical
|
||||
future variant. Score 1 does not fit because the repeated transformations are
|
||||
stable and readily identifiable even though they lack a single authority.
|
||||
|
||||
**Rule discrimination.** Decision rule 5 is decisive only if “direct evidence
|
||||
of routine recurrence” includes several current operations applying the same
|
||||
transformation. If it instead requires historical change evidence, the final
|
||||
rule would be non-discriminating for a revision-only review and this assignment
|
||||
would move toward 3.
|
||||
|
||||
## Round 2 revalidation
|
||||
|
||||
These scores supersede the corresponding Round 1 scores.
|
||||
|
||||
### `fabro-http` × `duplication-knowledge` — 3 (Medium)
|
||||
|
||||
**Decisive evidence.** `ProxyPolicy::parse` is the behavioral authority for the
|
||||
external `system`/`disabled` vocabulary, while
|
||||
`HttpClientBuildError::InvalidProxyPolicy` separately enumerates those values
|
||||
in its diagnostic (`src/lib.rs:29-35,63-66`). The builder macro remains one
|
||||
authority for applying the policy to both client kinds (`src/lib.rs:72-193`).
|
||||
|
||||
**Adjacent scores and ambiguity.** Score 4 does not fit because the diagnostic
|
||||
is a concrete second representation that can drift. Score 2 does not fit
|
||||
because proxy behavior is not independently reimplemented: the shared
|
||||
resolver and macro enforce it, and the two no-proxy convenience constructors
|
||||
are call sites rather than separate authorities (`src/lib.rs:195-213`). The
|
||||
remaining ambiguity is whether changing the closed proxy vocabulary is routine
|
||||
enough to make the diagnostic synchronization central; I treat it as isolated.
|
||||
|
||||
### `repository-ci` × `ownership-boundaries` — 2 (High)
|
||||
|
||||
**Decisive evidence.** The Rust workflow's legacy-auth check scans `apps`,
|
||||
`lib/packages`, and `docs/public/api-reference/fabro-api.yaml`
|
||||
(`rust.yml:80-91`), but its push and pull-request path filters omit all three
|
||||
(`rust.yml:3-35`). Under decision rule 3, that check owns trigger coverage for
|
||||
every path it scans, so routine changes in those targets bypass its lifecycle.
|
||||
|
||||
**Adjacent scores and ambiguity.** Score 3 does not fit because the missing
|
||||
triggers affect several routine source and contract paths, not an isolated
|
||||
edge. Score 1 does not fit because the Rust and TypeScript workflow owners and
|
||||
dependency direction remain stable. No material ambiguity remains under the
|
||||
new trigger-coverage rule.
|
||||
|
||||
### `fabro-checkpoint` × `ownership-boundaries` — 2 (High)
|
||||
|
||||
**Decisive evidence.** The map assigns checkpoint commits, trees, metadata
|
||||
branches, authorship, and trailers to this component. The routine
|
||||
`RunMetadataWriter` caller reconstructs that mapped lifecycle from `Store`
|
||||
primitives: it writes blobs and a tree, creates the commit and author/message,
|
||||
updates the ref, and pushes
|
||||
(`fabro-workflow/src/run_metadata.rs:313-361`). Decision rule 2 therefore
|
||||
places ownership at 2 even though the crate dependency points toward
|
||||
`fabro-checkpoint`.
|
||||
|
||||
**Adjacent scores and ambiguity.** Score 3 does not fit because this is the
|
||||
common metadata snapshot path, not an edge case. Score 1 does not fit because
|
||||
the dependency direction and the low-level `Store` role are stable, and
|
||||
`BranchStore::write_with` demonstrates a coherent lifecycle owner inside the
|
||||
crate (`src/branch.rs:56-81`). The only remaining ambiguity is how specialized
|
||||
the metadata commit is, but the map explicitly includes metadata branches.
|
||||
|
||||
### `fabro-checkpoint` × `simplicity` — 3 (High)
|
||||
|
||||
**Decisive evidence.** `fabro-store` and `serde` are production dependencies
|
||||
with no source use (`Cargo.toml:16-24`), and `BranchStore` is a parallel
|
||||
high-level entry layer with no production caller outside this crate. Decision
|
||||
rule 4 makes those isolated simplicity frictions and caps 4 at 3.
|
||||
|
||||
**Adjacent scores and ambiguity.** Score 4 does not fit because the unused
|
||||
production edges and parallel layer are concrete. Score 2 does not fit because
|
||||
the production `Store` path remains direct; normal callers do not navigate the
|
||||
unused dependencies or `BranchStore`. Whether `BranchStore` is retained for a
|
||||
future caller is ambiguous, but the unused dependencies alone sustain 3.
|
||||
|
||||
### `fabro-checkpoint` × `domain-model` — 2 (Medium)
|
||||
|
||||
**Decisive evidence.** The mapped Git-tree entry accepts any `String` path
|
||||
through `TreeEntries::set` (`src/git.rs:44-61`), while the routine metadata
|
||||
writer must validate paths before constructing those entries
|
||||
(`fabro-workflow/src/run_metadata.rs:319-336,471-481`). Decision rule 5 says
|
||||
caller validation does not isolate an invalid-capable mapped entry.
|
||||
`FileMode::from_i32` also collapses every unrecognized mode to `Blob`
|
||||
(`src/git.rs:29-35`).
|
||||
|
||||
**Adjacent scores and ambiguity.** Score 3 does not fit because raw paths cross
|
||||
the common write boundary. Score 1 does not fit because tree entries, modes,
|
||||
and authors retain stable meanings and the caller does validate its input.
|
||||
Confidence is Medium because a deliberately low-level Git store can reasonably
|
||||
leave some path constraints to higher-level schemas, although the revised rule
|
||||
weighs against that interpretation.
|
||||
|
||||
### `fabro-checkpoint` × `duplication-knowledge` — 3 (Medium)
|
||||
|
||||
**Decisive evidence.** The `refs/heads/{branch}` transformation is repeated in
|
||||
three `Store` operations and once at the workflow boundary
|
||||
(`src/git.rs:182-225`; `fabro-workflow/src/run_metadata.rs:425-439`).
|
||||
Trailer formatting, parsing, and block detection also encode the `": "`
|
||||
convention separately (`src/trailer.rs:11-12,28-40,45-59,68-86`). These are
|
||||
concrete second representations, so decision rule 6 caps 4 at 3.
|
||||
|
||||
**Adjacent scores and ambiguity.** Score 2 does not fit on the current evidence:
|
||||
adding a Store operation or trailer key may repeat a call-site convention, but
|
||||
does not require an ordinary mapped change to modify all existing locations.
|
||||
Score 4 does not fit because the representations are nevertheless concrete and
|
||||
can drift. The remaining ambiguity is whether broader trailer-syntax support
|
||||
would be routine maintenance; if so, its formatter/parser/detector
|
||||
synchronization would support 2.
|
||||
|
|
@ -1,447 +0,0 @@
|
|||
# Chisel calibration validation 3
|
||||
|
||||
Revision reviewed: `6bb6b5efcc0e36b52e3c097f532d9f2c00914c6c`.
|
||||
|
||||
This is an independent reading of the final rubric and the assigned component
|
||||
scopes. I traced representative production entry points and direct boundary
|
||||
callers. I did not inspect prior calibration scores or any other file in
|
||||
`.chisel/calibration/work/`.
|
||||
|
||||
## Score summary
|
||||
|
||||
| Component | Lens | Score | Evidence confidence |
|
||||
| --- | --- | ---: | --- |
|
||||
| `fabro-workflow` | ownership-boundaries | 2 | High |
|
||||
| `fabro-workflow` | domain-model | 2 | High |
|
||||
| `fabro-http` | domain-model | 4 | High |
|
||||
| `fabro-http` | duplication-knowledge | 3 | Medium |
|
||||
| `fabro-web-app` | ownership-boundaries | 4 | Medium |
|
||||
| `repository-ci` | ownership-boundaries | 4 | Medium |
|
||||
| `repository-ci` | domain-model | 2 | High |
|
||||
| `fabro-checkpoint` | ownership-boundaries | 2 | High |
|
||||
| `fabro-checkpoint` | simplicity | 3 | Medium |
|
||||
| `fabro-checkpoint` | domain-model | 2 | High |
|
||||
| `fabro-checkpoint` | duplication-knowledge | 3 | Medium |
|
||||
|
||||
## `fabro-workflow`
|
||||
|
||||
### `ownership-boundaries`: 2 (High)
|
||||
|
||||
- **Evidence:** `src/lifecycle/mod.rs:53-80,221-469` provides a real central
|
||||
`WorkflowLifecycle` and explicitly orders focused event, hook, fidelity, Git,
|
||||
artifact, status, and circuit-breaker delegates. Its terminal callback,
|
||||
however, only forwards `on_run_end` to the hook. Normal terminal persistence,
|
||||
metadata completion, terminal event emission, and sandbox stopping instead
|
||||
live in `src/pipeline/finalize.rs:524-635`. Bootstrap and execution failures
|
||||
take another terminal path in `src/operations/start.rs:176-345`, while
|
||||
`RunSession::run` also installs cleanup and drain guards at
|
||||
`src/operations/start.rs:889-947`. A routine terminal-lifecycle change must
|
||||
therefore coordinate the lifecycle orchestrator, finalizer, and detached
|
||||
failure/guard paths.
|
||||
- **Strongest counterevidence:** The normal phase sequence is plainly owned by
|
||||
`RunSession::run` (`initialize -> execute -> finalize -> pull_request`), and
|
||||
callback ordering inside graph execution has one obvious owner,
|
||||
`WorkflowLifecycle`.
|
||||
- **Why 3 does not fit:** Terminal completion, failure, persistence, and cleanup
|
||||
are common paths, not isolated edge compatibility. The split therefore
|
||||
remains central even though each individual phase is understandable.
|
||||
- **Why 1 does not fit:** Stable phase owners and a stable dependency direction
|
||||
are readily identifiable; the problem is coordination among them, not the
|
||||
absence of ownership.
|
||||
- **Rule discrimination:** The repository example correctly requires terminal
|
||||
inspection and rule 1 makes the common terminal split score-capping. Decision
|
||||
rule 2 is less literal here because no single identity is resupplied across
|
||||
every split, but the score does not depend on that rule.
|
||||
|
||||
### `domain-model`: 2 (High)
|
||||
|
||||
- **Evidence:** `src/lifecycle/event.rs:319-390` starts with the typed
|
||||
`StageOutcome` on an `Outcome`, serializes it with
|
||||
`outcome.status.to_string()`, and stores the result in the
|
||||
`Event::StageCompleted.status: String` field declared at
|
||||
`src/event/events.rs:264-293`. Every successful stage then passes through
|
||||
`src/event/convert.rs:14-24,309-348`, which reparses the string and silently
|
||||
converts an unknown value into a non-retryable failure. This is the ordinary
|
||||
durable-event path, not an import-only compatibility path.
|
||||
- **Strongest counterevidence:** The destination event model already has the
|
||||
canonical `fabro_types::StageOutcome`, parallel-branch completion carries it
|
||||
directly, and other core run concepts use typed IDs, reasons, timings, and an
|
||||
opaque `ResumeState` (`src/pipeline/types.rs:252-285`).
|
||||
- **Why 3 does not fit:** The invalid intermediate occurs for each ordinary
|
||||
successful stage before durable interpretation, so it is central rather than
|
||||
an isolated escape hatch.
|
||||
- **Why 1 does not fit:** `StageOutcome` itself has a stable, typed meaning; the
|
||||
defect is the recurring string round trip between two typed points.
|
||||
- **Rule discrimination:** Decision rule 4 is directly discriminating here:
|
||||
this is exactly a common-path invalid intermediate.
|
||||
|
||||
## `fabro-http`
|
||||
|
||||
### `domain-model`: 4 (High)
|
||||
|
||||
- **Evidence:** `src/lib.rs:23-61` gives proxy behavior a closed
|
||||
`ProxyPolicy::{System, Disabled}` vocabulary. The environment boundary
|
||||
accepts case-insensitive valid names, rejects every other value with a typed
|
||||
`HttpClientBuildError`, handles non-Unicode values explicitly, gives explicit
|
||||
policy precedence over the environment, and resolves absence to `System`.
|
||||
Both generated builders invoke this resolver before constructing a client
|
||||
(`src/lib.rs:72-193`), and the test-client entry points select
|
||||
`ProxyPolicy::Disabled` rather than passing an unchecked string
|
||||
(`src/lib.rs:195-213`).
|
||||
- **Strongest counterevidence:** The facade deliberately exposes reqwest's
|
||||
lower-level `Proxy` and `.no_proxy()` operations, so callers can compose
|
||||
transport details outside the two-value environment policy.
|
||||
- **Why 3 does not fit:** Those operations are typed builder choices, not
|
||||
unvalidated representations of the `FABRO_HTTP_PROXY_POLICY` value. Every
|
||||
common construction path still validates that boundary before use; I found no
|
||||
material meaning or validation friction.
|
||||
- **Why 1-2 do not fit:** There is one stable meaning, one resolver, and no
|
||||
recurring conversion through an invalid intermediate.
|
||||
- **Rule discrimination:** Decision rule 4 could be read ambiguously if every
|
||||
low-level builder method is called a policy escape hatch. The rubric's own
|
||||
`ProxyPolicy` example resolves that ambiguity in favor of the closed,
|
||||
validated environment-policy model.
|
||||
|
||||
### `duplication-knowledge`: 3 (Medium)
|
||||
|
||||
- **Evidence:** `define_builder!` at `src/lib.rs:72-193` is one authoritative
|
||||
production mechanism for the shared async/blocking builder surface and for
|
||||
applying the resolved proxy policy. The four convenience constructors route
|
||||
through those builders. The remaining repeated knowledge is narrow:
|
||||
`"system"` and `"disabled"` appear both in the parser and in the manually
|
||||
maintained `InvalidProxyPolicy` expectation text
|
||||
(`src/lib.rs:29-35,63-69`).
|
||||
- **Strongest counterevidence:** The macro removes the materially risky
|
||||
async/blocking synchronization, and the compiler forces the policy-application
|
||||
match to cover every enum variant. The two test helpers' use of
|
||||
`ProxyPolicy::Disabled` is ordinary reuse, not a second policy authority.
|
||||
- **Why 4 does not fit:** The user-facing valid-value list is a small second
|
||||
representation that can drift from the parser, so there is some isolated
|
||||
repeated domain knowledge.
|
||||
- **Why 2 does not fit:** There is no direct evidence that routine changes
|
||||
repeatedly synchronize separate async/blocking implementations. A future
|
||||
enum variant is hypothetical, and rule 5 specifically says exhaustive
|
||||
compiler-checked branches and hypothetical variants do not establish
|
||||
competing authorities.
|
||||
- **Rule discrimination:** Rule 5 cleanly rules out 2 but is non-discriminating
|
||||
between 3 and 4 for a duplicated allowed-value error message. I treat that
|
||||
message as real but isolated maintenance friction, hence 3.
|
||||
|
||||
## `fabro-web-app`
|
||||
|
||||
### `ownership-boundaries`: 4 (Medium)
|
||||
|
||||
- **Evidence:** `app/entry.tsx:17-48` owns root creation, global SWR policy,
|
||||
build-version guarding, toast mounting, and the single normal/install router
|
||||
choice. `app/router.tsx:97-184` owns normal route composition, while
|
||||
`app/install-router.tsx:6-22` owns the install graph. Shared HTTP translation
|
||||
and unauthorized handling live in `app/lib/api-client.ts:213-309`; shared
|
||||
reads such as `useRun` live in `app/lib/queries.ts:182-187`; recurring run
|
||||
mutations and cache follow-up live in
|
||||
`app/lib/mutations.ts:65-149`. Route components compose these owners.
|
||||
Separately, `scripts/build.ts:183-249,289-368` contains the complete
|
||||
app-local build, atomic publication, and old-build pruning lifecycle and
|
||||
publishes only `apps/fabro-web/dist`; boundary tooling mirrors that output
|
||||
into the Rust SPA rather than the web build writing across the boundary.
|
||||
- **Strongest counterevidence:** Some route-specific CRUD mutations import
|
||||
`apiData` and generated API objects directly, and the install feature spans
|
||||
`install-app.tsx`, `install-api.ts`, `install-query.ts`, and effect hooks.
|
||||
`run-detail.tsx` is also a busy composition point.
|
||||
- **Why 3 does not fit:** The direct calls remain at the route-specific UX
|
||||
owner and still use the shared transport/error boundary; shared read and
|
||||
recurring run-lifecycle responsibilities are not reimplemented there.
|
||||
Install state, transport, query, and browser effects have distinct homes.
|
||||
I found no isolated lifecycle that must leave its owner and resupply identity.
|
||||
- **Why 1-2 do not fit:** Runtime, routing, transport, queries, route UX, and
|
||||
build publication all have stable owners with dependencies pointing from
|
||||
composition toward shared services.
|
||||
- **Rule discrimination:** The final repository example is useful and
|
||||
discriminating: a large route is not by itself boundary leakage. The score
|
||||
would change if direct routes reimplemented shared transport or cache
|
||||
lifecycles, but representative boundary checks did not show that.
|
||||
|
||||
## `repository-ci`
|
||||
|
||||
### `ownership-boundaries`: 4 (Medium)
|
||||
|
||||
- **Evidence:** `.github/workflows/rust.yml:48-147` owns Rust formatting,
|
||||
lint/architecture checks, generated docs, Linux tests, twin E2E selection,
|
||||
and manual macOS tests. `.github/workflows/typescript.yml:36-77` owns web and
|
||||
generated-client typechecks, web tests, and the production embedded-SPA
|
||||
integration build. Each workflow owns its concurrency and least-privilege job
|
||||
permissions. The TypeScript workflow's `cargo dev build` is the intentional
|
||||
integration boundary that consumes the web bundle; it does not create a
|
||||
competing implementation of the web build.
|
||||
- **Strongest counterevidence:** The TypeScript build job invokes Rust build
|
||||
tooling, path scopes overlap around `lib/apps/fabro-spa/**`, and
|
||||
`.github/zizmor.yml` is configuration whose consumer is not shown in these
|
||||
files.
|
||||
- **Why 3 does not fit:** Cross-language integration is part of the mapped CI
|
||||
purpose and has one concrete home. The stale configuration values discussed
|
||||
below are domain-model findings, while duplicated push/pull selectors are
|
||||
duplication findings; counting either again as ownership friction would
|
||||
violate the rubric's primary-lens rule.
|
||||
- **Why 1-2 do not fit:** The Rust and TypeScript responsibilities and their
|
||||
dependency direction are stable. Routine validation changes have an obvious
|
||||
workflow owner rather than requiring competing lifecycle owners.
|
||||
- **Rule discrimination:** The instruction not to penalize an unevidenced
|
||||
missing lifecycle matters for the unseen zizmor consumer. The rubric is
|
||||
otherwise discriminating once repeated selector policy is kept out of the
|
||||
ownership lens.
|
||||
|
||||
### `domain-model`: 2 (High)
|
||||
|
||||
- **Evidence:** Both Rust trigger selectors name `openapi/**`
|
||||
(`.github/workflows/rust.yml:6-19,22-35`), but that revision has no tracked
|
||||
`openapi/` target. The actual Rust generator and TypeScript generator consume
|
||||
`docs/public/api-reference/fabro-api.yaml`
|
||||
(`lib/foundation/fabro-api/build.rs:159` and
|
||||
`lib/packages/fabro-api-client/package.json:7`), a path omitted from both
|
||||
workflow trigger models. This makes a core API-spec change invisible to the
|
||||
intended CI trigger. In addition, all three
|
||||
`.github/zizmor.yml:4-6` line selectors target
|
||||
`.github/workflows/rust.yml` lines 37, 49, and 62, which are respectively
|
||||
`workflow_dispatch`, the `fmt` job key, and a shell `run`, not action
|
||||
references for `stale-action-refs`.
|
||||
- **Strongest counterevidence:** Most configured branches, paths, action SHAs,
|
||||
runner labels, job names, and commands have clear current targets, and both
|
||||
workflow documents have a stable overall schema.
|
||||
- **Why 3 does not fit:** The dead OpenAPI selector sits in both central Rust
|
||||
push and pull-request triggers and omits the actual source of truth. It is not
|
||||
merely an isolated stale lint suppression.
|
||||
- **Why 1 does not fit:** The CI configuration language and almost all values
|
||||
remain interpretable; the problem is recurring invalid/no-target identifiers,
|
||||
not the absence of a stable configuration model.
|
||||
- **Rule discrimination:** Decision rule 6 correctly classifies the no-target
|
||||
identifiers as domain pressure, but it does not itself distinguish 2 from 3.
|
||||
The centrality of the API source-of-truth trigger is what selects 2.
|
||||
|
||||
## Control: `fabro-checkpoint`
|
||||
|
||||
### `ownership-boundaries`: 2 (High)
|
||||
|
||||
- **Evidence:** Inside the component, `BranchStore` owns a branch string and
|
||||
author and delegates Git objects to `Store`
|
||||
(`src/branch.rs:17-82`), which is a sensible direction. At the production
|
||||
boundary, however, no production caller constructs `BranchStore`.
|
||||
`fabro-workflow/src/run_metadata.rs:272-451` instead keeps `Store`, branch,
|
||||
author, `parent_oid`, and discovery state as separate fields, manually writes
|
||||
blobs and trees, supplies parents to `Store::write_commit`, resupplies the
|
||||
branch to `Store::update_ref`, and owns fetch/push discovery. Other checkpoint
|
||||
commit and trailer lifecycle work also remains in `fabro-workflow`. Thus the
|
||||
mapped checkpoint/metadata-branch lifecycle crosses the scoped owner on the
|
||||
normal production path.
|
||||
- **Strongest counterevidence:** `Store` is itself a mapped public entry point,
|
||||
the dependency direction remains `fabro-workflow -> fabro-checkpoint`, and
|
||||
remote authentication/push orchestration reasonably belongs near a workflow
|
||||
run rather than in a low-level Git object store.
|
||||
- **Why 3 does not fit:** The caller-held branch and parent identity are used on
|
||||
every metadata snapshot, not only in an isolated migration or uncommon
|
||||
fallback.
|
||||
- **Why 1 does not fit:** Low-level Git ownership and the higher workflow
|
||||
orchestration are both stable and understandable; they simply split one
|
||||
routine persistence lifecycle.
|
||||
- **Rule discrimination:** Decision rule 2 is directly discriminating:
|
||||
`RunMetadataWriter` retains and repeatedly resupplies the identity needed to
|
||||
complete operations on `Store`. The mapped breadth of “metadata branches”
|
||||
makes this more than ordinary parameter passing.
|
||||
|
||||
### `simplicity`: 3 (Medium)
|
||||
|
||||
- **Evidence:** The production low-level path is traceable:
|
||||
`Store::write_blob -> TreeEntries::set -> Store::write_tree ->
|
||||
Store::write_commit -> Store::update_ref`
|
||||
(`src/git.rs:123-188`). `BranchStore::write_with` also gives branch-oriented
|
||||
writes one linear read/modify/write implementation
|
||||
(`src/branch.rs:56-117`). The recursive flat-tree conversion is justified by
|
||||
Git's nested tree representation. The friction is isolated: `BranchStore` is
|
||||
a sizeable second entry layer with tests but no production caller at this
|
||||
revision, and `Cargo.toml:18` declares `fabro-store` although scoped
|
||||
production code does not reference it.
|
||||
- **Strongest counterevidence:** The two entry points represent legitimate
|
||||
abstraction levels, and the mapped cartography names both. None of the normal
|
||||
`Store` operations requires navigating configuration machinery or dynamic
|
||||
dispatch.
|
||||
- **Why 4 does not fit:** The unused higher layer/dependency is concrete,
|
||||
avoidable surface and configuration burden, even though it is off the current
|
||||
production common path.
|
||||
- **Why 2 does not fit:** Routine production writes do not repeatedly choose
|
||||
between `Store` and `BranchStore`; the observed caller consistently uses
|
||||
`Store`, and that path is direct.
|
||||
- **Rule discrimination:** The “public method alone does not establish
|
||||
frequency” rule prevents treating `BranchStore` as a competing common path.
|
||||
It is less discriminating between 3 and 4; the concrete unused dependency and
|
||||
unused entry layer are why I select 3.
|
||||
|
||||
### `domain-model`: 2 (High)
|
||||
|
||||
- **Evidence:** `GitAuthor::from_options` accepts arbitrary name/email strings
|
||||
(`src/author.rs:22-30`), while `BranchStore::new` only interprets them by
|
||||
calling `Signature::now(...).expect(...)`
|
||||
(`src/branch.rs:26-39`). `TreeEntries` stores paths as unrestricted `String`
|
||||
and `BranchStore::write_entry/write_entries` put caller strings into it
|
||||
without validation (`src/git.rs:46-90`,
|
||||
`src/branch.rs:84-109`); interpretation and possible rejection occur later
|
||||
while rebuilding Git trees. `FileMode::from_i32` also maps every unknown Git
|
||||
mode to `Blob` (`src/git.rs:21-36`) rather than preserving or rejecting an
|
||||
unknown shape. These invalid-capable intermediates sit on the mapped storage
|
||||
entry paths.
|
||||
- **Strongest counterevidence:** `FileMode` is closed for values the component
|
||||
writes, normal metadata callers validate paths before constructing
|
||||
`TreeEntries`, Git itself rejects malformed signatures/trees, and object IDs
|
||||
use git2's typed `Oid`.
|
||||
- **Why 3 does not fit:** Raw author and path values are carried by the ordinary
|
||||
entry-point types and interpreted later; they are not confined to a separate
|
||||
compatibility importer.
|
||||
- **Why 1 does not fit:** Authors, tree entries, modes, branches, and commits all
|
||||
have stable intended meanings. The issue is delayed validation and lossy
|
||||
fallback, not an unidentifiable core concept.
|
||||
- **Rule discrimination:** Decision rule 4 is discriminating here: these are
|
||||
common-path invalid-capable intermediate shapes rather than a low-level
|
||||
escape hatch unused by the entry path.
|
||||
|
||||
### `duplication-knowledge`: 3 (Medium)
|
||||
|
||||
- **Evidence:** Important transformations are mostly authoritative:
|
||||
`FileMode::{as_i32,from_i32}` contains the mode mapping,
|
||||
`BranchStore::write_with` contains branch read/modify/write, and
|
||||
`GitAuthor::default` contains the default identity. The narrow repeated
|
||||
knowledge is the bare-branch to full-ref transformation
|
||||
`format!("refs/heads/{branch}")` in each of
|
||||
`Store::{update_ref,resolve_ref,delete_ref}`
|
||||
(`src/git.rs:182-225`), with another full-ref rendering at the direct
|
||||
workflow metadata boundary. Trailer rendering also spells
|
||||
`"{}: {}"` in both `append` and `format_message`
|
||||
(`src/trailer.rs:9-65`).
|
||||
- **Strongest counterevidence:** The repeated ref syntax is stable low-level Git
|
||||
syntax, the three ref methods implement different operations, and the
|
||||
apparent duplication in single-entry/multi-entry or tip/commit reads has
|
||||
intentionally different result shapes. Unifying those operations would risk
|
||||
a parameterized mega-helper.
|
||||
- **Why 4 does not fit:** Full-ref and trailer-line rendering have small but real
|
||||
second representations rather than one helper/type enforcing each
|
||||
transformation.
|
||||
- **Why 2 does not fit:** There is no direct evidence of routine changes
|
||||
repeatedly synchronizing those stable renderings, and hypothetical future ref
|
||||
methods do not satisfy decision rule 5. The repeated knowledge is isolated
|
||||
from ordinary checkpoint-format extension.
|
||||
- **Rule discrimination:** Rule 5 usefully rules out 2 but is
|
||||
non-discriminating between 3 and 4 for repeated, stable protocol syntax. I
|
||||
score 3 because the repetitions are concrete, while keeping confidence
|
||||
Medium because their maintenance materiality is limited.
|
||||
|
||||
## Round 2 revalidation
|
||||
|
||||
I independently reapplied the simplified decision rules to only the requested
|
||||
assignments. Scores below supersede the corresponding Round 1 judgments for
|
||||
this revalidation.
|
||||
|
||||
| Component | Lens | Round 2 score | Confidence |
|
||||
| --- | --- | ---: | --- |
|
||||
| `fabro-http` | duplication-knowledge | 3 | High |
|
||||
| `repository-ci` | ownership-boundaries | 2 | High |
|
||||
| `fabro-checkpoint` | ownership-boundaries | 2 | High |
|
||||
| `fabro-checkpoint` | simplicity | 3 | High |
|
||||
| `fabro-checkpoint` | domain-model | 2 | High |
|
||||
| `fabro-checkpoint` | duplication-knowledge | 3 | Medium |
|
||||
|
||||
### `fabro-http` × `duplication-knowledge`: 3 (High)
|
||||
|
||||
- **Decisive evidence:** `define_builder!` remains the one mechanism for the
|
||||
materially recurring async/blocking builder policy
|
||||
(`src/lib.rs:72-193`). The parser and `InvalidProxyPolicy` message still hold
|
||||
a concrete second representation of the allowed `"system"`/`"disabled"`
|
||||
vocabulary (`src/lib.rs:29-35,63-69`).
|
||||
- **Adjacent scores:** 4 does not fit because revised rule 6 explicitly caps a
|
||||
concrete second semantic representation at 3. Score 2 does not fit because an
|
||||
ordinary mapped change does not currently synchronize separate async and
|
||||
blocking implementations; adding a future policy variant is not direct
|
||||
recurrence evidence.
|
||||
- **Remaining ambiguity:** None material. Revised rule 6 now resolves the prior
|
||||
3-versus-4 uncertainty.
|
||||
|
||||
### `repository-ci` × `ownership-boundaries`: 2 (High)
|
||||
|
||||
- **Decisive evidence:** The Rust workflow's architecture check scans
|
||||
`apps`, `lib/packages`, and
|
||||
`docs/public/api-reference/fabro-api.yaml`
|
||||
(`.github/workflows/rust.yml:80-91`), but its push and pull-request triggers
|
||||
omit all three routine target paths (`rust.yml:6-19,22-35`). Its Cargo jobs
|
||||
also consume the real API specification through
|
||||
`lib/foundation/fabro-api/build.rs`, yet that specification does not trigger
|
||||
the workflow. The TypeScript workflow likewise consumes the generated API
|
||||
client and performs the embedded integration build without making the source
|
||||
specification a trigger. Under revised rule 3, each check owns this coverage;
|
||||
the omitted routine targets are therefore central ownership pressure.
|
||||
- **Adjacent scores:** 3 does not fit because API, app, and package changes are
|
||||
routine targets of checks the workflow actually runs, not isolated edge
|
||||
inputs. Score 1 does not fit because Rust and TypeScript job ownership and
|
||||
dependency direction otherwise remain stable.
|
||||
- **Remaining ambiguity:** None material. The nonexistent `openapi/**` value is
|
||||
still a separate domain-model finding; the ownership finding rests on the
|
||||
real scanned/consumed paths that fail to trigger.
|
||||
|
||||
### `fabro-checkpoint` × `ownership-boundaries`: 2 (High)
|
||||
|
||||
- **Decisive evidence:** The mapped higher owner is `BranchStore`, but the
|
||||
routine production metadata caller instead retains `Store`, branch, author,
|
||||
parent, and discovery state and reconstructs blob/tree/commit/ref lifecycle
|
||||
from `Store` primitives in
|
||||
`fabro-workflow/src/run_metadata.rs:272-451`. Revised rule 2 names this shape
|
||||
directly.
|
||||
- **Adjacent scores:** 3 does not fit because reconstruction occurs on every
|
||||
metadata snapshot, not at an isolated edge. Score 1 does not fit because the
|
||||
low-level `Store` and workflow-level caller are stable, identifiable owners;
|
||||
the concern is the lifecycle split between them.
|
||||
- **Remaining ambiguity:** The workflow reasonably owns remote authentication,
|
||||
but that does not remove its reconstruction of the mapped checkpoint and
|
||||
metadata-branch persistence lifecycle.
|
||||
|
||||
### `fabro-checkpoint` × `simplicity`: 3 (High)
|
||||
|
||||
- **Decisive evidence:** The current production `Store` write sequence is
|
||||
linear and direct (`src/git.rs:123-188`). `BranchStore` is a parallel mapped
|
||||
entry layer with no production caller at this revision, and `Cargo.toml:18`
|
||||
declares the unused production dependency `fabro-store`. Revised rule 4
|
||||
classifies exactly this as isolated simplicity friction that caps 4 at 3.
|
||||
- **Adjacent scores:** 4 does not fit because the parallel unused layer and
|
||||
dependency are concrete. Score 2 does not fit because routine callers do not
|
||||
navigate competing paths or machinery; they consistently follow the direct
|
||||
`Store` path.
|
||||
- **Remaining ambiguity:** None material after rule 4. `BranchStore` being a
|
||||
mapped entry does not make it frequent when the boundary search finds no
|
||||
production caller.
|
||||
|
||||
### `fabro-checkpoint` × `domain-model`: 2 (High)
|
||||
|
||||
- **Decisive evidence:** Mapped entry shapes accept unrestricted author and path
|
||||
strings: `GitAuthor::from_options` stores raw values before
|
||||
`BranchStore::new` interprets them with `Signature::now(...).expect(...)`
|
||||
(`src/author.rs:22-30`, `src/branch.rs:26-39`), and
|
||||
`TreeEntries`/`write_entry` carry unchecked string paths until Git-tree
|
||||
construction (`src/git.rs:46-90`, `src/branch.rs:84-109`). Revised rule 5
|
||||
says caller validation and a typed destination do not isolate this
|
||||
invalid-capable mapped entry.
|
||||
- **Adjacent scores:** 3 does not fit because the invalid-capable shapes are on
|
||||
mapped entry paths, not a compatibility-only edge. Score 1 does not fit
|
||||
because the intended meanings of authors, paths, modes, and commits remain
|
||||
stable.
|
||||
- **Remaining ambiguity:** None material. Normal callers supplying valid values
|
||||
does not make the entry type canonical by construction.
|
||||
|
||||
### `fabro-checkpoint` × `duplication-knowledge`: 3 (Medium)
|
||||
|
||||
- **Decisive evidence:** Bare branch names are independently rendered as
|
||||
`refs/heads/{branch}` in `Store::update_ref`, `resolve_ref`, and `delete_ref`
|
||||
(`src/git.rs:182-225`), and trailer lines are independently rendered in
|
||||
`trailer::append` and `format_message` (`src/trailer.rs:9-65`). These are
|
||||
concrete second semantic representations, so revised rule 6 excludes 4.
|
||||
- **Adjacent scores:** 4 does not fit because the second renderings are real.
|
||||
Score 2 does not fit because no evidenced ordinary mapped change must
|
||||
synchronize the stable Git ref or trailer syntax across those locations;
|
||||
future ref operations are hypothetical, while the existing operations have
|
||||
distinct behavior.
|
||||
- **Remaining ambiguity:** Limited ambiguity remains over whether stable
|
||||
protocol syntax is material enough to count as semantic repetition at all.
|
||||
Rule 6 does not define that threshold, so confidence remains Medium; if it
|
||||
counts, 3 is the rule-directed score.
|
||||
|
|
@ -1,238 +0,0 @@
|
|||
# Documentation cartography scout
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`
|
||||
|
||||
Instructions read: `AGENTS.md`, `CONTRIBUTING.md`, and the Chisel cartography prompt. Scope is every tracked file under `docs/**`, plus `README.md` and `install.md`.
|
||||
|
||||
## Inventory
|
||||
|
||||
There are **488** scoped tracked files:
|
||||
|
||||
| Area | Files |
|
||||
| --- | ---: |
|
||||
| `docs/public/**` | 253 |
|
||||
| `docs/internal/**` | 82 |
|
||||
| `docs/plans/**` | 88 |
|
||||
| `docs/brainstorms/**` | 11 |
|
||||
| `docs/ideation/**` | 3 |
|
||||
| `docs/superpowers/**` | 49 |
|
||||
| `README.md`, `install.md` | 2 |
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `public-documentation` — Public documentation
|
||||
|
||||
- **Purpose:** Own the authored Fabro user documentation, Mintlify presentation/configuration, repository landing page, and the maintenance procedure for published web screenshots.
|
||||
- **Globs:**
|
||||
- `README.md`
|
||||
- `docs/public/**`
|
||||
- `docs/internal/updating-web-screenshots.md`
|
||||
- **Exclude globs:**
|
||||
- `docs/public/api-reference/fabro-api.yaml` — separate source contract
|
||||
- `docs/public/changelog/**` — separate published release-history component
|
||||
- all 22 generated public Graphviz SVG globs listed under exclusions below
|
||||
- **Entry points:**
|
||||
- `README.md`
|
||||
- `docs/public/docs.json`
|
||||
- `docs/public/getting-started/introduction.mdx`
|
||||
- `docs/public/getting-started/quick-start.mdx`
|
||||
- `docs/internal/updating-web-screenshots.md`
|
||||
- **Owns:**
|
||||
- Mintlify theme, navigation, tabs, and page ordering
|
||||
- public concepts, guides, tutorials, administration material, and reference prose
|
||||
- public documentation images, manually maintained SVG illustrations, logos, syntax definitions, and curated web screenshots
|
||||
- repository-facing overview and documentation links
|
||||
- web-screenshot capture and verification workflow
|
||||
- **Depends on candidates:** `fabro-http-api-contract`, `documentation-demo-workflows`, the CLI/config components that refresh fenced reference regions.
|
||||
- **Evidence:**
|
||||
- `AGENTS.md:46-51` mounts `docs/public` as the Mintlify document root.
|
||||
- `docs/public/docs.json` declares the Mintlify schema, theme, navigation, OpenAPI tab, and changelog tab.
|
||||
- `README.md` links to `docs.fabro.sh` and embeds assets from `docs/public/images` and `docs/public/logo`.
|
||||
- `docs/internal/updating-web-screenshots.md` names `docs/public/images/web/` as the screenshot destination, maps files to UI routes and doc consumers, and defines the refresh/verification workflow.
|
||||
- `lib/foundation/fabro-dev/src/commands/docs.rs` exposes `cargo dev docs refresh/check`; `docs_cli_reference.rs` and `docs_options_reference.rs` update only fenced regions of `docs/public/reference/cli.mdx` and `docs/public/reference/user-configuration.mdx`. The two whole files remain assigned here because substantial prose outside those fences is authored.
|
||||
- `test/docs/extract_dots.py` extracts workflow examples from the public docs for validation.
|
||||
- **Assigned count:** **112**: 110 public-site files after the API contract, changelog, and 22 generated SVGs are removed, plus `README.md` and the screenshot-maintenance guide.
|
||||
|
||||
### `public-release-history` — Published changelog
|
||||
|
||||
- **Purpose:** Preserve and publish dated user-facing release/change records independently of current reference documentation.
|
||||
- **Globs:** `docs/public/changelog/**`
|
||||
- **Entry points:** `docs/public/docs.json` changelog navigation; newest page at the assessed revision is `docs/public/changelog/2026-07-25.mdx`.
|
||||
- **Owns:** dated titles, migration warnings, feature summaries, and historical behavior notes.
|
||||
- **Depends on candidates:** `public-documentation` for Mintlify navigation/presentation.
|
||||
- **Evidence:**
|
||||
- `docs/public/docs.json` gives changelog its own top-level tab and lists every dated page.
|
||||
- The 120 `docs.json` changelog page entries exactly match the 120 tracked MDX files.
|
||||
- Each page has date/title frontmatter and describes changes for that date.
|
||||
- `lib/apps/fabro-server/tests/it/api/docs.rs:45-50` deliberately reads a changelog page as historical documentation.
|
||||
- **Assigned count:** **120**.
|
||||
|
||||
### `fabro-http-api-contract` — Fabro HTTP API contract
|
||||
|
||||
- **Purpose:** Define the OpenAPI-first wire contract used by the server, generated clients/types, conformance tests, and published API reference.
|
||||
- **Globs:** `docs/public/api-reference/fabro-api.yaml`
|
||||
- **Entry points:** `docs/public/api-reference/fabro-api.yaml`
|
||||
- **Owns:** HTTP routes, request/response schemas, authentication declarations, and API-facing wire documentation.
|
||||
- **Depends on candidates:** none at the documentation layer; parent reconciliation should make its consumers depend on this component.
|
||||
- **Consumers / evidence:**
|
||||
- `AGENTS.md:55-61` explicitly calls this file the source of truth and documents the Rust and TypeScript regeneration workflow.
|
||||
- `lib/foundation/fabro-api/build.rs:159` consumes it for Rust generation.
|
||||
- `lib/packages/fabro-api-client/package.json:7` consumes it for TypeScript Axios generation.
|
||||
- `lib/apps/fabro-server/src/server/handler/system.rs:694` embeds it in the server.
|
||||
- `lib/apps/fabro-server/tests/it/openapi_conformance.rs:21` reads it for route/spec conformance.
|
||||
- `docs/public/docs.json` points Mintlify's API tab at it.
|
||||
- **Assigned count:** **1**.
|
||||
|
||||
### `documentation-demo-workflows` — Executable documentation demos
|
||||
|
||||
- **Purpose:** Provide runnable workflow definitions and supporting configuration/prompts used by public tutorials and demonstrations.
|
||||
- **Globs:**
|
||||
- `docs/internal/demo/*.fabro`
|
||||
- `docs/internal/demo/*.toml`
|
||||
- `docs/internal/demo/prompts/**`
|
||||
- **Exclude globs:**
|
||||
- `docs/internal/demo/*.svg`
|
||||
- `docs/internal/demo/*.png`
|
||||
- **Entry points:**
|
||||
- `docs/internal/demo/01-hello.fabro`
|
||||
- `docs/internal/demo/14-search-imagegen.toml`
|
||||
- tutorial commands of the form `fabro run docs/internal/demo/<name>.fabro`
|
||||
- **Owns:** small executable example graphs, the image-generation demo run config, and shared demo prompt text.
|
||||
- **Depends on candidates:** CLI runner, workflow engine/validator, agent tools, and configured sandbox/model providers.
|
||||
- **Evidence:**
|
||||
- Public tutorials such as `docs/public/tutorials/hello-world.mdx`, `parallel-review.mdx`, `multi-model.mdx`, `plan-implement.mdx`, and `ensemble.mdx` invoke these paths directly.
|
||||
- `docs/public/core-concepts/models.mdx:250-251` also uses these graphs as runnable model examples.
|
||||
- `docs/internal/demo/14-search-imagegen.toml` selects its graph, Daytona environment, snapshot, and output assets.
|
||||
- `.fabro` files are complete Graphviz workflow entry documents with `goal`, start, and exit nodes.
|
||||
- **Assigned count:** **16** (14 `.fabro`, one `.toml`, one prompt).
|
||||
|
||||
### `internal-engineering-guidance` — Active engineering policies and architecture references
|
||||
|
||||
- **Purpose:** Record active repository-wide engineering policies and maintained architectural/runtime contracts that guide implementation changes.
|
||||
- **Globs:**
|
||||
- `docs/internal/*-strategy.md`
|
||||
- `docs/internal/*-policy.md`
|
||||
- `docs/internal/events.md`
|
||||
- `docs/internal/fabro-event-schema-v2-concrete-shape.md`
|
||||
- `docs/internal/llm-client-resolution.md`
|
||||
- `docs/internal/run-directory-keys.md`
|
||||
- **Entry points:**
|
||||
- `AGENTS.md:136-146`
|
||||
- `docs/internal/events-strategy.md`
|
||||
- `docs/internal/testing-strategy.md`
|
||||
- `docs/internal/error-handling-strategy.md`
|
||||
- **Owns:**
|
||||
- logging, events, testing, migrations, secret handling, error handling, React-effect, and panic policies
|
||||
- the maintained event catalog and implemented V2 event design explanation
|
||||
- LLM client-resolution rules, parallel-execution semantics, and run scratch-file reference
|
||||
- **Depends on candidates:** the runtime, server, CLI, web, configuration/auth, and workflow components whose contracts it describes. These are documentation dependencies rather than build edges.
|
||||
- **Evidence:**
|
||||
- `AGENTS.md:136-146` makes seven strategy/policy documents mandatory reading before related changes.
|
||||
- `docs/internal/events-strategy.md` distinguishes durable product events from tracing and identifies their consumers.
|
||||
- `docs/internal/events.md` is the maintained serialized event catalog and was updated near the assessed revision.
|
||||
- `docs/internal/fabro-event-schema-v2-concrete-shape.md:5` says `Status: implemented`; it also says the hand-written Rust types, not this document, are the actual contract source of truth.
|
||||
- `docs/internal/parallel-strategy.md:3` says `Status: implemented` and was updated with the shared-checkout behavior at the assessed revision.
|
||||
- `lib/foundation/fabro-vault/src/store.rs:359` links implementation documentation back to `docs/internal/migrations-strategy.md`.
|
||||
- **Assigned count:** **13**.
|
||||
|
||||
### `product-context` — Internal product framing
|
||||
|
||||
- **Purpose:** Maintain concise product intent, audience, current shape, success signals, and stable technical/product constraints.
|
||||
- **Globs:** `docs/internal/product/**`
|
||||
- **Entry points:**
|
||||
- `docs/internal/product/product-description.md`
|
||||
- `docs/internal/product/current-state.md`
|
||||
- **Owns:** business problem, personas, product description, current-state snapshot, success metrics, and product-level technical requirements.
|
||||
- **Depends on candidates:** none as a build edge; it informs product and documentation work across the repository.
|
||||
- **Evidence:**
|
||||
- The six documents have complementary named roles rather than dated implementation tasks.
|
||||
- `docs/internal/product/current-state.md` explicitly describes a deliberately brief current product snapshot.
|
||||
- `docs/internal/product/technical-requirements.md` explicitly calls its contents stable constraints product changes should respect.
|
||||
- **Assigned count:** **6**.
|
||||
|
||||
## Cross-scope assignment
|
||||
|
||||
### `install.md` -> marketing-site component
|
||||
|
||||
- **Count:** **1**.
|
||||
- `install.md` is a tracked mode-`120000` symlink to `apps/marketing/public/install.md`.
|
||||
- Commit `0cc02c294dac23e3ace7646528431e758e37eea1` states that Vercel deploys the marketing subtree, so the real file lives there and the repository-root path is a symlink.
|
||||
- `apps/marketing/src/pages/index.astro` advertises `https://fabro.sh/install.md`.
|
||||
- The root alias should therefore be claimed by the component that owns `apps/marketing/public/install.md`, rather than by `public-documentation`.
|
||||
|
||||
## Evidence-backed exclusions
|
||||
|
||||
### Historical brainstorm, plan, audit, and design records — 159 files
|
||||
|
||||
These are point-in-time requirements, ideation, implementation plans, handoffs, one-time QA instructions, measurements, audits, or superseded proposals. They remain useful history but are not active source contracts or maintained policy components.
|
||||
|
||||
| Glob/path | Count | Evidence |
|
||||
| --- | ---: | --- |
|
||||
| `docs/brainstorms/**` | 11 | Dated `*-requirements.md` brainstorm artifacts. |
|
||||
| `docs/ideation/**` | 3 | Dated ideation records. |
|
||||
| `docs/plans/**` | 88 | Dated implementation plans and handoffs. |
|
||||
| `docs/superpowers/plans/**` | 45 | Dated execution plans. |
|
||||
| `docs/superpowers/specs/**` | 4 | Dated feature/design specs. |
|
||||
| `docs/internal/cargo-target-apfs-churn-plan.md` | 1 | Checkbox execution plan with an unfilled results section. |
|
||||
| `docs/internal/cli-workflow-coupling-audit.md` | 1 | Snapshot audit organized around completed and remaining couplings. |
|
||||
| `docs/internal/event-schema-competitive-analysis.md` | 1 | Dated comparative research report. |
|
||||
| `docs/internal/fabro-event-schema-v2-proposal.md` | 1 | Explicit `Status: proposal`; the implemented concrete-shape document supersedes its framing. |
|
||||
| `docs/internal/mcp-server-qa-test-plan.md` | 1 | Explicitly says it is a one-time manual QA pass, not a reusable testing template. |
|
||||
| `docs/internal/plan-events-as-source-of-truth-follow-ups.md` | 1 | Prerequisite implementation plan. |
|
||||
| `docs/internal/plan-events-as-source-of-truth.md` | 1 | Implementation plan/summary rather than current contract reference. |
|
||||
| `docs/internal/slow-test-opportunities-2026-04-07.md` | 1 | Dated measurement dataset and implementation-status record. |
|
||||
|
||||
This exclusion does **not** include `docs/public/changelog/**`: the changelog is a live, complete Mintlify publication surface and is mapped as its own component.
|
||||
|
||||
### Generated Graphviz renderings — 44 files
|
||||
|
||||
| Glob/path | Unique count | Evidence |
|
||||
| --- | ---: | --- |
|
||||
| `docs/internal/demo/*.svg` | 11 | Every file contains `Generated by graphviz`; each has a same-stem `.fabro` source. |
|
||||
| `docs/internal/demo/*.png` | 11 | Same-stem raster renderings were introduced alongside the `.fabro` and generated SVG files; their pixel dimensions match the SVG point dimensions at Graphviz's 96-DPI raster scale. |
|
||||
| `docs/public/images/*-workflow.svg` | 9 | Every matching tracked file contains `Generated by graphviz`. |
|
||||
| `docs/public/images/tutorial-*.svg` | 10 | Every matching tracked file contains `Generated by graphviz`; one file overlaps the previous glob. |
|
||||
| `docs/public/images/brave-search-research.svg` | 1 | Contains `Generated by graphviz`. |
|
||||
| `docs/public/images/how-fabro-works.svg` | 1 | Contains `Generated by graphviz`. |
|
||||
| `docs/public/images/nlspec-conformance.svg` | 1 | Contains `Generated by graphviz`. |
|
||||
| `docs/public/images/plan-implement-readme.svg` | 1 | Contains `Generated by graphviz`. |
|
||||
|
||||
The public SVG rows resolve to **22 unique files** because `tutorial-sub-workflow.svg` matches both broad globs. Curated UI screenshots and hand-authored SVG illustrations remain assigned to `public-documentation`; `docs/internal/updating-web-screenshots.md` establishes their manual capture and verification workflow.
|
||||
|
||||
The fenced regions in `docs/public/reference/cli.mdx` and `docs/public/reference/user-configuration.mdx` are generated, but the files are mixed authored/generated documents. Cartography operates at file granularity, so both whole files stay assigned to `public-documentation`.
|
||||
|
||||
### Vendored third-party legal text — 1 file
|
||||
|
||||
- **Glob:** `docs/internal/licenses/graphviz-14.1.5-LICENSE`
|
||||
- **Count:** **1**.
|
||||
- **Evidence:** the filename pins Graphviz 14.1.5, the contents are the verbatim Eclipse Public License 2.0 plus secondary-license text, and the introducing commit is `chore: add vendored Graphviz license to docs-internal/licenses`.
|
||||
|
||||
## Unmapped files
|
||||
|
||||
- **Glob:** `docs/internal/assets/**`
|
||||
- **Count:** **15**.
|
||||
- These form a coherent collection of logos, palette mockups, headers, and HTML/PNG social-card pairs, but no tracked file consumes these exact paths at the assessed revision.
|
||||
- `docs/internal/updating-web-screenshots.md` identifies `docs/public/logo/dark.svg` and `docs/public/logo/light.svg`, not the internal assets, as the source-of-truth logos.
|
||||
- The collection has no manifest, status marker, or documented update workflow establishing whether it is maintained brand source, derived output, or historical design collateral. It should remain unmapped until that ownership is confirmed.
|
||||
|
||||
## Coverage
|
||||
|
||||
| Disposition | Count |
|
||||
| --- | ---: |
|
||||
| Assigned to proposed documentation components | 268 |
|
||||
| Cross-scope assignment (`install.md` to marketing site) | 1 |
|
||||
| **Assigned total** | **269** |
|
||||
| Excluded historical records | 159 |
|
||||
| Excluded generated renderings | 44 |
|
||||
| Excluded vendored license | 1 |
|
||||
| **Excluded total** | **204** |
|
||||
| Unmapped internal brand collateral | 15 |
|
||||
| **Scoped relevant total** | **488** |
|
||||
|
||||
`269 + 204 + 15 = 488`; every scoped tracked file is assigned, excluded, or explicitly unmapped.
|
||||
|
||||
## Open questions
|
||||
|
||||
1. Are the 15 files under `docs/internal/assets/**` maintained brand sources, or intentionally retained historical collateral? A component should be added only if an owner/update workflow confirms the former.
|
||||
2. Should the parent map keep `docs/internal/fabro-event-schema-v2-concrete-shape.md` in active engineering guidance, as proposed here based on `Status: implemented` and recent updates, or treat it as an implemented design record now that Rust event types and `events.md` carry the live contract?
|
||||
3. Confirm the final marketing component ID that will claim the `install.md` symlink together with `apps/marketing/public/install.md`.
|
||||
|
|
@ -1,461 +0,0 @@
|
|||
# Repository operations cartography scout
|
||||
|
||||
Assessed revision:
|
||||
`2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`).
|
||||
|
||||
Owned scope: root-level tracked files plus tracked files under `.ai/**`,
|
||||
`.cargo/**`, `.claude/**`, `.config/**`, `.fabro/**`, `.github/**`,
|
||||
`bin/**`, `docker/**`, and `installer/**`. Files under `lib/**`, `apps/**`,
|
||||
`docs/**`, `test/**`, and `evals/**` were not counted. The
|
||||
`lib/foundation/fabro-dev/**` and `lib/foundation/build-support/**` trees were
|
||||
consulted only as boundary and dependency evidence because the foundation
|
||||
scout owns them.
|
||||
|
||||
Applicable instructions read: `AGENTS.md`, its `CLAUDE.md` symlink, and
|
||||
`CONTRIBUTING.md`.
|
||||
|
||||
## Inventory and boundary approach
|
||||
|
||||
- `git ls-tree -r --name-only` at the assessed revision yields exactly 143
|
||||
tracked files in this scope: 24 root files, four under `.ai/`, one under
|
||||
`.cargo/`, eight under `.claude/`, one under `.config/`, 87 under `.fabro/`,
|
||||
seven under `.github/`, one under `bin/`, eight under `docker/`, and two
|
||||
under `installer/`.
|
||||
- Repository-wide manifests, tool configuration, and contributor rules are
|
||||
grouped as one development-policy component. They form the shared contract
|
||||
used by Cargo, Bun, nextest, rustfmt, Clippy, contributors, coding agents,
|
||||
and CI; splitting every configuration file would create small boundaries
|
||||
without independent entry points.
|
||||
- Pull-request CI and release automation are separate. The former validates
|
||||
changes on branch events, while the latter owns version tags and publication
|
||||
of binary, container, GitHub Release, and Homebrew artifacts.
|
||||
- Product container packaging and operator Compose deployment are grouped
|
||||
because the image layout, entrypoint, runtime environment, proxy files, and
|
||||
Compose stacks share one deployable artifact contract. The explicit
|
||||
split-web proof-of-concept is retained in this proposed component, with the
|
||||
question noted below.
|
||||
- `.fabro/project.toml`, its development image, and the named workflow catalog
|
||||
are grouped as the repository's Fabro-native automation surface. They share
|
||||
the `fabro run <name>` consumer, project defaults, clone-based execution
|
||||
environment, and repository-maintenance lifecycle.
|
||||
- The smaller `.ai`, `.claude`, and `bin/agent` families are grouped as coding
|
||||
agent automation. Their clients differ, but all supply repository-local
|
||||
prompts, skills, hooks, or helper commands to agents working on this
|
||||
repository.
|
||||
- Machine-produced state, a backup, vendored policy text, non-runtime review
|
||||
assets, legal/overview metadata, and canonical-file symlink aliases are
|
||||
excluded with exact counts below.
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `repository-development-policy` — Repository development policy
|
||||
|
||||
- **Assigned file count:** 11
|
||||
- **Purpose:** Defines the repository-wide Rust and JavaScript workspace,
|
||||
dependency, formatting, lint, test, version-control, contributor, and coding
|
||||
agent development contract.
|
||||
- **Globs:**
|
||||
- `.cargo/**`
|
||||
- `.config/**`
|
||||
- `.gitattributes`
|
||||
- `.gitignore`
|
||||
- `AGENTS.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- `Cargo.toml`
|
||||
- `package.json`
|
||||
- `bunfig.toml`
|
||||
- `clippy.toml`
|
||||
- `rustfmt.toml`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `Cargo.toml:[workspace]`
|
||||
- `Cargo.toml:[workspace.dependencies]`
|
||||
- `Cargo.toml:[workspace.lints]`
|
||||
- `package.json:workspaces`
|
||||
- `.cargo/config.toml:[alias]`
|
||||
- `.config/nextest.toml`
|
||||
- `AGENTS.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- **Owns:** Rust and Bun workspace membership; shared Rust dependency and
|
||||
version policy; workspace lint and compilation profiles; Bun linker
|
||||
selection; Cargo developer aliases and test proxy policy; nextest timeout
|
||||
profiles; rustfmt and Clippy policy; tracked/generated path treatment; and
|
||||
repository-wide contributor and agent instructions.
|
||||
- **Depends-on candidates:** `fabro-build-tooling` (the `cargo dev` alias
|
||||
dispatches to its feature-gated binary).
|
||||
- **Evidence:**
|
||||
- `Cargo.toml` — declares all Rust workspace members, default members,
|
||||
workspace package metadata, shared dependencies, lint policy, and build
|
||||
profiles.
|
||||
- `package.json` and `bunfig.toml` — declare the JavaScript workspace and
|
||||
deterministic Bun workspace linker contract.
|
||||
- `.cargo/config.toml` — exposes `cargo dev` as the CLI entry to
|
||||
`fabro-dev`, defines the test alias, and supplies the repository test
|
||||
proxy-policy environment.
|
||||
- `.config/nextest.toml`, `clippy.toml`, and `rustfmt.toml` — are direct
|
||||
configuration inputs to the repository's test, lint, and formatting
|
||||
commands.
|
||||
- `AGENTS.md` and `CONTRIBUTING.md` — define the repository-wide build/test
|
||||
commands, architectural policies, and contribution workflow.
|
||||
- `.gitattributes` and `.gitignore` — actively define generated-file
|
||||
classification and the source/output boundary used by developers and CI.
|
||||
- `lib/foundation/fabro-dev/Cargo.toml` and
|
||||
`lib/foundation/fabro-dev/src/lib.rs:Command` — out-of-scope evidence that
|
||||
the Cargo alias targets a distinct internal development CLI.
|
||||
|
||||
### `repository-ci` — Pull-request and branch continuous integration
|
||||
|
||||
- **Assigned file count:** 3
|
||||
- **Purpose:** Runs branch and pull-request validation for the Rust and
|
||||
TypeScript workspaces and configures static validation of GitHub Actions
|
||||
workflows.
|
||||
- **Globs:**
|
||||
- `.github/workflows/rust.yml`
|
||||
- `.github/workflows/typescript.yml`
|
||||
- `.github/zizmor.yml`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `.github/workflows/rust.yml`
|
||||
- `.github/workflows/typescript.yml`
|
||||
- `.github/zizmor.yml`
|
||||
- **Owns:** branch/path trigger policy; Rust format, lint, generated-doc, test,
|
||||
and twin-E2E jobs; TypeScript typecheck, test, and production-build jobs;
|
||||
concurrency cancellation; CI test profile selection; and repository-local
|
||||
workflow-linter exceptions.
|
||||
- **Depends-on candidates:** `repository-development-policy`,
|
||||
`fabro-build-tooling`, `fabro-web-app`,
|
||||
`fabro-api-client-generation`, and `twin-openai`. The workflows are also
|
||||
integration consumers of the full Rust workspace rather than a production
|
||||
runtime dependency of each Rust component.
|
||||
- **Evidence:**
|
||||
- `.github/workflows/rust.yml` — path-gates Rust-relevant changes and runs
|
||||
the pinned formatter, Clippy, generated-document check, workspace nextest
|
||||
suite, and selected twin-mode E2E packages.
|
||||
- `.github/workflows/typescript.yml` — installs the frozen Bun workspace,
|
||||
typechecks the web app and generated-client package, runs web tests, and
|
||||
invokes `cargo dev build` for the release-style embedded-SPA build.
|
||||
- `.github/zizmor.yml` — is consumed alongside those workflows and names
|
||||
workflow-specific action-reference exceptions.
|
||||
- `lib/foundation/fabro-dev/src/commands/build.rs` — out-of-scope evidence
|
||||
that `cargo dev build` refreshes the SPA and then forwards to Cargo build.
|
||||
|
||||
### `release-distribution-automation` — Release and package publication
|
||||
|
||||
- **Assigned file count:** 4
|
||||
- **Purpose:** Cuts nightly releases and publishes versioned CLI archives,
|
||||
GitHub Releases, multi-architecture container images, attestations, and
|
||||
stable/nightly Homebrew formulas.
|
||||
- **Globs:**
|
||||
- `.github/workflows/nightly.yml`
|
||||
- `.github/workflows/release.yml`
|
||||
- `installer/**`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `.github/workflows/nightly.yml`
|
||||
- `.github/workflows/release.yml`
|
||||
- `installer/fabro.rb.template`
|
||||
- `installer/fabro-nightly.rb.template`
|
||||
- **Owns:** scheduled nightly tag creation; cross-platform release target
|
||||
matrix; CLI archive/checksum generation; provenance attestations; GitHub
|
||||
Release creation; release container publication; stable and nightly release
|
||||
channel selection; and Homebrew formula template substitution/publication.
|
||||
- **Depends-on candidates:** `repository-development-policy`,
|
||||
`fabro-build-tooling`, `container-packaging-and-deployment`, `fabro-cli`,
|
||||
and `fabro-spa`.
|
||||
- **Evidence:**
|
||||
- `.github/workflows/nightly.yml` — mints the release-app token and invokes
|
||||
`cargo --locked dev release --nightly` after ensuring the current commit
|
||||
does not already have a nightly tag.
|
||||
- `.github/workflows/release.yml` — is triggered by version tags, compiles
|
||||
and packages five targets, attests archives and container images, creates
|
||||
the GitHub Release, publishes the multi-architecture image, and updates
|
||||
stable or nightly Homebrew formulas.
|
||||
- `installer/fabro.rb.template` and
|
||||
`installer/fabro-nightly.rb.template` — define the platform archive URLs,
|
||||
checksum placeholders, installed binary, and Homebrew smoke test consumed
|
||||
by the release workflow.
|
||||
- `lib/foundation/fabro-dev/src/commands/release.rs` — out-of-scope evidence
|
||||
that the developer CLI owns release version computation, test smoke,
|
||||
`Cargo.toml`/`Cargo.lock` update, commit, tag, and push before the tag
|
||||
workflow publishes artifacts.
|
||||
- `lib/foundation/fabro-dev/src/commands/docker_build.rs` — out-of-scope
|
||||
evidence that local image construction intentionally shares the release
|
||||
pipeline's `tmp/docker-context/<arch>/fabro` layout.
|
||||
|
||||
### `container-packaging-and-deployment` — Container packaging and deployment
|
||||
|
||||
- **Assigned file count:** 16
|
||||
- **Purpose:** Packages the Fabro CLI/server as a runtime container and
|
||||
defines supported local, production, Tailscale, and split-web Compose
|
||||
deployments around that image.
|
||||
- **Globs:**
|
||||
- `.dockerignore`
|
||||
- `.env.example`
|
||||
- `Dockerfile`
|
||||
- `docker-compose*.yaml`
|
||||
- `docker/**`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `Dockerfile`
|
||||
- `docker/entrypoint.sh`
|
||||
- `docker/preflight.sh`
|
||||
- `docker-compose.yaml`
|
||||
- `docker-compose.prod.yaml`
|
||||
- `docker-compose.tailscale.yaml`
|
||||
- `docker-compose.split-web.yaml`
|
||||
- **Owns:** staged multi-architecture binary image layout; runtime package and
|
||||
unprivileged-user setup; storage-home and Docker-socket group handoff;
|
||||
deployment environment contract; preflight resource/daemon/network checks;
|
||||
Caddy proxy/TLS behavior; Compose services, volumes, ports, and health
|
||||
checks; and the split static-web/API deployment configuration.
|
||||
- **Depends-on candidates:** `fabro-cli`, `fabro-server`, `fabro-web-app`, and
|
||||
`fabro-build-tooling`.
|
||||
- **Evidence:**
|
||||
- `Dockerfile` — consumes the architecture-specific binary staged under
|
||||
`tmp/docker-context`, installs runtime dependencies, and installs the
|
||||
shared entrypoint.
|
||||
- `docker/entrypoint.sh` — owns storage permissions, Docker socket group
|
||||
mapping, and privilege drop before launching Fabro.
|
||||
- `docker/preflight.sh` — is a standalone deployment readiness entry point
|
||||
for Docker version/daemon, Compose, CPU, memory, disk, port, and registry
|
||||
reachability.
|
||||
- `docker-compose.yaml`, `docker-compose.local.yaml`,
|
||||
`docker-compose.prod.yaml`, and `docker-compose.tailscale.yaml` — define
|
||||
distinct operator compositions around the same Fabro image and runtime
|
||||
state.
|
||||
- `docker-compose.split-web.yaml` and `docker/split-web/**` — jointly own the
|
||||
alternate edge/API/static-web composition; the local README documents its
|
||||
request ownership and validation commands.
|
||||
- `.github/workflows/release.yml` and
|
||||
`lib/foundation/fabro-dev/src/commands/docker_build.rs` — release and local
|
||||
developer consumers both stage the same per-architecture context consumed
|
||||
by the root Dockerfile.
|
||||
|
||||
### `fabro-repository-automation` — Fabro-native repository automation
|
||||
|
||||
- **Assigned file count:** 41
|
||||
- **Purpose:** Configures Fabro's own development environment and supplies the
|
||||
named workflow graphs, prompts, permissions, and project defaults used for
|
||||
repository maintenance, integration demonstrations, and workflow examples.
|
||||
- **Globs:**
|
||||
- `.fabro/Dockerfile`
|
||||
- `.fabro/project.toml`
|
||||
- `.fabro/workflows/**`
|
||||
- **Exclude globs:**
|
||||
- `.fabro/workflows/goal/workflow.svg`
|
||||
- **Entry points:**
|
||||
- `.fabro/project.toml`
|
||||
- `.fabro/workflows/*/workflow.toml`
|
||||
- `.fabro/workflows/*/workflow.fabro`
|
||||
- `.fabro/workflows/implement-plan/workflow.fabro`
|
||||
- `.fabro/workflows/patch-cves/workflow.fabro`
|
||||
- `.fabro/workflows/pr-simplify/workflow.fabro`
|
||||
- `.fabro/workflows/smoke/workflow.fabro`
|
||||
- **Owns:** repository-level pull-request defaults; the `fabro-dev` Daytona
|
||||
environment and resource/lifecycle labels; its browser-capable Rust/Bun
|
||||
development image; named workflow graph catalog; workflow-local prompts;
|
||||
GitHub integration permissions; and repository verification/maintenance
|
||||
command sequences.
|
||||
- **Depends-on candidates:** `fabro-cli`, `fabro-config`, `fabro-workflow`,
|
||||
`fabro-graphviz`, `fabro-sandbox`, `fabro-github`,
|
||||
`fabro-build-tooling`, and `repository-development-policy`.
|
||||
- **Evidence:**
|
||||
- `.fabro/project.toml` — is the project-level Fabro configuration entry,
|
||||
selecting the Daytona environment, `.fabro/Dockerfile`, resource limits,
|
||||
lifecycle, labels, and pull-request defaults.
|
||||
- `.fabro/Dockerfile` — supplies the clone-based workflow environment with
|
||||
Git, ripgrep, browser/desktop support, GitHub CLI, pinned Rust tooling,
|
||||
nextest, and Bun.
|
||||
- `.fabro/workflows/*/workflow.toml` — provides per-workflow graph selection,
|
||||
environment overrides, pull-request behavior, and GitHub token
|
||||
permissions.
|
||||
- `.fabro/workflows/*/workflow.fabro` — provides independently runnable
|
||||
Graphviz workflow entries for demos, human interaction, GitHub
|
||||
operations, implementation, verification, maintenance, and smoke tests.
|
||||
- `.fabro/workflows/implement-plan/workflow.fabro` — invokes the
|
||||
repository's Cargo/Bun verification contract and `cargo dev` generated-doc
|
||||
and SPA lifecycle, tying maintenance workflows to the same developer
|
||||
tooling as CI.
|
||||
- `.fabro/workflows/patch-cves/**` and
|
||||
`.fabro/workflows/pr-simplify/**` — pair bundled prompts with the explicit
|
||||
GitHub permissions and pull-request behavior needed by repository
|
||||
maintenance runs.
|
||||
- `AGENTS.md` — documents `fabro run <name>` as resolving
|
||||
`.fabro/workflows/<name>/workflow.toml`, establishing the catalog's common
|
||||
consumer.
|
||||
|
||||
### `coding-agent-automation` — Repository coding-agent automation
|
||||
|
||||
- **Assigned file count:** 11
|
||||
- **Purpose:** Supplies repository-local code-review prompts, documentation
|
||||
and changelog skills, edit hooks, and an image-generation helper to external
|
||||
coding-agent clients.
|
||||
- **Globs:**
|
||||
- `.ai/prompts/**`
|
||||
- `.claude/settings.json`
|
||||
- `.claude/skills/**`
|
||||
- `bin/agent/**`
|
||||
- **Exclude globs:**
|
||||
- `.claude/skills/*/watermark`
|
||||
- **Entry points:**
|
||||
- `.ai/prompts/code-review-fast.md`
|
||||
- `.ai/prompts/code-review-deep-1.md`
|
||||
- `.claude/skills/changelog/SKILL.md`
|
||||
- `.claude/skills/docs/SKILL.md`
|
||||
- `.claude/settings.json`
|
||||
- `bin/agent/imagegen`
|
||||
- **Owns:** fast and multi-stage deep code-review orchestration prompts;
|
||||
changelog selection and MDX formatting procedure; code-to-documentation
|
||||
mapping and update procedure; post-edit Rust formatting hook; and the
|
||||
command-line Gemini image request/output flow.
|
||||
- **Depends-on candidates:** `public-documentation` and
|
||||
`public-release-history` are data/format consumers of the two skills; the
|
||||
remaining prompts and helper use external agent, GitHub CLI, Git, and Gemini
|
||||
interfaces rather than product runtime components.
|
||||
- **Evidence:**
|
||||
- `.ai/prompts/code-review-deep-{1,2,3}.md` — define a three-artifact review
|
||||
pipeline from candidate discovery through analysis and false-positive
|
||||
filtering.
|
||||
- `.ai/prompts/code-review-fast.md` — defines pull-request eligibility,
|
||||
parallel review/confidence filtering, and the GitHub comment output
|
||||
contract.
|
||||
- `.claude/skills/changelog/SKILL.md` and its references — define the
|
||||
Git-history-to-Mintlify changelog workflow and output format.
|
||||
- `.claude/skills/docs/SKILL.md` and its mapping reference — define the
|
||||
Git-history-to-public-doc update workflow and map implementation paths to
|
||||
published documentation pages.
|
||||
- `.claude/settings.json` — registers the repository-local post-edit Rust
|
||||
formatting hook.
|
||||
- `bin/agent/imagegen` — is an executable helper that loads repository
|
||||
environment credentials, calls the Gemini image endpoint, and writes the
|
||||
decoded image.
|
||||
|
||||
## Evidence-backed exclusions
|
||||
|
||||
### Vendored Rust style-guide skill
|
||||
|
||||
- **Glob:** `.fabro/skills/rust-style-guide/**`
|
||||
- **Count:** 44 tracked files.
|
||||
- **Reason/evidence:** Commit `9af0296469b902c9780a983dee5bee07b0abbcdf`
|
||||
explicitly records all 44 files as vendored from
|
||||
`brynary/rust-style-guide` commit `8fd2a4f`, trimmed to the runtime skill
|
||||
payload. The files are copied policy/procedure content rather than authored
|
||||
implementation owned by this repository. The skill entry point also routes
|
||||
readers across the copied `guidelines/**` and `workflows/**` payload.
|
||||
|
||||
### Dependency resolution outputs
|
||||
|
||||
- **Paths:** `Cargo.lock`, `bun.lock`
|
||||
- **Count:** two tracked files.
|
||||
- **Reason/evidence:** These are machine-maintained dependency resolution
|
||||
snapshots. `lib/foundation/fabro-dev/src/commands/release.rs` explicitly
|
||||
runs `cargo update --workspace` and stages `Cargo.lock`, while all CI/release
|
||||
consumers use Cargo `--locked` or Bun `--frozen-lockfile`; the manifests and
|
||||
policies that generate and consume them remain assigned.
|
||||
|
||||
### Skill watermarks
|
||||
|
||||
- **Glob:** `.claude/skills/*/watermark`
|
||||
- **Count:** two tracked files.
|
||||
- **Reason/evidence:** Each file is a commit SHA used as generated progress
|
||||
state. `.claude/skills/changelog/SKILL.md` and
|
||||
`.claude/skills/docs/SKILL.md` each explicitly instruct their workflow to
|
||||
overwrite its watermark with `git rev-parse HEAD`.
|
||||
|
||||
### Project configuration backup
|
||||
|
||||
- **Path:** `.fabro/project.toml.bak`
|
||||
- **Count:** one tracked file.
|
||||
- **Reason/evidence:** The `.bak` file preserves the previous inline
|
||||
`[run.sandbox.daytona]`/snapshot configuration, while
|
||||
`.fabro/project.toml` is the canonical current project configuration and
|
||||
points to the separate `.fabro/Dockerfile`.
|
||||
|
||||
### Non-runtime workflow and review assets
|
||||
|
||||
- **Paths:** `.fabro/workflows/goal/workflow.svg`, `.github/assets/**`
|
||||
- **Count:** three tracked files: one SVG workflow illustration and two PNG
|
||||
screenshots.
|
||||
- **Reason/evidence:** The goal workflow's runtime TOML points to
|
||||
`workflow.fabro`, not the SVG, and the SVG has no tracked runtime consumer.
|
||||
Commit `ac32963538f4441d40a47fcfcd868ca290d2b899` identifies the two PNGs as
|
||||
live screenshots captured for a web-feature pull request and says they are
|
||||
safe to remove from that change; no tracked source references them at the
|
||||
assessed revision.
|
||||
|
||||
### Canonical-file symlink aliases
|
||||
|
||||
- **Paths:** `CLAUDE.md`, `install.sh`, `install.md`
|
||||
- **Count:** three tracked symlinks.
|
||||
- **Reason/evidence:** Git records each with mode `120000`. Their targets are
|
||||
`AGENTS.md`, `apps/marketing/public/install.sh`, and
|
||||
`apps/marketing/public/install.md`, respectively. The canonical instruction
|
||||
file is assigned above, while the canonical install resources are owned by
|
||||
the web scout's `fabro-marketing-site`; excluding aliases prevents the same
|
||||
content from being assessed twice.
|
||||
|
||||
### Root overview and legal metadata
|
||||
|
||||
- **Paths:** `README.md`, `LICENSE.md`
|
||||
- **Count:** two tracked files.
|
||||
- **Reason/evidence:** `README.md` is the repository/product landing document
|
||||
and routes readers to the public installation and documentation surfaces;
|
||||
it does not define an independently executable or state-owning boundary.
|
||||
`LICENSE.md` is the repository's MIT legal text. Neither should form a
|
||||
quality-scored implementation component on its own.
|
||||
|
||||
## Coverage ledger
|
||||
|
||||
| Classification | Files |
|
||||
| --- | ---: |
|
||||
| `repository-development-policy` | 11 |
|
||||
| `repository-ci` | 3 |
|
||||
| `release-distribution-automation` | 4 |
|
||||
| `container-packaging-and-deployment` | 16 |
|
||||
| `fabro-repository-automation` | 41 |
|
||||
| `coding-agent-automation` | 11 |
|
||||
| Vendored Rust style-guide skill | 44 |
|
||||
| Dependency resolution outputs | 2 |
|
||||
| Skill watermarks | 2 |
|
||||
| Project configuration backup | 1 |
|
||||
| Non-runtime workflow and review assets | 3 |
|
||||
| Canonical-file symlink aliases | 3 |
|
||||
| Root overview and legal metadata | 2 |
|
||||
| **Total** | **143** |
|
||||
|
||||
Computed scope coverage:
|
||||
|
||||
- **Relevant tracked files:** 143
|
||||
- **Assigned to proposed components:** 86
|
||||
- **Excluded with evidence:** 57
|
||||
- **Unmapped:** 0
|
||||
|
||||
The component and exclusion patterns above were resolved against the assessed
|
||||
revision's `git ls-tree` inventory. They are disjoint, and
|
||||
`86 + 57 + 0 = 143`.
|
||||
|
||||
## Open boundary questions
|
||||
|
||||
1. Should `repository-development-policy` remain one repository-wide
|
||||
developer contract, or should the final map separate executable
|
||||
workspace/tool configuration from the contributor/agent governance in
|
||||
`AGENTS.md` and `CONTRIBUTING.md`?
|
||||
2. Should `container-packaging-and-deployment` split into an image-packaging
|
||||
component and an operator Compose-deployment component? The root
|
||||
`Dockerfile` has a release/local-build lifecycle, while the Compose/Caddy
|
||||
files own runtime topology, but both share the image and entrypoint
|
||||
contract.
|
||||
3. Should the explicitly named split-web proof-of-concept remain inside the
|
||||
container deployment component, become a separate experimental deployment
|
||||
component, or be excluded as non-production material?
|
||||
4. Should `.fabro/project.toml` and `.fabro/Dockerfile` remain with the named
|
||||
workflow catalog? They share the Fabro project/run consumer today, but the
|
||||
environment image and project defaults could change independently from
|
||||
individual graphs.
|
||||
5. Should the small `.ai`, `.claude`, and `bin/agent` families remain grouped
|
||||
as `coding-agent-automation`, or does the final map need separate
|
||||
review-automation and documentation-maintenance boundaries despite their
|
||||
small file counts?
|
||||
6. Should root `README.md` remain excluded as repository overview metadata,
|
||||
or should it be folded into the docs scout's `public-documentation`
|
||||
component even though it sits outside `docs/**`?
|
||||
|
|
@ -1,198 +0,0 @@
|
|||
# Independent cartography review
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`
|
||||
|
||||
Reviewed artifact:
|
||||
`.chisel/cartography/work/candidate-codebase-map.json`.
|
||||
|
||||
This review is limited to component boundaries, dependencies, evidence, and
|
||||
file disposition. It does not assess implementation quality.
|
||||
|
||||
## Independent inventory check
|
||||
|
||||
I resolved the fixed tree with `git ls-tree -r --name-only` and matched every
|
||||
component glob, component exclusion, global exclusion, and declared unmapped
|
||||
path independently of the candidate's renderer.
|
||||
|
||||
- Tracked files: **3,104**
|
||||
- Candidate claims: **2,256**
|
||||
- Candidate global exclusions: **848**
|
||||
- Candidate unmapped files: **0**
|
||||
- Files without a disposition: **0**
|
||||
- Files claimed by multiple components, or both claimed and globally excluded:
|
||||
**0**
|
||||
- Overlap between separate global-exclusion entries: **0**
|
||||
|
||||
The candidate's mechanical accounting is therefore correct as written.
|
||||
Component IDs are unique, all named dependencies resolve, all globs resolve,
|
||||
and every evidence/entry-point path exists in the fixed tree. A symbol-text
|
||||
check also found no missing Rust/TypeScript symbols among the qualified
|
||||
references; the one non-symbol qualifier is the valid JSON property reference
|
||||
`package.json:scripts.generate`.
|
||||
|
||||
Mechanical coverage does not settle whether each disposition or boundary is
|
||||
architecturally correct. The supported corrections below change the
|
||||
classification of 15 files but leave the total inventory unchanged.
|
||||
|
||||
## Supported corrections
|
||||
|
||||
### 1. Move `docs/internal/assets/**` from global exclusion to `unmapped_files`
|
||||
|
||||
All 15 files under `docs/internal/assets/**` are currently excluded because
|
||||
they have no tracked consumer or documented update workflow. That establishes
|
||||
that ownership is unresolved; it does not establish that the SVG, HTML, and
|
||||
raster files are generated, vendored, build output, or historical records.
|
||||
The candidate's own open question likewise asks whether they are maintained
|
||||
brand sources.
|
||||
|
||||
Until that question is answered, exclusion asserts more than the evidence
|
||||
supports. Preserve the open question and list the 15 exact tracked paths as
|
||||
unmapped. This changes coverage to **2,256 assigned, 833 excluded, 15
|
||||
unmapped**.
|
||||
|
||||
### 2. Restore `fabro-spa` as a separate component
|
||||
|
||||
`lib/apps/fabro-spa/Cargo.toml` declares an independent Rust package with the
|
||||
specific responsibility “Embedded production SPA assets for Fabro.”
|
||||
`lib/apps/fabro-spa/src/lib.rs` exposes the server-facing `get` and
|
||||
`AssetBytes` interface, owns compile-time embedding and hashes, and is consumed
|
||||
directly by `lib/apps/fabro-server/src/static_files.rs` and
|
||||
`lib/apps/fabro-server/src/csp.rs`.
|
||||
|
||||
Folding those two assigned files into `fabro-web-app` combines a browser
|
||||
application with a Rust server adapter that has a different entry point,
|
||||
consumer, toolchain, and reason to change. It also turns the precise dependency
|
||||
`fabro-server -> fabro-spa` into the over-broad
|
||||
`fabro-server -> fabro-web-app`.
|
||||
|
||||
Add a `fabro-spa` component for `lib/apps/fabro-spa/Cargo.toml` and
|
||||
`lib/apps/fabro-spa/src/**`; retain `lib/apps/fabro-spa/assets/**` as the
|
||||
evidence-backed generated-output exclusion. Remove those assigned paths from
|
||||
`fabro-web-app`, replace the server's web-app edge with
|
||||
`fabro-server -> fabro-spa`, and let the SPA refresh tooling express the
|
||||
build-time connection to the browser app.
|
||||
|
||||
The two-file size is not by itself a reason to hide this package: it has a
|
||||
manifest, public interface, owned compile-time lifecycle, and independent
|
||||
consumer boundary, the same kind of evidence used to retain other small Rust
|
||||
components in the candidate.
|
||||
|
||||
### 3. Separate `fabro-build-support` from `fabro-build-tooling`
|
||||
|
||||
`lib/foundation/build-support/Cargo.toml` is an independent package whose only
|
||||
responsibility is build-script Git/profile metadata.
|
||||
`lib/foundation/build-support/git_metadata.rs` exposes that public API, and
|
||||
the direct consumers are `lib/apps/fabro-cli/build.rs` and
|
||||
`lib/apps/fabro-server/build.rs`.
|
||||
|
||||
The remaining `fabro-dev` package is an executable repository-development CLI
|
||||
with SPA, documentation, release, benchmark, and container command
|
||||
lifecycles. Combining these packages hides shared compile-time infrastructure
|
||||
inside an unrelated command application; the candidate purpose has to join
|
||||
“runs repository ... automation” with “supplies compile-time Git metadata” to
|
||||
cover both.
|
||||
|
||||
Add a `fabro-build-support` component for
|
||||
`lib/foundation/build-support/**`. Keep `lib/foundation/fabro-dev/**`,
|
||||
`test/bin/release_test.sh`, and `test/analysis/bench-tests-diff.sql` in the
|
||||
existing development-tooling component. Add
|
||||
`fabro-cli -> fabro-build-support` and
|
||||
`fabro-server -> fabro-build-support`, which are explicit Cargo build
|
||||
dependencies.
|
||||
|
||||
### 4. Correct the shared fixture dependency direction
|
||||
|
||||
`workflow-test-corpus` is inert input data. The candidate evidence identifies
|
||||
the readers:
|
||||
|
||||
- `fabro-test` resolves files beneath `../../../test/`;
|
||||
- `fabro-cli` source/tests install the root and template fixtures;
|
||||
- `fabro-graphviz` and `fabro-validate` enumerate
|
||||
`test/dot-compatibility`;
|
||||
- `fabro-workflow` enumerates `test/attractor`.
|
||||
|
||||
Those consumers depend on the corpus, just as the generated API clients depend
|
||||
on their source contract. The candidate currently records the reverse and
|
||||
also names `fabro-template`, for which there is no direct corpus read.
|
||||
|
||||
Make `workflow-test-corpus.depends_on` empty, add
|
||||
`workflow-test-corpus` to the five direct consumer components above, and omit
|
||||
the unsupported `fabro-template` edge. This correction does not require
|
||||
redistributing the shared files.
|
||||
|
||||
### 5. Add direct operational dependencies omitted from
|
||||
`fabro-build-tooling`
|
||||
|
||||
The candidate's purpose and evidence include operations whose source contains
|
||||
explicit repository-component dependencies, but its dependency list contains
|
||||
only Cargo library dependencies:
|
||||
|
||||
- `docs_cli_reference.rs` invokes `fabro-cli` and writes
|
||||
`docs/public/reference/cli.mdx`;
|
||||
- `docs_options_reference.rs` writes the same public-documentation surface;
|
||||
- `spa_refresh.rs` invokes the build in `apps/fabro-web` and mirrors its output
|
||||
into `lib/apps/fabro-spa/assets`;
|
||||
- `docker_build.rs` runs the root container build;
|
||||
- `release.rs` reads and updates the root Cargo workspace contract.
|
||||
|
||||
Add dependencies from `fabro-build-tooling` to `fabro-cli`,
|
||||
`public-documentation`, `fabro-web-app`, the restored `fabro-spa`,
|
||||
`container-packaging-and-deployment`, and
|
||||
`repository-development-policy`. These are the same operational dependency
|
||||
kind already used for CI, release, repository-workflow, and documentation
|
||||
components; omitting them only for the development CLI makes the graph
|
||||
inconsistent.
|
||||
|
||||
### 6. Add `public-documentation -> public-release-history`
|
||||
|
||||
`docs/public/docs.json`, owned by `public-documentation`, enumerates every
|
||||
changelog page and gives the collection its top-level publication surface.
|
||||
The existing `public-release-history -> public-documentation` edge captures
|
||||
the changelog's dependence on Mintlify presentation, but it omits the direct
|
||||
navigation/configuration dependency in the other direction. Retain the
|
||||
existing edge and add the reciprocal edge.
|
||||
|
||||
## Optional boundary questions
|
||||
|
||||
These are plausible alternatives, but the fixed revision does not require
|
||||
them as corrections:
|
||||
|
||||
1. **First-run web installer.** The 14 install/mode files have a distinct
|
||||
router, reducer, API facade, storage token, and lifecycle, so a
|
||||
`fabro-web-install` component is supportable now; it does not need a
|
||||
separate binary entry point to qualify. On the other hand, it is selected
|
||||
by the shared browser entry and imports the app's common UI/runtime. For the
|
||||
recommended map, keep it in `fabro-web-app` and preserve this as an open
|
||||
boundary question. Splitting it would raise the component count by one.
|
||||
2. **Shared workflow corpus ownership.** Its cross-crate consumers justify the
|
||||
shared corpus component. Distributing the root/template, Attractor, and DOT
|
||||
compatibility subcorpora to their consumers is also possible, but would
|
||||
make the DOT corpus arbitrarily owned by one of two readers. Retain the
|
||||
shared component unless later assessment proves its combined boundary
|
||||
noisy.
|
||||
3. **Workflow, LLM, store, and server subcomponents.** The candidate's broad
|
||||
components have recognizable internal areas, but their crate facades,
|
||||
shared state, and integration lifecycles currently support the retained
|
||||
crate/service boundaries. No additional split is required at this
|
||||
revision.
|
||||
|
||||
No candidate component is supported for removal or merger. In particular, the
|
||||
single-file OpenAPI contract and the small MCP, evaluation, CI, and release
|
||||
components have independent source-of-truth, protocol, executable, or
|
||||
publication lifecycles that justify their granularity.
|
||||
|
||||
## Recommended disposition
|
||||
|
||||
Apply the two supported package splits and retain the optional boundaries as
|
||||
questions:
|
||||
|
||||
- **Recommended component count:** **70** (candidate 68, plus
|
||||
`fabro-spa` and `fabro-build-support`)
|
||||
- **Relevant tracked files:** **3,104**
|
||||
- **Assigned:** **2,256**
|
||||
- **Excluded:** **833**
|
||||
- **Unmapped:** **15** (`docs/internal/assets/**`, listed as exact paths)
|
||||
- **Overlap or uncovered files:** **0**
|
||||
|
||||
The counts satisfy `2,256 + 833 + 15 = 3,104`. The optional installer split
|
||||
would produce 71 components without changing coverage.
|
||||
|
|
@ -1,216 +0,0 @@
|
|||
# Rust Applications Cartography Scout
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
|
||||
|
||||
Scope: tracked files under `lib/apps/**`. Root `Cargo.toml`, `.gitignore`,
|
||||
`AGENTS.md`, and `CONTRIBUTING.md` were read only as workspace, exclusion, and
|
||||
repository-instruction evidence; they are not included in the scope counts.
|
||||
`CLAUDE.md` resolves to the same repository guidance as `AGENTS.md`.
|
||||
|
||||
The primary proposal is one component per Cargo application package. These
|
||||
boundaries are established by independent package manifests, binary or library
|
||||
entry points, public interfaces, package-owned lifecycle/state, package test
|
||||
suites, and explicit Cargo dependency edges. The CLI and server have broad
|
||||
module trees, but their entry points and tests converge on one executable or
|
||||
one shared server state/router respectively.
|
||||
|
||||
## Inventory and coverage
|
||||
|
||||
The inventory was computed with:
|
||||
|
||||
```text
|
||||
git ls-tree -r --name-only 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a -- lib/apps
|
||||
```
|
||||
|
||||
| Scope | Tracked | Assigned | Excluded | Unmapped |
|
||||
| --- | ---: | ---: | ---: | ---: |
|
||||
| `lib/apps/fabro-cli/**` | 241 | 241 | 0 | 0 |
|
||||
| `lib/apps/fabro-mcp-server/**` | 5 | 5 | 0 | 0 |
|
||||
| `lib/apps/fabro-server/**` | 112 | 112 | 0 | 0 |
|
||||
| `lib/apps/fabro-spa/**` | 3 | 2 | 1 | 0 |
|
||||
| **Total** | **361** | **360** | **1** | **0** |
|
||||
|
||||
The one excluded tracked file is
|
||||
`lib/apps/fabro-spa/assets/.gitkeep`. `AGENTS.md` states that embedded SPA
|
||||
assets are refreshed build output and are gitignored except for `.gitkeep`;
|
||||
`.gitignore` corroborates this with `lib/apps/fabro-spa/assets/*` and the
|
||||
explicit `.gitkeep` exception. The placeholder is therefore excluded as
|
||||
evidence of a generated build-output directory. No generated code, vendored
|
||||
code, dependency trees, or other build output is tracked elsewhere in this
|
||||
scope.
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `fabro-cli` — Fabro CLI Application
|
||||
|
||||
- **Purpose:** Provides the `fabro` command-line application, including command parsing and dispatch, terminal presentation, server/client bootstrap, and the hidden local run-worker process entry.
|
||||
- **Assigned file count:** 241
|
||||
- **Globs:**
|
||||
- `lib/apps/fabro-cli/Cargo.toml`
|
||||
- `lib/apps/fabro-cli/build.rs`
|
||||
- `lib/apps/fabro-cli/src/**`
|
||||
- `lib/apps/fabro-cli/tests/**`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `lib/apps/fabro-cli/src/main.rs:main`
|
||||
- `lib/apps/fabro-cli/src/main.rs:main_inner`
|
||||
- `lib/apps/fabro-cli/src/args.rs:Cli`
|
||||
- `lib/apps/fabro-cli/src/args.rs:Commands`
|
||||
- `lib/apps/fabro-cli/src/commands/run/mod.rs:dispatch`
|
||||
- **Owns:**
|
||||
- The `fabro` process lifecycle, exit classification, telemetry bootstrap, and logging bootstrap.
|
||||
- CLI argument and subcommand contracts plus human-readable and JSON output behavior.
|
||||
- Per-command resolved settings, lazy API client/credential/catalog state in `CommandContext`.
|
||||
- Local server discovery/startup and authenticated server connections.
|
||||
- The hidden `__run-worker` subprocess entry and its terminal run-progress presentation.
|
||||
- **Candidate `depends_on` IDs within this scout:** `fabro-mcp-server`, `fabro-server`.
|
||||
- **Manifest-backed cross-scope dependency candidates:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-checkpoint`, `fabro-client`, `fabro-config`, `fabro-dump`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp`, `fabro-model`, `fabro-oauth`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-static`, `fabro-store`, `fabro-telemetry`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `fabro-workflow`. `fabro-build-support` is also a build-time edge.
|
||||
- **Evidence:**
|
||||
- `lib/apps/fabro-cli/Cargo.toml:[[bin]]` — declares package `fabro-cli` as the `fabro` binary with `src/main.rs` as its entry point and lists direct workspace dependencies, including `fabro-mcp-server` and `fabro-server`.
|
||||
- `Cargo.toml:[workspace]` — includes `lib/apps/*` as members and selects `lib/apps/fabro-cli` as the default workspace member.
|
||||
- `lib/apps/fabro-cli/src/main.rs:main_inner` — creates the shared command context and dispatches every `Commands` variant, including the server and run-worker paths.
|
||||
- `lib/apps/fabro-cli/src/args.rs:Commands` — defines the complete top-level CLI command surface; `RunCommands` includes the hidden `__run-worker` entry.
|
||||
- `lib/apps/fabro-cli/src/command_context.rs:CommandContext` — owns the per-invocation settings, output mode, storage path, lazy server client, credential source, and model catalog shared by commands.
|
||||
- `lib/apps/fabro-cli/src/server_client.rs:connect_server_with_settings` — resolves local or remote targets and constructs the authenticated control-plane client used by command implementations.
|
||||
- `lib/apps/fabro-cli/tests/it/main.rs` — assembles command, scenario, support, and end-to-end workflow tests around the same binary application boundary.
|
||||
|
||||
### `fabro-mcp-server` — Fabro MCP Stdio Server
|
||||
|
||||
- **Purpose:** Exposes Fabro run operations as an MCP stdio tool server and supplies MCP-client configuration generation and installation helpers used by the CLI.
|
||||
- **Assigned file count:** 5
|
||||
- **Globs:**
|
||||
- `lib/apps/fabro-mcp-server/Cargo.toml`
|
||||
- `lib/apps/fabro-mcp-server/src/**`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `lib/apps/fabro-mcp-server/src/lib.rs:start`
|
||||
- `lib/apps/fabro-mcp-server/src/server.rs:start`
|
||||
- `lib/apps/fabro-mcp-server/src/lib.rs:FabroMcpServerSettings`
|
||||
- `lib/apps/fabro-mcp-server/src/config.rs:config_json`
|
||||
- `lib/apps/fabro-mcp-server/src/config.rs:init_agent`
|
||||
- **Owns:**
|
||||
- The MCP stdio service lifecycle and registered Fabro tool router.
|
||||
- Lazy construction of the Fabro client-backed tool backend.
|
||||
- Translation from MCP run-create inputs to Fabro API run manifests.
|
||||
- MCP client configuration rendering and updates to supported agent config files.
|
||||
- **Candidate `depends_on` IDs within this scout:** `fabro-server`.
|
||||
- **Manifest-backed cross-scope dependency candidates:** `fabro-api`, `fabro-client`, `fabro-config`, `fabro-manifest`, `fabro-model`, `fabro-tool`, `fabro-types`, `fabro-util`.
|
||||
- **Evidence:**
|
||||
- `lib/apps/fabro-mcp-server/Cargo.toml:[package]` — declares a distinct library package described as the Fabro MCP stdio server and lists a direct `fabro-server` dependency.
|
||||
- `lib/apps/fabro-mcp-server/src/lib.rs:FabroMcpServerSettings` — defines the public construction boundary, client factory, config path, and working directory used to start the service.
|
||||
- `lib/apps/fabro-mcp-server/src/server.rs:start` — owns the `rmcp` stdio service lifecycle; `FabroMcpServer` owns the tool router and lazy backend.
|
||||
- `lib/apps/fabro-mcp-server/src/manifest_builder.rs:McpRunManifestBuilder` — adapts MCP tool creation requests through `fabro_server::run_tool_manifest`.
|
||||
- `lib/apps/fabro-cli/src/commands/mcp/mod.rs:dispatch` — the separate CLI package consumes this library solely through its public start/config/init interfaces.
|
||||
|
||||
### `fabro-server` — Fabro HTTP Server
|
||||
|
||||
- **Purpose:** Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, schedulers, worker processes, sessions, authentication, integrations, and startup/shutdown.
|
||||
- **Assigned file count:** 112
|
||||
- **Globs:**
|
||||
- `lib/apps/fabro-server/Cargo.toml`
|
||||
- `lib/apps/fabro-server/build.rs`
|
||||
- `lib/apps/fabro-server/migrations/**`
|
||||
- `lib/apps/fabro-server/src/**`
|
||||
- `lib/apps/fabro-server/tests/**`
|
||||
- **Exclude globs:** none
|
||||
- **Entry points:**
|
||||
- `lib/apps/fabro-server/src/serve.rs:serve_command`
|
||||
- `lib/apps/fabro-server/src/server.rs:AppState`
|
||||
- `lib/apps/fabro-server/src/server.rs:build_router`
|
||||
- `lib/apps/fabro-server/src/server.rs:build_router_with_options`
|
||||
- `lib/apps/fabro-server/src/server.rs:spawn_scheduler`
|
||||
- `lib/apps/fabro-server/src/lib.rs`
|
||||
- **Owns:**
|
||||
- Listener binding, resolved startup configuration, migrations, web enablement, and graceful shutdown.
|
||||
- Shared `AppState`: managed runs, persistent stores, session runtimes, artifact storage, resource sampling, settings/catalog state, and integration services.
|
||||
- API and web routing, authentication/principal middleware, static-file delivery, security headers, and OpenAPI conformance at the router boundary.
|
||||
- Run and automation scheduling, worker launch/control/token state, cancellation escalation, and global event broadcast.
|
||||
- Server-side install, diagnostics, GitHub webhook, Slack, environment, secret, variable, MCP-server, and sandbox coordination exposed through HTTP handlers.
|
||||
- **Candidate `depends_on` IDs within this scout:** `fabro-spa`.
|
||||
- **Manifest-backed cross-scope dependency candidates:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-automation`, `fabro-client`, `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp-store`, `fabro-model`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-slack`, `fabro-static`, `fabro-store`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-variable`, `fabro-vault`, `fabro-workflow`. `fabro-build-support` is also a build-time edge.
|
||||
- **Evidence:**
|
||||
- `lib/apps/fabro-server/Cargo.toml:[package]` — declares a distinct HTTP-server library package, an integration-test target gated by `test-support`, and a direct `fabro-spa` dependency.
|
||||
- `lib/apps/fabro-server/src/lib.rs` — exposes the server's supported module/API surface and gates `test_support` behind tests or the explicit feature.
|
||||
- `lib/apps/fabro-server/src/serve.rs:serve_command` — resolves settings and secrets, runs database and compatibility migrations, builds stores/state/router, binds listeners, starts background services, and coordinates shutdown.
|
||||
- `lib/apps/fabro-server/src/server.rs:AppState` — centralizes the service's run registry, stores, session and worker runtime state, schedulers, event channel, settings, credentials, integrations, and shutdown token.
|
||||
- `lib/apps/fabro-server/src/server.rs:build_router_with_options` — composes real/demo APIs, auth/web routes, middleware, static assets, and the health surface around the shared state.
|
||||
- `lib/apps/fabro-server/src/server/handler/mod.rs:real_routes` — registers the HTTP resource handlers that consume `AppState`.
|
||||
- `lib/apps/fabro-server/tests/it/main.rs` — assembles API, conformance, pagination, and lifecycle scenario tests around the same library/router boundary.
|
||||
|
||||
### `fabro-spa` — Embedded SPA Assets
|
||||
|
||||
- **Purpose:** Provides the compile-time embedded production SPA asset lookup API and precomputed content hashes consumed by the HTTP server.
|
||||
- **Assigned file count:** 2
|
||||
- **Globs:**
|
||||
- `lib/apps/fabro-spa/Cargo.toml`
|
||||
- `lib/apps/fabro-spa/src/**`
|
||||
- `lib/apps/fabro-spa/assets/**`
|
||||
- **Exclude globs:**
|
||||
- `lib/apps/fabro-spa/assets/**`
|
||||
- **Entry points:**
|
||||
- `lib/apps/fabro-spa/src/lib.rs:get`
|
||||
- `lib/apps/fabro-spa/src/lib.rs:AssetBytes`
|
||||
- **Owns:**
|
||||
- Compile-time embedding of production SPA files from `assets/`.
|
||||
- Asset byte ownership and the SHA-256 metadata returned to server static-file handling.
|
||||
- The invariant that source maps are not embedded.
|
||||
- **Candidate `depends_on` IDs within this scout:** none
|
||||
- **Manifest-backed cross-scope dependency candidates:** none
|
||||
- **Evidence:**
|
||||
- `lib/apps/fabro-spa/Cargo.toml:[package]` — declares a distinct library package for embedded production SPA assets and depends only on `rust-embed`.
|
||||
- `lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets` — defines the compile-time asset folder and source-map exclusions.
|
||||
- `lib/apps/fabro-spa/src/lib.rs:get` — is the package's public asset lookup interface and returns bytes with their precomputed SHA-256 value.
|
||||
- `lib/apps/fabro-server/src/static_files.rs` — consumes `fabro_spa::get` and `fabro_spa::AssetBytes`, establishing the direction `fabro-server` → `fabro-spa`.
|
||||
- `AGENTS.md` and `.gitignore` — identify `assets/` contents as refreshed, ignored build output while preserving only `.gitkeep`.
|
||||
|
||||
## Dependency reconciliation notes
|
||||
|
||||
The in-scope application dependency edges are exact production Cargo edges:
|
||||
|
||||
```text
|
||||
fabro-cli ───────────────→ fabro-server ───────────────→ fabro-spa
|
||||
└──→ fabro-mcp-server ───→ fabro-server
|
||||
```
|
||||
|
||||
The cross-scope dependency labels above use Cargo package names as provisional
|
||||
component IDs. If another scout groups multiple packages into one component,
|
||||
the parent map should translate those package edges to the reconciled
|
||||
component ID. Build-time and dev-only edges should be handled consistently
|
||||
across the final map; the primary candidate lists above include production
|
||||
and build-time edges but do not add dev-only test-support dependencies.
|
||||
|
||||
Dev-only workspace edges that may matter during reconciliation are:
|
||||
|
||||
- `fabro-cli` tests additionally use `fabro-acp`, `fabro-macros`,
|
||||
`fabro-server` with `test-support`, `fabro-types` with `test-support`, and
|
||||
`fabro-workflow` with `test-support`.
|
||||
- `fabro-server` tests additionally use `fabro-macros`, `fabro-sandbox` with
|
||||
`test-support`, and `fabro-types` with `test-support`.
|
||||
|
||||
## Exclusions and unmapped files
|
||||
|
||||
- **Excluded:** `lib/apps/fabro-spa/assets/.gitkeep` — placeholder retained in
|
||||
an otherwise ignored generated-asset directory.
|
||||
- **Unmapped:** none.
|
||||
|
||||
## Open boundary questions
|
||||
|
||||
1. Should `fabro-server` remain one service component, as proposed, or should
|
||||
the final repository map expose separate server transport/auth and
|
||||
run/worker-coordination components? `serve_command`, `AppState`, and the
|
||||
integration suite currently join those lifecycles, while the public auth
|
||||
modules, handler tree, and worker-control modules offer possible
|
||||
sub-boundaries.
|
||||
2. Should the hidden `fabro __run-worker` path remain part of `fabro-cli`, as
|
||||
proposed, or be represented as a run-worker component? It has a distinct
|
||||
process lifecycle and is launched by `fabro-server`, but it shares the CLI
|
||||
binary, manifest, dispatch, command context, and integration-test suite.
|
||||
3. Should MCP client configuration/init behavior and the MCP stdio tool
|
||||
service remain one `fabro-mcp-server` component, as proposed? They are
|
||||
separate public operations but share one five-file package and one CLI
|
||||
namespace.
|
||||
4. Should `fabro-spa` remain a separate component, as proposed, or be folded
|
||||
into `fabro-server` because all generated payloads are excluded and the
|
||||
remaining package has two assigned files? Its separate Cargo package and
|
||||
public asset/hash interface establish a dependency boundary, while its only
|
||||
production consumer in this scope is the server.
|
||||
|
|
@ -1,391 +0,0 @@
|
|||
# Cartography scout report: Rust components
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
|
||||
|
||||
Scope: tracked files under `lib/components/**`, with workspace manifests and public consumers consulted only as boundary evidence.
|
||||
|
||||
## Boundary synthesis
|
||||
|
||||
The scope contains 23 non-published, shared in-repository Rust library crates. The primary proposal keeps one component per crate: every crate has its own manifest and crate root, exposes a distinct public vocabulary or execution facade, and owns a separate domain state, external protocol, or runtime lifecycle. This also keeps the regular Cargo dependency edges directional and makes every glob non-overlapping.
|
||||
|
||||
The four SQLite-backed resource crates (`fabro-automation`, `fabro-environment`, `fabro-mcp-store`, and `fabro-variable`) use a similar storage pattern, but their identifiers, validation, import formats, tables, and public consumers differ; they are therefore proposed as separate components. The two-file crates (`fabro-dump`, `fabro-install`, and `fabro-manifest`) are also kept separate because each contains a substantial public operation and has a distinct dependency/consumer boundary rather than being a collection of incidental helpers.
|
||||
|
||||
Checked-in snapshots, prompt templates, grammars, migrations, and test fixture keys are assigned to the component whose behavior they exercise. No tracked file in this scope has evidence of being vendored or build output, and no checked-in generated source is excluded.
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `fabro-acp` — Agent Client Protocol runtime
|
||||
|
||||
- Purpose: Launch and control Agent Client Protocol processes through Fabro sandboxes and translate their sessions into Fabro run results.
|
||||
- Globs: `lib/components/fabro-acp/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-acp/src/lib.rs`, `lib/components/fabro-acp/src/command.rs:AcpProcessSpec`, `lib/components/fabro-acp/src/session.rs:run_acp_turn`
|
||||
- Owns: ACP process specifications; ACP transport/session lifetime; live steering and cancellation handles; ACP process exit/error translation.
|
||||
- Depends on candidates: `fabro-sandbox`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-acp/Cargo.toml` — declares an ACP backend crate with a default `runtime` feature and an optional runtime dependency on `fabro-sandbox`.
|
||||
- `lib/components/fabro-acp/src/lib.rs` — exposes the process specification and runtime session/control API while keeping transport internal.
|
||||
- `lib/components/fabro-acp/tests/session.rs` — exercises the session boundary as an integration test.
|
||||
- Scoped tracked files: 8
|
||||
|
||||
### `fabro-agent` — Coding agent runtime
|
||||
|
||||
- Purpose: Run programmable coding-agent sessions, including model profiles, context management, native tools, permissions, MCP tools, and subagents.
|
||||
- Globs: `lib/components/fabro-agent/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-agent/src/lib.rs`, `lib/components/fabro-agent/src/session.rs:Session`, `lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry`, `lib/components/fabro-agent/src/cli.rs:run_with_args`
|
||||
- Owns: agent session state and history; agent/model profiles and prompt templates; tool registry and execution lifecycle; context compaction; todo/question/subagent runtimes; agent-emitted events.
|
||||
- Depends on candidates: `fabro-llm`, `fabro-mcp`, `fabro-sandbox`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-agent/Cargo.toml` — describes a programmable agentic loop and declares direct dependencies on the LLM, MCP, and sandbox crates.
|
||||
- `lib/components/fabro-agent/src/lib.rs` — presents one crate-level facade spanning sessions, profiles, tools, permissions, history, and subagent supervision.
|
||||
- `lib/components/fabro-agent/tests/it/main.rs` — anchors the crate's integration-test suite; profile prompt snapshots and `.j2` templates are behavioral assets of the same runtime.
|
||||
- Scoped tracked files: 66
|
||||
|
||||
### `fabro-automation` — Automation definitions and storage
|
||||
|
||||
- Purpose: Validate, version, import, and durably store scheduled, API-triggered, and manual Fabro automation definitions.
|
||||
- Globs: `lib/components/fabro-automation/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-automation/src/lib.rs`, `lib/components/fabro-automation/src/store.rs:AutomationStore`, `lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once`
|
||||
- Owns: automation IDs and revisions; automation targets and triggers; canonical revision calculation; automation SQLite records; legacy file-definition import.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-automation/Cargo.toml` — declares “Automation domain and durable storage for Fabro” and uses the shared database foundation.
|
||||
- `lib/components/fabro-automation/src/lib.rs` — re-exports the automation domain, validation errors, revisions, store, and one-time importer as one API.
|
||||
- `lib/components/fabro-automation/tests/store.rs` and `lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs` — cover and evolve the owned automation persistence format.
|
||||
- Scoped tracked files: 9
|
||||
|
||||
### `fabro-checkpoint` — Git checkpoint storage
|
||||
|
||||
- Purpose: Store workflow checkpoints and metadata in Git commits and dedicated metadata branches.
|
||||
- Globs: `lib/components/fabro-checkpoint/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-checkpoint/src/lib.rs`, `lib/components/fabro-checkpoint/src/branch.rs:BranchStore`, `lib/components/fabro-checkpoint/src/git.rs:Store`
|
||||
- Owns: Git tree entries and checkpoint commits; metadata-branch naming and access; checkpoint commit authorship and trailers; checkpoint-specific error types.
|
||||
- Depends on candidates: `fabro-store`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-checkpoint/Cargo.toml` — identifies Git-backed workflow checkpoint storage and directly depends on `fabro-store`.
|
||||
- `lib/components/fabro-checkpoint/src/lib.rs` — exposes branch, Git, author, trailer, and checkpoint error modules behind one crate facade.
|
||||
- `lib/components/fabro-checkpoint/src/branch.rs:BranchStore` and `lib/components/fabro-checkpoint/src/git.rs:Store` — provide the two persistence entry points over the same Git repository state.
|
||||
- Scoped tracked files: 7
|
||||
|
||||
### `fabro-dump` — Run dump materialization
|
||||
|
||||
- Purpose: Materialize a stored run projection, event history, checkpoints, artifacts, and referenced blobs into a portable directory tree.
|
||||
- Globs: `lib/components/fabro-dump/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-dump/src/lib.rs:RunDump`, `lib/components/fabro-dump/src/lib.rs:RunDump::from_store_state_and_events`, `lib/components/fabro-dump/src/lib.rs:RunDump::write_to_dir`
|
||||
- Owns: dump entry layout and filenames; stage ranking within dumps; blob hydration; dump serialization and directory writing.
|
||||
- Depends on candidates: `fabro-store`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-dump/Cargo.toml` — gives the crate a direct dependency on `fabro-store`, which supplies projections and event envelopes.
|
||||
- `lib/components/fabro-dump/src/lib.rs:RunDump` — contains the public dump-building and writing lifecycle, with inline tests for its output contract.
|
||||
- Workspace consumers `fabro-cli` and `fabro-workflow` both depend directly on `fabro-dump`, rather than accessing its behavior through `fabro-store`.
|
||||
- Scoped tracked files: 2
|
||||
|
||||
### `fabro-environment` — Environment definitions and storage
|
||||
|
||||
- Purpose: Validate, seed, version, import, and durably store server-owned execution environment definitions.
|
||||
- Globs: `lib/components/fabro-environment/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-environment/src/lib.rs`, `lib/components/fabro-environment/src/store.rs:EnvironmentStore`, `lib/components/fabro-environment/src/store.rs:seed_default_environment`
|
||||
- Owns: environment IDs and revisions; environment drafts and canonical revisions; environment SQLite records; built-in environment seeding; legacy directory import.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-environment/Cargo.toml` — declares the server-owned environment domain and durable storage.
|
||||
- `lib/components/fabro-environment/src/lib.rs` — exports a specific environment domain/store API, including seeding and import operations.
|
||||
- `lib/components/fabro-environment/tests/store.rs` — exercises the environment persistence boundary independently of the other resource stores.
|
||||
- Scoped tracked files: 7
|
||||
|
||||
### `fabro-github` — GitHub authentication and API
|
||||
|
||||
- Purpose: Resolve GitHub credentials and perform authenticated GitHub App, repository, branch, and pull-request API operations.
|
||||
- Globs: `lib/components/fabro-github/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-github/src/lib.rs:GitHubCredentials`, `lib/components/fabro-github/src/lib.rs:GitHubContext`, `lib/components/fabro-github/src/lib.rs:create_pull_request`, `lib/components/fabro-github/src/lib.rs:resolve_authenticated_url`
|
||||
- Owns: GitHub credential forms and token minting; GitHub API request/response translation; repository URL normalization and authenticated clone URLs; pull-request lifecycle calls.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-github/Cargo.toml` — describes GitHub App authentication and API helpers and declares the JWT/HTTP dependencies used at this boundary.
|
||||
- `lib/components/fabro-github/src/lib.rs` — defines the credential context, testable HTTP abstraction, App token flow, and repository/PR operations in one public surface.
|
||||
- `lib/components/fabro-github/tests/integration.rs` and `lib/components/fabro-github/src/testdata/rsa_private.pem` — exercise the external authentication/API boundary using a dedicated test key fixture.
|
||||
- Scoped tracked files: 4
|
||||
|
||||
### `fabro-graphviz` — Workflow graph language
|
||||
|
||||
- Purpose: Parse Graphviz DOT into Fabro's typed graph model and parse conditions/stylesheets or render graphs for presentation.
|
||||
- Globs: `lib/components/fabro-graphviz/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-graphviz/src/lib.rs`, `lib/components/fabro-graphviz/src/parser/mod.rs:parse`, `lib/components/fabro-graphviz/src/condition.rs:parse_condition_expr`, `lib/components/fabro-graphviz/src/render.rs:render_dot`
|
||||
- Owns: DOT lexer/parser/semantic conversion; graph parsing errors; condition and stylesheet syntax; Graphviz rendering normalization.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-graphviz/Cargo.toml` — names the crate as the DOT parser and typed graph data model.
|
||||
- `lib/components/fabro-graphviz/src/parser/mod.rs:parse` — is the source-to-typed-graph entry point backed by separate lexer, grammar, AST, and semantic modules.
|
||||
- `lib/components/fabro-graphviz/src/lib.rs` — exposes parsing-adjacent condition, fidelity, rendering, and stylesheet interfaces as the graph-language boundary.
|
||||
- Scoped tracked files: 14
|
||||
|
||||
### `fabro-hooks` — Workflow lifecycle hooks
|
||||
|
||||
- Purpose: Configure and execute user-defined workflow lifecycle hooks and bridge tool hooks into the agent runtime.
|
||||
- Globs: `lib/components/fabro-hooks/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-hooks/src/lib.rs`, `lib/components/fabro-hooks/src/runner.rs:HookRunner`, `lib/components/fabro-hooks/src/executor.rs:HookExecutor`, `lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback`
|
||||
- Owns: hook configuration and event selection; hook execution context; hook result/decision merging; HTTP/command hook dispatch; agent tool-hook bridging.
|
||||
- Depends on candidates: `fabro-agent`, `fabro-llm`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-hooks/Cargo.toml` — identifies workflow lifecycle hooks and directly depends on the agent and LLM components used by hook execution.
|
||||
- `lib/components/fabro-hooks/src/lib.rs` — exposes hook definitions, decisions, runner, execution context, and the agent bridge.
|
||||
- `lib/components/fabro-hooks/tests/host_command_hooks.rs` — tests host-command hooks through the public lifecycle boundary.
|
||||
- Scoped tracked files: 8
|
||||
|
||||
### `fabro-install` — Installation persistence
|
||||
|
||||
- Purpose: Prepare, persist, and roll back shared CLI/server installation settings, credentials, development tokens, and default environments.
|
||||
- Globs: `lib/components/fabro-install/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan`, `lib/components/fabro-install/src/lib.rs:persist_install_outputs_direct`, `lib/components/fabro-install/src/lib.rs:merge_server_settings`
|
||||
- Owns: install persistence plans; settings and server-env mutations; vault writes/removals; development-token creation and rollback; default environment seeding during install.
|
||||
- Depends on candidates: `fabro-environment`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-install/Cargo.toml` — describes shared install primitives for CLI and server flows and directly depends on the environment store.
|
||||
- `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan` — groups the files, env entries, token, and vault state committed by one install operation.
|
||||
- Workspace consumers `fabro-cli` and `fabro-server` depend directly on this crate, making it a shared install boundary rather than CLI-local code.
|
||||
- Scoped tracked files: 2
|
||||
|
||||
### `fabro-interview` — Human interaction runtime
|
||||
|
||||
- Purpose: Represent workflow questions and answers and provide console, callback, queue, control, recording, replay, and automatic interviewer implementations.
|
||||
- Globs: `lib/components/fabro-interview/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-interview/src/lib.rs:Interviewer`, `lib/components/fabro-interview/src/lib.rs:ask_with_timeout`, `lib/components/fabro-interview/src/control.rs:ControlInterviewer`
|
||||
- Owns: question/answer protocol; interviewer request lifetime and timeout behavior; queued and controlled answer delivery; interview recording and replay.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-interview/Cargo.toml` — defines human-in-the-loop interviewer traits and implementations as the crate purpose.
|
||||
- `lib/components/fabro-interview/src/lib.rs:Interviewer` — is the shared async interaction interface and re-exports all implementation strategies.
|
||||
- `lib/components/fabro-interview/src/control_protocol.rs` and `lib/components/fabro-interview/src/control.rs` — own the worker-control delivery protocol and pending interaction state.
|
||||
- Scoped tracked files: 10
|
||||
|
||||
### `fabro-llm` — Unified LLM client
|
||||
|
||||
- Purpose: Provide a provider-neutral generation API with model routing, middleware, retries, token/cost accounting, provider adapters, and wire codecs.
|
||||
- Globs: `lib/components/fabro-llm/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-llm/src/lib.rs`, `lib/components/fabro-llm/src/client.rs:Client`, `lib/components/fabro-llm/src/provider.rs:ProviderAdapter`, `lib/components/fabro-llm/src/generate.rs:generate`, `lib/components/fabro-llm/src/generate.rs:stream`
|
||||
- Owns: normalized LLM request/response/stream types; provider adapter registry; provider-specific authentication and transport; request/response/stream wire translation; retry/middleware/generation orchestration; token and cost calculations.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-llm/Cargo.toml` — describes a unified multi-provider client and does not depend on another component crate.
|
||||
- `lib/components/fabro-llm/src/provider.rs:ProviderAdapter` and `lib/components/fabro-llm/src/client.rs:Client` — define the adapter contract and client registry through which the provider modules are consumed.
|
||||
- `lib/components/fabro-llm/tests/it/wire/mod.rs` and its provider-specific snapshot trees — verify that the codecs and adapters implement the same normalized client boundary.
|
||||
- Scoped tracked files: 188
|
||||
|
||||
### `fabro-manifest` — Run manifest construction
|
||||
|
||||
- Purpose: Resolve workflow/configuration inputs, collect static dependencies, and construct a self-contained run manifest with Git provenance.
|
||||
- Globs: `lib/components/fabro-manifest/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-manifest/src/lib.rs:build_run_manifest`, `lib/components/fabro-manifest/src/lib.rs:build_run_overrides`, `lib/components/fabro-manifest/src/lib.rs:ManifestBuildInput`
|
||||
- Owns: manifest build input/output; configuration-layer resolution for manifest creation; workflow/file dependency collection; Git context and pre-run push preparation.
|
||||
- Depends on candidates: `fabro-github`, `fabro-graphviz`, `fabro-workflow`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-manifest/Cargo.toml` — declares run manifest construction and direct dependencies on graph parsing, GitHub support, and selected workflow utilities.
|
||||
- `lib/components/fabro-manifest/src/lib.rs:build_run_manifest` — is a single public assembly operation that produces the API `RunManifest`.
|
||||
- Workspace consumers `fabro-cli`, `fabro-server`, and `fabro-mcp-server` depend directly on the crate to share identical manifest construction.
|
||||
- Scoped tracked files: 2
|
||||
|
||||
### `fabro-mcp` — MCP client runtime
|
||||
|
||||
- Purpose: Connect to configured Model Context Protocol servers, manage their connection lifetimes, discover tools, and dispatch qualified tool calls.
|
||||
- Globs: `lib/components/fabro-mcp/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-mcp/src/lib.rs`, `lib/components/fabro-mcp/src/client.rs:McpClient`, `lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager`
|
||||
- Owns: MCP client connections; stdio and streaming HTTP transport selection; server connection manager state; tool discovery, qualified names, and call-result conversion.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-mcp/Cargo.toml` — describes the MCP client role and enables the rmcp client/transport features required by it.
|
||||
- `lib/components/fabro-mcp/src/lib.rs` — exposes client, config, connection manager, and HTTP transport modules while keeping protocol handlers internal.
|
||||
- `lib/components/fabro-mcp/tests/stdio_integration.rs` — verifies the external MCP process boundary over stdio.
|
||||
- Scoped tracked files: 10
|
||||
|
||||
### `fabro-mcp-store` — MCP server catalog storage
|
||||
|
||||
- Purpose: Durably store, revision, cache, and import server-managed MCP server definitions.
|
||||
- Globs: `lib/components/fabro-mcp-store/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-mcp-store/src/lib.rs`, `lib/components/fabro-mcp-store/src/store.rs:McpServerStore`, `lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once`
|
||||
- Owns: MCP server definition SQLite records; definition revisions and optimistic concurrency; synchronous catalog cache; legacy directory import.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-mcp-store/Cargo.toml` — declares server-managed MCP catalog durable storage.
|
||||
- `lib/components/fabro-mcp-store/src/lib.rs` — explicitly states that the domain model is shared but this crate owns persistence, and exports only the store/error/import API.
|
||||
- `lib/components/fabro-mcp-store/tests/store.rs` — exercises that persistence boundary independently from live MCP connections.
|
||||
- Scoped tracked files: 6
|
||||
|
||||
### `fabro-sandbox` — Execution sandbox abstraction
|
||||
|
||||
- Purpose: Define the execution sandbox and provider contracts and implement local, Docker, and Daytona sandbox lifecycles.
|
||||
- Globs: `lib/components/fabro-sandbox/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-sandbox/src/lib.rs`, `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProvider`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry`
|
||||
- Owns: sandbox filesystem/process/terminal interface; provider creation, lookup, and removal lifecycle; local/Docker/Daytona implementations; clone-source setup and reconnect behavior; sandbox errors and redaction.
|
||||
- Depends on candidates: `fabro-github`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-sandbox/Cargo.toml` — defines provider features (`local`, `docker`, `daytona`) around the common sandbox crate and makes GitHub support optional for clone-based providers.
|
||||
- `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox` and `lib/components/fabro-sandbox/src/provider.rs:SandboxProvider` — separate per-sandbox operations from provider lifecycle management within one public boundary.
|
||||
- `lib/components/fabro-sandbox/tests/docker_streaming.rs` and `lib/components/fabro-sandbox/tests/daytona_streaming_live.rs` — exercise provider implementations against the shared contract.
|
||||
- Scoped tracked files: 23
|
||||
|
||||
### `fabro-slack` — Slack interaction integration
|
||||
|
||||
- Purpose: Connect to Slack Socket Mode and translate workflow questions, answers, run lifecycle events, and thread replies between Slack and Fabro.
|
||||
- Globs: `lib/components/fabro-slack/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-slack/src/connection.rs:run`, `lib/components/fabro-slack/src/client.rs:SlackClient`, `lib/components/fabro-slack/src/blocks.rs:question_to_blocks`
|
||||
- Owns: Slack credential resolution; Socket Mode connection/event loop; Slack API client; block rendering; interaction payload parsing; run-to-thread registry and dispatch.
|
||||
- Depends on candidates: `fabro-interview`, `fabro-workflow`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-slack/Cargo.toml` — declares the Slack interviewer integration and directly depends on the interview and workflow components.
|
||||
- `lib/components/fabro-slack/src/connection.rs:run` — owns the Socket Mode connection lifetime and dispatch loop.
|
||||
- `lib/components/fabro-slack/src/interaction.rs` and `lib/components/fabro-slack/src/threads.rs` — translate external payloads into interview submissions and associate Slack threads with run state.
|
||||
- Scoped tracked files: 11
|
||||
|
||||
### `fabro-store` — Run and authentication persistence
|
||||
|
||||
- Purpose: Persist run event streams, projections, blobs, artifacts, summaries, catalog indexes, and server authentication grants over SlateDB, object storage, and SQLite.
|
||||
- Globs: `lib/components/fabro-store/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-store/src/lib.rs`, `lib/components/fabro-store/src/slate/mod.rs:Database`, `lib/components/fabro-store/src/slate/run_store.rs:RunDatabase`, `lib/components/fabro-store/src/run_state.rs:RunProjectionReducer`
|
||||
- Owns: run event append/read lifecycle; run projection reduction and caching; run/blob/artifact key layout; run catalog and summary indexes; authorization-code and refresh-token records; storage-specific errors and locking.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-store/src/lib.rs` — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth records.
|
||||
- `lib/components/fabro-store/src/slate/mod.rs:Database` — is the shared storage root from which run, blob, catalog, auth-code, and refresh-token stores are obtained.
|
||||
- `lib/components/fabro-store/tests/serializable_projection.rs` — tests the durable projection representation at the crate boundary.
|
||||
- Scoped tracked files: 25
|
||||
|
||||
### `fabro-tool` — Run-control tools
|
||||
|
||||
- Purpose: Define and execute the shared run create, search, get, event, gather, interaction, and pairing tools over an abstract Fabro backend.
|
||||
- Globs: `lib/components/fabro-tool/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-tool/src/lib.rs`, `lib/components/fabro-tool/src/common.rs:FabroToolBackend`, `lib/components/fabro-tool/src/common.rs:tool_definitions`, `lib/components/fabro-tool/src/create.rs:create_runs`
|
||||
- Owns: tool names, JSON schemas, and parameter validation; backend-neutral run-control operations; result DTOs and text rendering; API-client backend adapter.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-tool/Cargo.toml` — identifies shared run-control tool behavior and depends on foundation API/client contracts rather than the server or workflow implementation.
|
||||
- `lib/components/fabro-tool/src/common.rs:FabroToolBackend` — is the abstraction shared by CLI, server, workflow, and MCP-server consumers.
|
||||
- `lib/components/fabro-tool/src/lib.rs` — exports a matched set of validated operation/result/text interfaces for all supported tools.
|
||||
- Scoped tracked files: 12
|
||||
|
||||
### `fabro-tracker` — Issue tracker adapters
|
||||
|
||||
- Purpose: Provide a common issue-tracker interface with GitHub Projects and Linear implementations.
|
||||
- Globs: `lib/components/fabro-tracker/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-tracker/src/lib.rs:Tracker`, `lib/components/fabro-tracker/src/github.rs:GitHubTracker`, `lib/components/fabro-tracker/src/linear.rs:LinearTracker`
|
||||
- Owns: normalized issue and blocker records; candidate-issue query and state-transition contract; GitHub Projects GraphQL adapter; Linear GraphQL adapter.
|
||||
- Depends on candidates: `fabro-github`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-tracker/Cargo.toml` — declares the tracker trait/types boundary and directly depends on GitHub support for one adapter.
|
||||
- `lib/components/fabro-tracker/src/lib.rs:Tracker` — defines a provider-neutral async issue workflow implemented by both provider modules.
|
||||
- `lib/components/fabro-tracker/src/fixtures/github-app-test-key.pem` — is a test fixture owned by the GitHub tracker adapter, not a runtime credential or vendored file.
|
||||
- Scoped tracked files: 5
|
||||
|
||||
### `fabro-validate` — Workflow graph validation
|
||||
|
||||
- Purpose: Run built-in and catalog-aware lint rules over typed Fabro workflow graphs and return structured diagnostics.
|
||||
- Globs: `lib/components/fabro-validate/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-validate/src/lib.rs:validate`, `lib/components/fabro-validate/src/lib.rs:validate_with_catalog`, `lib/components/fabro-validate/src/lib.rs:LintRule`, `lib/components/fabro-validate/src/rules/mod.rs:built_in_rules`
|
||||
- Owns: validation severity and diagnostic structure; lint-rule interface and built-in rule registry; graph/catalog validation traversal; validation error escalation.
|
||||
- Depends on candidates: `fabro-acp`, `fabro-graphviz`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-validate/Cargo.toml` — declares graph validation/linting and directly depends on graph parsing plus ACP backend validation.
|
||||
- `lib/components/fabro-validate/src/lib.rs:LintRule` — provides the extension interface and public diagnostic API.
|
||||
- `lib/components/fabro-validate/src/rules/mod.rs:built_in_rules` and the 31 rule source files — form an explicit registry of independently tested rules under one validation lifecycle.
|
||||
- Scoped tracked files: 36
|
||||
|
||||
### `fabro-variable` — Workflow variable storage
|
||||
|
||||
- Purpose: Validate, durably store, snapshot, and import workflow-visible non-sensitive variables.
|
||||
- Globs: `lib/components/fabro-variable/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-variable/src/lib.rs:VariableStore`, `lib/components/fabro-variable/src/lib.rs:VariableStore::value_map`, `lib/components/fabro-variable/src/lib.rs:import_legacy_json_once`
|
||||
- Owns: variable name validation; variable SQLite records and timestamps; name-to-value snapshots for template contexts; legacy JSON import and backup.
|
||||
- Depends on candidates: `[]`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-variable/Cargo.toml` — defines workflow-visible, non-sensitive variables as a separate storage concern.
|
||||
- `lib/components/fabro-variable/src/lib.rs:VariableStore` — exposes CRUD and render-context snapshot operations over that single domain.
|
||||
- `lib/components/fabro-variable/tests/store.rs` — verifies its persistence/import contract independently from environments, automations, and MCP definitions.
|
||||
- Scoped tracked files: 3
|
||||
|
||||
### `fabro-workflow` — Workflow orchestration engine
|
||||
|
||||
- Purpose: Transform, validate, initialize, execute, persist, resume, and finalize graph-defined Fabro runs across handlers, lifecycle hooks, sandboxes, checkpoints, events, and human controls.
|
||||
- Globs: `lib/components/fabro-workflow/**`
|
||||
- Exclude globs: `[]`
|
||||
- Entry points: `lib/components/fabro-workflow/src/operations/mod.rs`, `lib/components/fabro-workflow/src/operations/start.rs:start`, `lib/components/fabro-workflow/src/pipeline/mod.rs`, `lib/components/fabro-workflow/src/pipeline/execute.rs:execute`, `lib/components/fabro-workflow/src/handler/mod.rs:Handler`
|
||||
- Owns: run operation lifecycle (create/start/resume/retry/rewind/fork/archive); workflow transform/validate/initialize/execute/finalize phases; node handler registry and built-in handlers; run-scoped services and cancellation; workflow event conversion/emission; checkpoint, Git, artifact, hook, and status lifecycles; steering and run control.
|
||||
- Depends on candidates: `fabro-acp`, `fabro-agent`, `fabro-checkpoint`, `fabro-dump`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-interview`, `fabro-llm`, `fabro-mcp`, `fabro-sandbox`, `fabro-store`, `fabro-tool`, `fabro-validate`
|
||||
- Evidence:
|
||||
- `lib/components/fabro-workflow/Cargo.toml` — defines the DOT-based workflow runner and declares the component dependencies used to assemble the engine.
|
||||
- `lib/components/fabro-workflow/src/pipeline/mod.rs` — exposes the ordered parse/transform/validate/initialize/execute/finalize phase boundary and its typed phase states.
|
||||
- `lib/components/fabro-workflow/src/handler/mod.rs:Handler` and `lib/components/fabro-workflow/src/lifecycle/mod.rs:WorkflowLifecycle` — connect node execution to the run-scoped lifecycle under the same engine.
|
||||
- `lib/components/fabro-workflow/tests/it/main.rs` and `lib/components/fabro-workflow/tests/materialize_run.rs` — exercise end-to-end orchestration and run materialization.
|
||||
- Scoped tracked files: 122
|
||||
|
||||
## Coverage
|
||||
|
||||
The fixed-revision inventory was computed with:
|
||||
|
||||
```text
|
||||
git ls-tree -r --name-only 2bcf94fed8a9b429f18d9196fa824711d6f4cb0a -- lib/components
|
||||
```
|
||||
|
||||
| Component glob | Assigned tracked files |
|
||||
| --- | ---: |
|
||||
| `lib/components/fabro-acp/**` | 8 |
|
||||
| `lib/components/fabro-agent/**` | 66 |
|
||||
| `lib/components/fabro-automation/**` | 9 |
|
||||
| `lib/components/fabro-checkpoint/**` | 7 |
|
||||
| `lib/components/fabro-dump/**` | 2 |
|
||||
| `lib/components/fabro-environment/**` | 7 |
|
||||
| `lib/components/fabro-github/**` | 4 |
|
||||
| `lib/components/fabro-graphviz/**` | 14 |
|
||||
| `lib/components/fabro-hooks/**` | 8 |
|
||||
| `lib/components/fabro-install/**` | 2 |
|
||||
| `lib/components/fabro-interview/**` | 10 |
|
||||
| `lib/components/fabro-llm/**` | 188 |
|
||||
| `lib/components/fabro-manifest/**` | 2 |
|
||||
| `lib/components/fabro-mcp/**` | 10 |
|
||||
| `lib/components/fabro-mcp-store/**` | 6 |
|
||||
| `lib/components/fabro-sandbox/**` | 23 |
|
||||
| `lib/components/fabro-slack/**` | 11 |
|
||||
| `lib/components/fabro-store/**` | 25 |
|
||||
| `lib/components/fabro-tool/**` | 12 |
|
||||
| `lib/components/fabro-tracker/**` | 5 |
|
||||
| `lib/components/fabro-validate/**` | 36 |
|
||||
| `lib/components/fabro-variable/**` | 3 |
|
||||
| `lib/components/fabro-workflow/**` | 122 |
|
||||
| **Total** | **580** |
|
||||
|
||||
- Relevant tracked files: 580
|
||||
- Assigned files: 580
|
||||
- Excluded files: 0
|
||||
- Unmapped files: 0
|
||||
- Duplicate claims: 0 (the proposed crate-directory globs are disjoint)
|
||||
|
||||
## Exclusions and unmapped files
|
||||
|
||||
- Evidence-backed exclusions: none.
|
||||
- Unmapped files: none.
|
||||
- Checked-in `.snap`, `.j2`, `.lark`, migration, README, and test-key files remain assigned because they specify or exercise component behavior.
|
||||
|
||||
## Boundary questions for reconciliation
|
||||
|
||||
1. Should `fabro-workflow` remain one engine component, as proposed, or be split into a public run-operations/materialization component and an execution component? `src/operations/**` and `src/pipeline/**` expose recognizable facades, but `services.rs`, `event.rs`, `runtime_store.rs`, the root modules, and lifecycle/handler code tie both facades to the same run-scoped state and make a non-overlapping ownership split less clear.
|
||||
2. Should `fabro-llm` remain one unified client component, as proposed, or should `src/providers/**`, `src/codec/**`, and `tests/it/wire/**` form a provider-protocol-adapters component? The adapter trait and wire-focused tests support that sub-boundary, while `adapter_registry.rs`, shared normalized types, transport helpers, and direct module references keep it inside one crate-level client lifecycle.
|
||||
3. Should `fabro-store` remain one persistence component, as proposed, or should its authorization-code/refresh-token stores be separated from run/event/blob persistence? `slate::Database` exposes them from one storage root, but their record lifecycles are consumed by server authentication rather than workflow execution.
|
||||
|
|
@ -1,389 +0,0 @@
|
|||
# Rust foundation cartography scout
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
|
||||
|
||||
Scope: all 365 tracked files under `lib/foundation/**`. Root and consumer manifests, the OpenAPI specification, and public consumer entry points were consulted only as boundary evidence and are not part of this scope's coverage counts.
|
||||
|
||||
Applicable instructions read: `AGENTS.md` and `CONTRIBUTING.md` (`CLAUDE.md` is a symlink to `AGENTS.md`).
|
||||
|
||||
## Boundary approach
|
||||
|
||||
- Most foundation crates are proposed as components in their own right because their manifests, crate-root facades, public state or lifecycle, focused tests, and reverse dependency edges describe a distinct responsibility.
|
||||
- `build-support` and `fabro-dev` are grouped as `fabro-build-tooling`: the two-file build-support crate would otherwise be too narrow for a stable assessment, and both crates serve repository build/development lifecycle rather than product runtime.
|
||||
- `fabro-macros` and `fabro-options-metadata` are grouped as `fabro-macros-metadata`: the proc-macro crate cannot expose runtime metadata itself, and the `OptionsMetadata` derive and runtime visitor model form one compiler/runtime contract. The proc-macro crate's `Combine` and `e2e_test` entry points remain part of that compiler-support component.
|
||||
- The small `fabro-http`, `fabro-proc`, and `fabro-static` crates remain separate. Each is a dependency hub with a distinct public policy boundary (HTTP construction/proxy policy, OS process primitives, and shared string registries respectively), so grouping them would mix independent reasons to change.
|
||||
- `fabro-types` and `fabro-util` remain crate-level components. Their crate-root facades and cross-module use are the stable public boundaries available at this revision; a finer file-family split would not have an independent manifest or facade and would create overlapping conceptual ownership.
|
||||
- Production and normal compile-time internal dependencies are listed below. Dev-only edges to `fabro-test` are omitted except for the test-support component itself.
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `fabro-build-tooling` — Fabro build and developer tooling
|
||||
|
||||
- **File count:** 23
|
||||
- **Purpose:** Runs repository development, build, documentation, SPA, container, benchmark, and release automation and supplies compile-time Git metadata to product build scripts.
|
||||
- **Globs:** `lib/foundation/build-support/**`, `lib/foundation/fabro-dev/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-dev/src/main.rs:main`, `lib/foundation/fabro-dev/src/lib.rs:run`, `lib/foundation/build-support/git_metadata.rs:collect_from`, `lib/foundation/build-support/git_metadata.rs:cargo_profile`
|
||||
- **Owns:** developer CLI command dispatch; subprocess plans for build/docs/SPA/Docker/release/test benchmarking; reference generation checks; compile-time Git SHA, rerun paths, and Cargo profile discovery.
|
||||
- **Depends on candidates:** `fabro-config`, `fabro-macros-metadata`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-dev/Cargo.toml` — declares an internal `fabro-dev` binary/library and integration-test target behind the `dev` feature.
|
||||
- `lib/foundation/fabro-dev/src/lib.rs:Command` — dispatches the build, Docker, docs, release, SPA, and benchmark command families.
|
||||
- `lib/foundation/fabro-dev/src/commands/mod.rs:PlannedCommand` — centralizes the subprocess lifecycle shared by those commands.
|
||||
- `lib/foundation/fabro-dev/tests/it/main.rs` — provides the integration-test composition root for the developer CLI.
|
||||
- `lib/foundation/build-support/Cargo.toml` and `lib/foundation/build-support/git_metadata.rs:BuildGitMetadata` — define a build-script-only support crate whose public result is embedded Git/build metadata; `lib/apps/fabro-cli/Cargo.toml` and `lib/apps/fabro-server/Cargo.toml` consume it as a build dependency.
|
||||
|
||||
### `fabro-api` — Generated API contract and Rust client
|
||||
|
||||
- **File count:** 60
|
||||
- **Purpose:** Generates the low-level Rust HTTP client and API type surface from the OpenAPI contract while reusing canonical Fabro domain types and verifying wire/type parity.
|
||||
- **Globs:** `lib/foundation/fabro-api/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-api/build.rs:main`, `lib/foundation/fabro-api/src/lib.rs:ApiClient`, `lib/foundation/fabro-api/src/lib.rs:types`
|
||||
- **Owns:** OpenAPI-to-Progenitor compatibility transformations; generated-client configuration; canonical type replacement map; low-level generated client facade; API/domain type identity and JSON round-trip tests.
|
||||
- **Depends on candidates:** `fabro-config`, `fabro-model`, `fabro-types`
|
||||
- **External dependency edges:** API types are also replaced with types from the `fabro-automation` and `fabro-environment` components.
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-api/Cargo.toml` — describes generated Rust types and HTTP client and declares `build.rs` generation dependencies.
|
||||
- `lib/foundation/fabro-api/build.rs:main` — reads `docs/public/api-reference/fabro-api.yaml`, patches the generator view, registers canonical type replacements, and writes `OUT_DIR/codegen.rs`.
|
||||
- `lib/foundation/fabro-api/src/lib.rs:generated` — includes the generated file behind a private module and exposes `ApiClient` plus a type facade.
|
||||
- `lib/foundation/fabro-api/tests/run_event_round_trip.rs:run_event_reuses_canonical_type` and the other `tests/*_round_trip.rs` files — verify type identity and OpenAPI JSON shape across the exported contract.
|
||||
- `docs/public/api-reference/fabro-api.yaml` — repository instructions identify this out-of-scope file as the HTTP contract source of truth.
|
||||
|
||||
### `fabro-auth` — Provider credential resolution
|
||||
|
||||
- **File count:** 16
|
||||
- **Purpose:** Resolves provider credentials and interpolated headers from environment or vault sources, refreshes OAuth credentials, and drives interactive authentication strategies.
|
||||
- **Globs:** `lib/foundation/fabro-auth/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver`, `lib/foundation/fabro-auth/src/credential_source.rs:CredentialSource`, `lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy`, `lib/foundation/fabro-auth/src/sql_vault_source.rs:SqlVaultCredentialSource`
|
||||
- **Owns:** provider credential-source precedence; API authorization/header material; configured-provider discovery; OAuth refresh and vault write-back; API-key and Codex-device login strategy state.
|
||||
- **Depends on candidates:** `fabro-http`, `fabro-model`, `fabro-oauth`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-vault`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-auth/Cargo.toml` — describes typed provider credential storage/resolution and declares the model, OAuth, redaction, vault, HTTP, and type dependencies.
|
||||
- `lib/foundation/fabro-auth/src/lib.rs` — exposes sources, resolver, strategies, refresh, and vault adapters as the crate facade.
|
||||
- `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve` — composes catalog policy, vault/environment lookup, header interpolation, and OAuth refresh into the provider-facing credential.
|
||||
- `lib/foundation/fabro-auth/src/credential_source.rs:CredentialSource` — provides the source abstraction used by environment, in-memory vault, and SQLite-backed vault implementations.
|
||||
- `lib/foundation/fabro-auth/src/sql_vault_source.rs:SqlVaultCredentialSource::persist_oauth_refreshes` — owns revision-aware persistence of refreshed OAuth state.
|
||||
|
||||
### `fabro-client` — High-level Fabro service client
|
||||
|
||||
- **File count:** 9
|
||||
- **Purpose:** Provides the high-level authenticated Fabro service client over HTTP or Unix sockets, including endpoint operations, SSE streams, token refresh, target normalization, and local CLI auth storage.
|
||||
- **Globs:** `lib/foundation/fabro-client/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-client/src/client.rs:Client::builder`, `lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect`, `lib/foundation/fabro-client/src/target.rs:ServerTarget`, `lib/foundation/fabro-client/src/auth_store.rs:AuthStore`, `lib/foundation/fabro-client/src/client.rs:RunEventStream`
|
||||
- **Owns:** connected client transport state; API operation wrappers and error classification; OAuth refresh coordination; HTTP/Unix target canonicalization; SSE buffering; per-server CLI authentication file and locking lifecycle.
|
||||
- **Depends on candidates:** `fabro-api`, `fabro-http`, `fabro-model`, `fabro-static`, `fabro-types`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-client/Cargo.toml` — distinguishes the typed high-level client from the generated `fabro-api` dependency.
|
||||
- `lib/foundation/fabro-client/src/client.rs:ClientState` and `Client` — own the generated client, raw HTTP client, bearer token, base URL, refresh lock, and optional transport reconnection.
|
||||
- `lib/foundation/fabro-client/src/target.rs:ServerTarget::build_public_http_client` — defines the HTTP-versus-Unix-socket transport boundary.
|
||||
- `lib/foundation/fabro-client/src/auth_store.rs:AuthStore` — owns the locked local authentication file lifecycle.
|
||||
- `lib/foundation/fabro-client/src/lib.rs` — exposes the client, streams, credential, error, session, store, and target facade consumed by CLI/server/tool applications.
|
||||
|
||||
### `fabro-config` — Layered configuration and runtime paths
|
||||
|
||||
- **File count:** 52
|
||||
- **Purpose:** Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical storage/runtime paths.
|
||||
- **Globs:** `lib/foundation/fabro-config/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder`, `lib/foundation/fabro-config/src/builders.rs:RunSettingsBuilder`, `lib/foundation/fabro-config/src/builders.rs:load_server_runtime_settings`, `lib/foundation/fabro-config/src/lib.rs:load_config_file`, `lib/foundation/fabro-config/src/resolve/mod.rs`
|
||||
- **Owns:** source-layer structs and merge semantics; built-in defaults; settings parsing/validation/resolution; configuration compatibility migrations; home, storage, runtime-directory, and run-scratch path conventions; daemon/envfile/log-filter configuration helpers.
|
||||
- **Depends on candidates:** `fabro-macros-metadata`, `fabro-model`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-config/Cargo.toml` — declares the centralized configuration crate and its optional `clap` integration.
|
||||
- `lib/foundation/fabro-config/src/lib.rs` — exposes layer types, builders, resolvers, parsing, storage, and runtime path facade.
|
||||
- `lib/foundation/fabro-config/src/builders.rs` — composes defaults and source layers into dense user, server, run, workflow, and model-catalog settings.
|
||||
- `lib/foundation/fabro-config/src/layers/combine.rs` and `lib/foundation/fabro-config/src/layers/*.rs` — define the layer merge contract and source-specific shapes.
|
||||
- `lib/foundation/fabro-config/src/migrations.rs` plus `lib/foundation/fabro-config/migrations/*.rs` — register and implement the settings-file migration lifecycle.
|
||||
- `lib/foundation/fabro-config/src/tests/*.rs` — exercise resolution independently for root, CLI, project, run, server, and workflow sources.
|
||||
|
||||
### `fabro-core` — Generic graph execution kernel
|
||||
|
||||
- **File count:** 13
|
||||
- **Purpose:** Executes generic directed workflow graphs with handler, retry, lifecycle, cancellation, checkpoint, visit-limit, and stall-monitoring contracts.
|
||||
- **Globs:** `lib/foundation/fabro-core/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-core/src/executor.rs:ExecutorBuilder`, `lib/foundation/fabro-core/src/executor.rs:Executor::run`, `lib/foundation/fabro-core/src/graph.rs:Graph`, `lib/foundation/fabro-core/src/handler.rs:NodeHandler`, `lib/foundation/fabro-core/src/lifecycle.rs:RunLifecycle`
|
||||
- **Owns:** in-memory execution state; node/edge traversal loop; handler and lifecycle extension contracts; retry/visit/cancellation decisions; stall-watchdog task lifecycle.
|
||||
- **Depends on candidates:** `fabro-types`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-core/Cargo.toml` — identifies the crate as the generic workflow execution engine without depending on the higher-level workflow component.
|
||||
- `lib/foundation/fabro-core/src/graph.rs` — defines generic graph, node, and edge contracts.
|
||||
- `lib/foundation/fabro-core/src/executor.rs:Executor::run` — owns the traversal and execution lifecycle.
|
||||
- `lib/foundation/fabro-core/src/state.rs:ExecutionState` — owns current node, outcomes, retries, visits, completed nodes, and context.
|
||||
- `lib/foundation/fabro-core/src/lifecycle.rs:RunLifecycle` and `lib/foundation/fabro-core/src/stall.rs:StallWatchdog` — expose the lifecycle hooks and owned background timeout task.
|
||||
- `lib/components/fabro-workflow/Cargo.toml` — out-of-scope consumer evidence that the product workflow component adapts this lower-level kernel.
|
||||
|
||||
### `fabro-db` — Shared SQLite database foundation
|
||||
|
||||
- **File count:** 9
|
||||
- **Purpose:** Opens and migrates the shared SQLite database, manages migration rollback snapshots and private file permissions, and defines the bundled schema migration set.
|
||||
- **Globs:** `lib/foundation/fabro-db/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-db/src/lib.rs:Database::connect`, `lib/foundation/fabro-db/src/lib.rs:Database::migrate`, `lib/foundation/fabro-db/src/lib.rs:Database::health_check`, `lib/foundation/fabro-db/src/lib.rs:DbPool`
|
||||
- **Owns:** SQLite pool setup; WAL/synchronous/busy-timeout policy; schema migration registry; pre-migration snapshot and legacy-backup paths; database file permissions; shared tables and indexes declared in `migrations/*.sql`.
|
||||
- **Depends on candidates:** `[]`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-db/Cargo.toml` — declares a SQLite storage foundation with SQLx migration support.
|
||||
- `lib/foundation/fabro-db/src/lib.rs:Database` — owns database connection, migration, snapshot, health-check, and pool access lifecycle.
|
||||
- `lib/foundation/fabro-db/migrations/*.sql` — define the variables, environments, secrets, MCP servers, automations, and run-projection schema compiled into this crate's migrator.
|
||||
- `lib/foundation/fabro-db/tests/sqlite.rs` — exercises migration, snapshot, permissions, and database behavior at the crate boundary.
|
||||
- `lib/components/fabro-variable/Cargo.toml`, `lib/components/fabro-environment/Cargo.toml`, `lib/components/fabro-mcp-store/Cargo.toml`, `lib/components/fabro-automation/Cargo.toml`, and `lib/components/fabro-store/Cargo.toml` — out-of-scope manifests show multiple persistence components sharing this foundation.
|
||||
|
||||
### `fabro-http` — Shared HTTP transport construction
|
||||
|
||||
- **File count:** 2
|
||||
- **Purpose:** Centralizes reqwest type exposure and synchronous/asynchronous HTTP client construction with Fabro's proxy and test no-proxy policy.
|
||||
- **Globs:** `lib/foundation/fabro-http/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-http/src/lib.rs:HttpClientBuilder`, `lib/foundation/fabro-http/src/lib.rs:http_client`, `lib/foundation/fabro-http/src/lib.rs:test_http_client`, `lib/foundation/fabro-http/src/lib.rs:BlockingHttpClientBuilder`
|
||||
- **Owns:** approved reqwest facade; proxy-policy resolution from `FABRO_HTTP_PROXY_POLICY`; async/blocking client builders; deterministic no-proxy test clients.
|
||||
- **Depends on candidates:** `fabro-static`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-http/Cargo.toml` — declares a shared reqwest-wrapper crate.
|
||||
- `lib/foundation/fabro-http/src/lib.rs:ProxyPolicy` and `HttpClientBuilder` — implement the shared transport-construction policy rather than domain HTTP behavior.
|
||||
- The root `Cargo.toml` exposes `fabro-http` as a workspace dependency, and app/component manifests consume it directly, establishing it as a cross-cutting transport boundary.
|
||||
|
||||
### `fabro-macros-metadata` — Compile-time macros and option metadata
|
||||
|
||||
- **File count:** 6
|
||||
- **Purpose:** Supplies Fabro's derive/attribute macros and the runtime option-metadata model used by generated configuration and documentation tooling.
|
||||
- **Globs:** `lib/foundation/fabro-macros/**`, `lib/foundation/fabro-options-metadata/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-macros/src/lib.rs:e2e_test`, `lib/foundation/fabro-macros/src/lib.rs:derive_combine`, `lib/foundation/fabro-macros/src/lib.rs:derive_options_metadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionSet`
|
||||
- **Owns:** macro input parsing and expansion for E2E mode gates, configuration-layer combination, and option metadata; option visitor/tree representation; flattened lookup/display/serialization of option metadata.
|
||||
- **Depends on candidates:** `[]`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-macros/Cargo.toml` — declares the proc-macro crate and a dev dependency on the runtime metadata crate.
|
||||
- `lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl` — generates implementations against `fabro_options_metadata::OptionsMetadata`.
|
||||
- `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata` and `OptionSet` — provide the runtime half of that generated contract.
|
||||
- `lib/foundation/fabro-macros/tests/options_metadata.rs` — tests the proc-macro/runtime pair together.
|
||||
- `lib/foundation/fabro-config/Cargo.toml` and `lib/foundation/fabro-dev/Cargo.toml` — out-of-scope consumer evidence for configuration derives and generated option documentation.
|
||||
|
||||
### `fabro-model` — LLM model and provider catalog
|
||||
|
||||
- **File count:** 28
|
||||
- **Purpose:** Defines provider/model identity, capabilities, billing metadata, embedded catalog data, override merging, and model selection.
|
||||
- **Globs:** `lib/foundation/fabro-model/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-model/src/catalog.rs:Catalog::builtin`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::from_builtin_with_overrides`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::select`, `lib/foundation/fabro-model/src/bootstrap_catalog.rs:catalog`, `lib/foundation/fabro-model/src/lib.rs`
|
||||
- **Owns:** canonical provider/model IDs; embedded provider TOML catalog; catalog indexes and selection state; provider auth declarations; model capabilities, controls, codecs/adapters, reasoning levels, pricing, and billing calculations.
|
||||
- **Depends on candidates:** `fabro-static`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-model/Cargo.toml` — names provider identity, model metadata, and resolution as the crate responsibility and embeds catalog resources.
|
||||
- `lib/foundation/fabro-model/src/catalog.rs:BuiltinCatalogToml` and `Catalog` — load embedded provider files into indexed selection state.
|
||||
- `lib/foundation/fabro-model/src/catalog/providers/*.toml` — are the tracked built-in provider/model catalog sources.
|
||||
- `lib/foundation/fabro-model/src/ids.rs` — defines open-ended provider and model identity shared by auth, config, API, and LLM consumers.
|
||||
- `lib/foundation/fabro-model/src/billing.rs` and `src/types.rs` — define the catalog's billing and public model metadata surfaces.
|
||||
|
||||
### `fabro-oauth` — OAuth PKCE and loopback callback flow
|
||||
|
||||
- **File count:** 3
|
||||
- **Purpose:** Implements generic OAuth 2.0 PKCE authorization, loopback callback serving, browser launch, code exchange, and token refresh.
|
||||
- **Globs:** `lib/foundation/fabro-oauth/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow`, `lib/foundation/fabro-oauth/src/lib.rs:start_callback_server_with_errors`, `lib/foundation/fabro-oauth/src/lib.rs:exchange_code`, `lib/foundation/fabro-oauth/src/lib.rs:refresh_token`, `lib/foundation/fabro-oauth/examples/login.rs:main`
|
||||
- **Owns:** PKCE verifier/challenge and state generation; authorization URL encoding; ephemeral callback listener/task and shutdown handle; callback validation/result delivery; token response decoding and refresh requests.
|
||||
- **Depends on candidates:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-oauth/Cargo.toml` — declares a generic OAuth 2.0 PKCE token-acquisition crate.
|
||||
- `lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle` — owns the ephemeral callback server port and shutdown channel.
|
||||
- `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow` — composes PKCE, callback server, browser, and token exchange into the top-level flow.
|
||||
- `lib/foundation/fabro-oauth/examples/login.rs` — demonstrates the crate as a standalone protocol flow.
|
||||
- `lib/foundation/fabro-auth/Cargo.toml` and `lib/apps/fabro-cli/Cargo.toml` — out-of-scope manifests establish both auth-library and direct CLI consumers.
|
||||
|
||||
### `fabro-proc` — OS process primitives
|
||||
|
||||
- **File count:** 8
|
||||
- **Purpose:** Wraps platform process primitives for signals, process groups, advisory file locking, pre-exec hooks, process liveness, and process-title rewriting.
|
||||
- **Globs:** `lib/foundation/fabro-proc/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-proc/src/lib.rs`, `lib/foundation/fabro-proc/src/signal.rs:process_running`, `lib/foundation/fabro-proc/src/signal.rs:sigterm_process_group`, `lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid`, `lib/foundation/fabro-proc/src/title.rs:init`
|
||||
- **Owns:** Unix signal/process-group calls; cross-platform liveness semantics; advisory locks; child pre-exec configuration; captured argv memory and process title state.
|
||||
- **Depends on candidates:** `[]`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-proc/Cargo.toml` — describes safe wrappers for process-management primitives and compiles the C argv capture helper.
|
||||
- `lib/foundation/fabro-proc/src/lib.rs` — is a platform-gated facade over flock, pre-exec, signal, and title modules.
|
||||
- `lib/foundation/fabro-proc/c/capture_argv.c` and `lib/foundation/fabro-proc/build.rs` — establish the FFI/build boundary for title rewriting.
|
||||
- `lib/apps/fabro-server/Cargo.toml`, `lib/apps/fabro-cli/Cargo.toml`, and `lib/components/fabro-sandbox/Cargo.toml` — out-of-scope manifests show independent process-lifecycle consumers.
|
||||
|
||||
### `fabro-redact` — Secret and credential redaction
|
||||
|
||||
- **File count:** 8
|
||||
- **Purpose:** Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded Gitleaks rules and entropy scanning.
|
||||
- **Globs:** `lib/foundation/fabro-redact/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-redact/src/lib.rs:redact_string`, `lib/foundation/fabro-redact/src/lib.rs:redacted_url_for_log`, `lib/foundation/fabro-redact/src/jsonl.rs:redact_jsonl_line`, `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl`
|
||||
- **Owns:** Gitleaks rule source and generated rule table; lazy rule engine; entropy thresholds; overlap merging and redaction marker; JSON field/object skip policy; safe URL display semantics.
|
||||
- **Depends on candidates:** `[]`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-redact/Cargo.toml` — declares the secret/credential redaction boundary.
|
||||
- `lib/foundation/fabro-redact/build.rs:main` and `lib/foundation/fabro-redact/data/gitleaks.toml` — compile the tracked rule source into an untracked `OUT_DIR` table.
|
||||
- `lib/foundation/fabro-redact/src/lib.rs:redact_string` — composes entropy and Gitleaks detection into one public redaction surface.
|
||||
- `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl` — owns the raw-versus-display URL credential boundary.
|
||||
- `lib/foundation/fabro-redact/src/jsonl.rs` — applies the scanner to structured event/log content.
|
||||
|
||||
### `fabro-static` — Shared static conventions
|
||||
|
||||
- **File count:** 4
|
||||
- **Purpose:** Defines dependency-light canonical environment-variable names and the registry that classifies bootstrap and optional-vault secrets.
|
||||
- **Globs:** `lib/foundation/fabro-static/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-static/src/env_vars.rs:EnvVars`, `lib/foundation/fabro-static/src/secret_registry.rs:is_bootstrap_secret`, `lib/foundation/fabro-static/src/secret_registry.rs:optional_vault_secrets`
|
||||
- **Owns:** canonical process environment string constants; bootstrap-secret set; optional vault-secret set and classification.
|
||||
- **Depends on candidates:** `[]`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-static/Cargo.toml` — declares a no-dependency static string registry.
|
||||
- `lib/foundation/fabro-static/src/env_vars.rs:EnvVars` — centralizes environment names consumed across applications, components, and foundation crates.
|
||||
- `lib/foundation/fabro-static/src/secret_registry.rs` — defines secret scope independently of vault/auth implementations.
|
||||
- The root `Cargo.toml` exposes the crate as a workspace dependency, and `fabro-http`, `fabro-model`, `fabro-util`, auth, telemetry, server, CLI, sandbox, Slack, and GitHub manifests consume it.
|
||||
|
||||
### `fabro-telemetry` — Analytics and crash telemetry
|
||||
|
||||
- **File count:** 11
|
||||
- **Purpose:** Initializes analytics/crash reporting, builds anonymous telemetry context, buffers events, and hands delivery to blocking or detached senders across CLI and server lifecycles.
|
||||
- **Globs:** `lib/foundation/fabro-telemetry/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-telemetry/src/lib.rs:init_cli`, `lib/foundation/fabro-telemetry/src/lib.rs:init_server`, `lib/foundation/fabro-telemetry/src/lib.rs:track`, `lib/foundation/fabro-telemetry/src/lib.rs:shutdown`, `lib/foundation/fabro-telemetry/src/panic.rs:install_panic_hook`
|
||||
- **Owns:** process-global telemetry state; anonymous CLI/server identifiers; background buffer thread and shutdown join; analytics event shape/context; command sanitization; Segment delivery and detached subprocess handoff; Sentry panic capture.
|
||||
- **Depends on candidates:** `fabro-http`, `fabro-static`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-telemetry/Cargo.toml` — declares analytics and crash reporting with HTTP, Sentry, Git, and process-spawn dependencies.
|
||||
- `lib/foundation/fabro-telemetry/src/lib.rs:Global` — owns the process-global sender, identity, context, level, and background thread.
|
||||
- `lib/foundation/fabro-telemetry/src/buffer.rs` and `src/sender.rs` — define buffered delivery and upload boundaries.
|
||||
- `lib/foundation/fabro-telemetry/src/spawn.rs` — owns the detached subprocess handoff used at process exit.
|
||||
- `lib/foundation/fabro-telemetry/src/panic.rs` — owns panic-hook event construction and capture.
|
||||
|
||||
### `fabro-template` — Template rendering and dependency discovery
|
||||
|
||||
- **File count:** 4
|
||||
- **Purpose:** Renders MiniJinja templates with Fabro context, source-aware diagnostics, rooted include stores, caching/recording wrappers, and static dependency discovery.
|
||||
- **Globs:** `lib/foundation/fabro-template/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-template/src/lib.rs:render_source`, `lib/foundation/fabro-template/src/lib.rs:render_named`, `lib/foundation/fabro-template/src/lib.rs:TemplateContext`, `lib/foundation/fabro-template/src/store.rs:TemplateStore`, `lib/foundation/fabro-template/src/dependency.rs:discover_static_dependency_closure`
|
||||
- **Owns:** template context/value exposure; strict and lenient render modes; source-location error diagnostics; include/import path safety and rooted resolution; filesystem/bundle/cache/recording stores; static dependency closure.
|
||||
- **Depends on candidates:** `fabro-types`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-template/Cargo.toml` — declares the shared MiniJinja rendering boundary.
|
||||
- `lib/foundation/fabro-template/src/lib.rs:TemplateContext` and `TemplateError` — define the public render input and source-aware failure surface.
|
||||
- `lib/foundation/fabro-template/src/store.rs:TemplateStore` and `TemplateIncludeResolver` — define source loading and root containment.
|
||||
- `lib/foundation/fabro-template/src/dependency.rs` — owns include/import extraction and dependency-closure discovery.
|
||||
- `lib/components/fabro-agent/Cargo.toml`, `lib/components/fabro-workflow/Cargo.toml`, and `lib/components/fabro-manifest/Cargo.toml` — out-of-scope manifests show agent, workflow, and manifest consumers.
|
||||
|
||||
### `fabro-test` — Shared integration-test infrastructure
|
||||
|
||||
- **File count:** 3
|
||||
- **Purpose:** Provides isolated Fabro CLI/server integration-test contexts, twin/live mode control, process and environment harnessing, snapshot normalization, and HTTP assertion helpers.
|
||||
- **Globs:** `lib/foundation/fabro-test/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-test/src/lib.rs:TestContext`, `lib/foundation/fabro-test/src/lib.rs:TestMode`, `lib/foundation/fabro-test/src/lib.rs:apply_test_isolation`, `lib/foundation/fabro-test/src/lib.rs:test_http_client`, `lib/foundation/fabro-test/src/http_assert.rs:expect_reqwest_status`
|
||||
- **Owns:** per-test temporary home/storage/session/server lifecycle; E2E mode and live-secret gating; subprocess environment isolation; test daemon coordination; snapshot filters; twin service setup; Axum/reqwest response assertion diagnostics.
|
||||
- **Depends on candidates:** `fabro-config`, `fabro-http`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util`
|
||||
- **External dependency edges:** depends on the `fabro-install`, `twin-openai`, and `twin-github` test components.
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-test/Cargo.toml` — identifies the crate as integration-test utilities and declares test-only component/twin dependencies.
|
||||
- `lib/foundation/fabro-test/src/lib.rs:TestContext` — owns isolated test paths, session state, Fabro binary invocation, filters, and managed server/storage state.
|
||||
- `lib/foundation/fabro-test/src/lib.rs:TestMode` and `apply_test_isolation` — define the twin/live/strict and environment-isolation contracts used by the `e2e_test` macro.
|
||||
- `lib/foundation/fabro-test/src/http_assert.rs` — centralizes response consumption and diagnostic assertion behavior for both server and network tests.
|
||||
- Workspace app/component manifests list `fabro-test` only in dev-dependency/test contexts.
|
||||
|
||||
### `fabro-types` — Shared product contracts and state records
|
||||
|
||||
- **File count:** 78
|
||||
- **Purpose:** Defines the serializable identifiers, settings records, run/session/event/state projections, and other shared product vocabulary exchanged across Fabro crates and API boundaries.
|
||||
- **Globs:** `lib/foundation/fabro-types/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-types/src/lib.rs`, `lib/foundation/fabro-types/src/run_event/mod.rs:RunEvent`, `lib/foundation/fabro-types/src/run.rs:RunSpec`, `lib/foundation/fabro-types/src/settings/mod.rs`, `lib/foundation/fabro-types/src/outcome.rs:Outcome`, `lib/foundation/fabro-types/src/status.rs:RunStatus`
|
||||
- **Owns:** canonical serde shapes and IDs for runs, stages, sessions, events, transcripts, outcomes, status, projections, sandboxes, MCP servers, variables, secrets, integrations, billing, repositories, pull requests, and dense/resolved settings; feature-gated shared test fixtures.
|
||||
- **Depends on candidates:** `fabro-model`, `fabro-util`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-types/Cargo.toml` — describes shared record structs/enums and exposes only `clap` and `test-support` feature boundaries.
|
||||
- `lib/foundation/fabro-types/src/lib.rs` — is a single crate facade that re-exports the canonical shared product vocabulary across its module families.
|
||||
- `lib/foundation/fabro-types/src/run_event/mod.rs` and `src/run_event/*.rs` — define the event contract consumed by workflow, storage, server, client, and API code.
|
||||
- `lib/foundation/fabro-types/src/settings/mod.rs` and `src/settings/*.rs` — define the resolved settings contract consumed by `fabro-config` and runtime components.
|
||||
- `lib/foundation/fabro-types/tests/*.rs` — verify serde and method contracts for run specs, events, failures, sandbox models, inventory, and stage handlers.
|
||||
- `lib/foundation/fabro-api/build.rs` and its round-trip tests — boundary evidence that API generation intentionally reuses these types rather than generating parallel DTOs.
|
||||
|
||||
### `fabro-util` — Cross-cutting runtime and CLI utilities
|
||||
|
||||
- **File count:** 24
|
||||
- **Purpose:** Provides shared environment, filesystem, shell, terminal, logging, token, error-rendering, time, backoff, warning, and workspace-glob primitives used across Fabro crates.
|
||||
- **Globs:** `lib/foundation/fabro-util/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-util/src/lib.rs`, `lib/foundation/fabro-util/src/shell.rs:shell_quote`, `lib/foundation/fabro-util/src/printer.rs:Printer`, `lib/foundation/fabro-util/src/home.rs:Home`, `lib/foundation/fabro-util/src/run_log.rs:BufferedFileAppender`, `lib/foundation/fabro-util/src/workspace_glob.rs:WorkspaceGlobSet`
|
||||
- **Owns:** low-level helper contracts and any helper-owned state, including the global warning set, buffered run-log guard, environment abstraction, home directory, dev/session token formats, terminal styles/printers, backoff policy, error-chain rendering, and workspace glob compilation.
|
||||
- **Depends on candidates:** `fabro-static`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-util/Cargo.toml` — identifies shared terminal/path/environment/runtime helpers and has no product-component dependencies.
|
||||
- `lib/foundation/fabro-util/src/lib.rs` — exposes the helper modules directly as the public crate facade.
|
||||
- `lib/foundation/fabro-util/src/shell.rs` — owns shell quoting/joining used by workflow and developer tooling.
|
||||
- `lib/foundation/fabro-util/src/run_log.rs` and `src/warnings.rs` — contain the component's stateful log-guard and warning-registry lifecycles.
|
||||
- `lib/foundation/fabro-util/tests/dev_token.rs` and `tests/error_chain.rs` — test stable token-file and error-rendering contracts.
|
||||
|
||||
### `fabro-vault` — Secret vault and SQLite secret store
|
||||
|
||||
- **File count:** 4
|
||||
- **Purpose:** Validates and stores workflow-visible secrets in file/in-memory vaults or the shared SQLite database, including revision-aware updates and one-time legacy import.
|
||||
- **Globs:** `lib/foundation/fabro-vault/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `lib/foundation/fabro-vault/src/lib.rs:Vault::load`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::open`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::apply`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::snapshot`, `lib/foundation/fabro-vault/src/store.rs:import_legacy_json_once`
|
||||
- **Owns:** secret-name/type validation; redacted secret entry representation; atomic JSON vault persistence; SQL secret CRUD; secret revisions and compare-and-swap refresh updates; snapshots; legacy JSON import and backup lifecycle.
|
||||
- **Depends on candidates:** `fabro-db`, `fabro-static`, `fabro-types`
|
||||
- **Evidence:**
|
||||
- `lib/foundation/fabro-vault/Cargo.toml` — declares the workflow-visible secret vault and its database/type dependencies.
|
||||
- `lib/foundation/fabro-vault/src/lib.rs:Vault` — owns file-backed or detached in-memory entries and atomic write behavior.
|
||||
- `lib/foundation/fabro-vault/src/store.rs:SecretStore` — owns the SQLite-backed secret operations and snapshots.
|
||||
- `lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision` — exposes the revision boundary used for concurrent OAuth refresh write-back.
|
||||
- `lib/foundation/fabro-vault/tests/store.rs` — exercises store CRUD, validation, snapshots, and legacy import at the public boundary.
|
||||
|
||||
## Coverage
|
||||
|
||||
| Proposed component | Tracked files |
|
||||
| --- | ---: |
|
||||
| `fabro-build-tooling` | 23 |
|
||||
| `fabro-api` | 60 |
|
||||
| `fabro-auth` | 16 |
|
||||
| `fabro-client` | 9 |
|
||||
| `fabro-config` | 52 |
|
||||
| `fabro-core` | 13 |
|
||||
| `fabro-db` | 9 |
|
||||
| `fabro-http` | 2 |
|
||||
| `fabro-macros-metadata` | 6 |
|
||||
| `fabro-model` | 28 |
|
||||
| `fabro-oauth` | 3 |
|
||||
| `fabro-proc` | 8 |
|
||||
| `fabro-redact` | 8 |
|
||||
| `fabro-static` | 4 |
|
||||
| `fabro-telemetry` | 11 |
|
||||
| `fabro-template` | 4 |
|
||||
| `fabro-test` | 3 |
|
||||
| `fabro-types` | 78 |
|
||||
| `fabro-util` | 24 |
|
||||
| `fabro-vault` | 4 |
|
||||
| **Total assigned** | **365** |
|
||||
|
||||
- **Relevant tracked files:** 365
|
||||
- **Assigned:** 365
|
||||
- **Excluded:** 0
|
||||
- **Unmapped:** 0
|
||||
- **Overlap:** 0; every proposed glob is a whole crate directory, and the two grouped components use disjoint crate directories.
|
||||
- **Tracked exclusions:** none. Build outputs such as `OUT_DIR/codegen.rs` and `OUT_DIR/rules_generated.rs` are generated but are not tracked and therefore are not part of the 365-file inventory. No vendored or generated tracked source was found in scope.
|
||||
- **Unmapped files:** `[]`
|
||||
|
||||
## External boundary evidence consulted
|
||||
|
||||
These files are outside the scoped inventory and are neither assigned nor counted as unmapped:
|
||||
|
||||
- `Cargo.toml` — workspace membership, workspace dependencies, and lint policy.
|
||||
- `docs/public/api-reference/fabro-api.yaml` — source contract read by `fabro-api/build.rs`.
|
||||
- `lib/apps/fabro-cli/Cargo.toml`, `lib/apps/fabro-server/Cargo.toml`, `lib/apps/fabro-mcp-server/Cargo.toml` — application-level reverse dependency evidence.
|
||||
- Relevant `lib/components/*/Cargo.toml` manifests — reverse dependency evidence for execution, storage, schema, types, templates, auth, HTTP, process, test, and API foundations.
|
||||
|
||||
## Genuine boundary questions
|
||||
|
||||
1. Should `build-support` remain grouped with `fabro-dev` in the final map, or should its compile-time consumer boundary make it a separate two-file component despite the resulting assessment granularity?
|
||||
2. Should `fabro-macros` and `fabro-options-metadata` remain one component? Their `OptionsMetadata` compiler/runtime contract supports grouping, while `Combine` and `e2e_test` also connect the proc-macro crate to configuration and test infrastructure.
|
||||
3. Should the SQL migration files under `fabro-db/migrations/**` remain with the shared database foundation, or should reconciliation assign table-specific migrations to the variable, environment, MCP-store, automation, and run-store components that own the corresponding query behavior? The current proposal follows compile-time ownership by `fabro-db`.
|
||||
4. Is `fabro-types` an acceptable single assessment component, or does the final map need stable subcomponents for settings, run/event/projection, and other contract families? This revision exposes one manifest and one broad crate facade, so this scout found no non-overlapping public boundary for such a split.
|
||||
|
|
@ -1,332 +0,0 @@
|
|||
# Cartography scout report: tests and evaluations
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` (`2bcf94fed`)
|
||||
|
||||
Scope: all 180 tracked files under `test/**` and `evals/**`. Cargo workspace
|
||||
manifests, test consumers, repository documentation sources, and implementation
|
||||
entry points were consulted only as boundary evidence and are not included in
|
||||
this scope's counts.
|
||||
|
||||
Applicable instructions read: `AGENTS.md`, `CONTRIBUTING.md`, and
|
||||
`docs/internal/testing-strategy.md` (`CLAUDE.md` is a symlink to `AGENTS.md`).
|
||||
|
||||
## Boundary decisions
|
||||
|
||||
- `twin-openai` and `twin-github` are separate components. Each is a distinct
|
||||
Cargo workspace member with its own protocol surface, router, state model,
|
||||
lifecycle, fixtures, and consumers. Their common use as local fake services
|
||||
is not enough to combine OpenAI scenario/stream behavior with GitHub
|
||||
repository/authentication behavior.
|
||||
- The checked-in workflow fixtures outside `test/docs/**` are proposed as a
|
||||
shared `workflow-test-corpus` component. They are all user-facing workflow,
|
||||
configuration, prompt, and template inputs, and they are intentionally
|
||||
consumed across CLI, workflow, graph-language, rendering, and validation
|
||||
tests. Keeping them together avoids assigning shared compatibility data to
|
||||
one arbitrary production consumer.
|
||||
- `test/docs/**` is proposed as a separate
|
||||
`documentation-workflow-tests` component. It has its own extraction and
|
||||
multi-phase runner entry points and owns a documentation-derived but curated
|
||||
executable corpus. The tracked fixtures are test source: the checklist
|
||||
records extracted, assembled, and adapted cases, and `run_tests.sh` executes
|
||||
them directly. They are therefore assigned rather than excluded as generated
|
||||
output.
|
||||
- The SWE-bench tooling is a distinct evaluation component. It owns a
|
||||
generation, grading, monitoring, environment-generation, and result-recording
|
||||
workflow that is independent of the normal Cargo test lifecycle.
|
||||
- `evals/swe-bench/scoreboard/**` is not executable evaluation source. The
|
||||
evaluation README calls it a Git-tracked permanent record, and
|
||||
`record_results.py` writes every tracked file shape beneath it. Those 16
|
||||
recorded outputs are proposed as a global exclusion.
|
||||
- The two distribution shell tests and the benchmark-analysis SQL do not form a
|
||||
coherent component together. They are recommended additions to existing
|
||||
components, described after the component proposals.
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `twin-openai` — OpenAI protocol twin
|
||||
|
||||
- **File count:** 35 (28 Rust, 5 Markdown, 1 Cargo manifest, 1 `.gitignore`)
|
||||
- **Purpose:** Provides a deterministic OpenAI-compatible HTTP service for
|
||||
black-box and protocol-contract tests, including scripted successes,
|
||||
failures, streaming, request inspection, and live shape comparison.
|
||||
- **Globs:** `test/twin/openai/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `test/twin/openai/src/main.rs:main`,
|
||||
`test/twin/openai/src/lib.rs:build_app`,
|
||||
`test/twin/openai/src/lib.rs:build_app_with_config`,
|
||||
`test/twin/openai/src/app.rs:router`
|
||||
- **Owns:** server bind/configuration lifecycle; `/v1/responses` and
|
||||
`/v1/chat/completions` request/response contracts; bearer-token namespaces;
|
||||
FIFO scenario queues; deterministic response IDs; normalized request logs;
|
||||
SSE construction and transport-failure behavior; admin reset/scenario APIs;
|
||||
debug UI and snapshots; local and opt-in live contract suites.
|
||||
- **Depends on candidates:** `fabro-http`, `fabro-static`
|
||||
- **Evidence:**
|
||||
- `Cargo.toml` — lists `test/twin/openai` as a workspace member and exposes
|
||||
`twin-openai` as a workspace dependency.
|
||||
- `test/twin/openai/Cargo.toml` — declares a non-published library/binary
|
||||
package described as a fake OpenAI-compatible server.
|
||||
- `test/twin/openai/src/app.rs:router` and
|
||||
`test/twin/openai/src/openai/mod.rs:router` — compose the health, OpenAI,
|
||||
admin, and debug HTTP surfaces.
|
||||
- `test/twin/openai/src/state.rs:AppState` — owns namespaced response
|
||||
counters, scenario queues, and request logs.
|
||||
- `test/twin/openai/src/engine/scenario.rs:ScenarioScript` — defines scripted
|
||||
success, application-error, delay, partial/malformed stream, and hang
|
||||
behavior.
|
||||
- `test/twin/openai/tests/common/mod.rs:spawn_server` and the eight sibling
|
||||
contract suites — exercise the service as a protocol boundary; the ignored
|
||||
`live_openai_contract.rs` compares supported protocol shapes with the live
|
||||
API.
|
||||
- `lib/foundation/fabro-test/Cargo.toml` and
|
||||
`lib/foundation/fabro-test/src/lib.rs:twin_openai` — show the shared
|
||||
integration-test harness consuming this package as an in-process service.
|
||||
|
||||
### `twin-github` — GitHub protocol twin
|
||||
|
||||
- **File count:** 20 (17 Rust, 2 PEM fixtures, 1 Cargo manifest)
|
||||
- **Purpose:** Provides an in-process fake GitHub service with seeded mutable
|
||||
state and temporary Git repositories for black-box GitHub App, OAuth, API,
|
||||
GraphQL, and smart-HTTP tests.
|
||||
- **Globs:** `test/twin/github/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `test/twin/github/src/server.rs:TestServer::start`,
|
||||
`test/twin/github/src/server.rs:build_router`,
|
||||
`test/twin/github/src/state.rs:AppState`,
|
||||
`test/twin/github/src/fixtures.rs:FixtureState::into_app_state`
|
||||
- **Owns:** ephemeral listener and shutdown lifecycle; temporary bare Git
|
||||
repositories; fake apps, installations, repositories, branches, pull
|
||||
requests, releases, projects, comments, webhook configuration, manifest
|
||||
conversions, access tokens, OAuth codes/tokens/users; GitHub authentication
|
||||
checks; bundled test RSA key pair.
|
||||
- **Depends on candidates:** `fabro-http`
|
||||
- **Evidence:**
|
||||
- `Cargo.toml` — lists `test/twin/github` independently as a workspace member
|
||||
and workspace dependency.
|
||||
- `test/twin/github/Cargo.toml` — declares a non-published library package
|
||||
described as a fake GitHub API server.
|
||||
- `test/twin/github/src/handlers/mod.rs:build_router` — registers the GitHub
|
||||
App, installation, branch, pull-request, manifest, OAuth, user, release,
|
||||
GraphQL, and Git smart-HTTP routes.
|
||||
- `test/twin/github/src/state.rs:AppState` — owns the central seeded and
|
||||
mutable GitHub-domain state.
|
||||
- `test/twin/github/src/server.rs:TestServer::start` — initializes temporary
|
||||
Git repositories, binds an ephemeral listener, and controls graceful
|
||||
shutdown.
|
||||
- `test/twin/github/src/fixtures.rs:FixtureState` and
|
||||
`test/twin/github/src/testdata/*.pem` — define reusable seeded service data
|
||||
and the owned authentication fixtures.
|
||||
- `lib/foundation/fabro-test/src/lib.rs:TwinGitHub` and
|
||||
`lib/apps/fabro-cli/tests/it/support/auth_harness.rs` — show this twin
|
||||
serving the CLI/server authentication integration boundary.
|
||||
|
||||
### `workflow-test-corpus` — Shared workflow compatibility fixtures
|
||||
|
||||
- **File count:** 42
|
||||
- 8 root `test/*.fabro` workflows
|
||||
- 14 `test/attractor/*.dot` compatibility graphs
|
||||
- 3 `test/dot-compatibility/*.fabro` graphs
|
||||
- 17 templating/configuration files under the four templated fixture trees
|
||||
- **Purpose:** Supplies reusable user-facing workflow, compatibility,
|
||||
configuration, prompt, partial, and template inputs to cross-crate parser,
|
||||
validator, renderer, workflow, and CLI tests.
|
||||
- **Globs:** `test/*.fabro`, `test/attractor/**`,
|
||||
`test/dot-compatibility/**`, `test/templated_inputs/**`,
|
||||
`test/templated_unbound_imported/**`,
|
||||
`test/templated_unbound_partial/**`, `test/templates/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `test/simple.fabro`,
|
||||
`test/attractor/simple_example.dot`,
|
||||
`test/dot-compatibility/acp-agent-chain.fabro`,
|
||||
`test/templates/static_dependencies/workflow.fabro`,
|
||||
`test/templates/sibling_partial/workflow.fabro`
|
||||
- **Owns:** representative valid and invalid workflow shapes; branching,
|
||||
conditions, parallelism, styles, and legacy syntax cases; Attractor DOT
|
||||
compatibility graphs; shared DOT parse/render/validation cases; template
|
||||
input, import, include, sibling-partial, static-dependency, and
|
||||
missing-dependency fixture trees.
|
||||
- **Depends on candidates:** `fabro-cli`, `fabro-graphviz`, `fabro-template`,
|
||||
`fabro-test`, `fabro-validate`, `fabro-workflow`
|
||||
- **Evidence:**
|
||||
- `docs/internal/testing-strategy.md` — explicitly recognizes checked-in
|
||||
user-facing workflows, configs, prompts, and repository contents as shared
|
||||
fixtures.
|
||||
- `lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture` —
|
||||
resolves named inputs from the repository `test/` directory for isolated
|
||||
CLI tests.
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/validate.rs` and
|
||||
`lib/apps/fabro-cli/tests/it/workflow/dry_run_examples.rs` — consume the
|
||||
root workflows and all templating fixture trees as black-box CLI inputs.
|
||||
- `lib/components/fabro-workflow/tests/it/attractor_compat.rs` — enumerates
|
||||
and parses every graph in `test/attractor/**`.
|
||||
- `lib/components/fabro-graphviz/src/render.rs:dot_compatibility_fixtures`
|
||||
and
|
||||
`lib/components/fabro-validate/src/lib.rs:dot_compatibility_fixtures` —
|
||||
independently enumerate the same three `test/dot-compatibility/**` inputs,
|
||||
establishing that corpus as shared rather than crate-local.
|
||||
|
||||
### `documentation-workflow-tests` — Documentation workflow conformance
|
||||
|
||||
- **File count:** 55 (40 Fabro workflows, 7 shell files, 5 Markdown files, 2
|
||||
run TOML files, 1 Python extractor)
|
||||
- **Purpose:** Extracts, curates, validates, preflights, and executes workflow
|
||||
examples and companion files derived from Fabro documentation.
|
||||
- **Globs:** `test/docs/**`
|
||||
- **Exclude globs:** `[]`
|
||||
- **Entry points:** `test/docs/run_tests.sh`,
|
||||
`test/docs/extract_dots.py:main`, `test/docs/CHECKLIST.md`
|
||||
- **Owns:** documentation-example corpus layout; prompt and script stubs;
|
||||
variable-bearing run configurations; extraction naming and stub generation;
|
||||
validate/preflight/dry-run/live phase selection; parallel execution and
|
||||
temporary result/run directories; the documented corpus checklist.
|
||||
- **Depends on candidates:** `fabro-cli`, `fabro-workflow`, the final
|
||||
documentation-site component
|
||||
- **Evidence:**
|
||||
- `test/docs/run_tests.sh:run_one` — discovers all 40 tracked `*.fabro`
|
||||
examples and invokes the built `fabro` binary in validate, preflight,
|
||||
dry-run, model-specific, or full execution modes.
|
||||
- `test/docs/extract_dots.py:main` — reads documentation Markdown, extracts
|
||||
complete DOT graphs, and creates companion prompt stubs and run
|
||||
configurations under `test/docs`.
|
||||
- `test/docs/CHECKLIST.md` — documents the 40-example corpus, distinguishes
|
||||
extracted and assembled cases, records companion-file needs, and provides
|
||||
the runner commands.
|
||||
- `.claude/skills/docs/SKILL.md` — instructs documentation changes containing
|
||||
full DOT graphs to run `./test/docs/run_tests.sh validate`, tying this
|
||||
harness to the documentation change lifecycle.
|
||||
|
||||
### `swe-bench-evaluation` — SWE-bench evaluation workflow
|
||||
|
||||
- **File count:** 9 (6 Python scripts, 1 Fabro workflow, 1 requirements file, 1
|
||||
README)
|
||||
- **Purpose:** Generates Fabro patches for SWE-bench Lite instances, grades
|
||||
them through Daytona or the official harness, monitors runs, and records
|
||||
normalized result summaries.
|
||||
- **Globs:** `evals/swe-bench/*.py`, `evals/swe-bench/*.fabro`,
|
||||
`evals/swe-bench/*.txt`, `evals/swe-bench/README.md`
|
||||
- **Exclude globs:** `[]` (the sibling scoreboard is a global exclusion)
|
||||
- **Entry points:** `evals/swe-bench/run_eval.py:main`,
|
||||
`evals/swe-bench/evaluate_daytona.py:main`,
|
||||
`evals/swe-bench/evaluate.py:main`,
|
||||
`evals/swe-bench/record_results.py:main`,
|
||||
`evals/swe-bench/status.py:main`,
|
||||
`evals/swe-bench/gen_dockerfile.py:main`
|
||||
- **Owns:** SWE-bench Lite dataset selection; per-instance goal/workflow/TOML
|
||||
generation; Daytona snapshot and sandbox specifications; Fabro subprocess
|
||||
orchestration and timeout cleanup; patch extraction; official and
|
||||
Daytona-based grading; progress summaries; scoreboard record schema and
|
||||
leaderboard regeneration.
|
||||
- **Depends on candidates:** `fabro-cli`, `fabro-sandbox`,
|
||||
`fabro-workflow`
|
||||
- **External dependencies:** Hugging Face `datasets`, the `swebench` harness,
|
||||
Daytona, and optionally Docker through the official harness.
|
||||
- **Evidence:**
|
||||
- `evals/swe-bench/README.md` — defines the three-stage generate, evaluate,
|
||||
and record lifecycle, the two grading backends, and raw-versus-recorded
|
||||
result locations.
|
||||
- `evals/swe-bench/run_eval.py:run_instance` — creates per-instance Fabro
|
||||
workflows/configs, invokes `fabro run`, and extracts produced patches.
|
||||
- `evals/swe-bench/evaluate_daytona.py` — creates grading workflows and
|
||||
executes held-out tests in Daytona snapshots.
|
||||
- `evals/swe-bench/evaluate.py:main` — exposes the alternative official
|
||||
Docker-backed `swebench.harness.run_evaluation` path.
|
||||
- `evals/swe-bench/gen_dockerfile.py:generate_dockerfile` — translates
|
||||
SWE-bench repository/version specs into reusable sandbox images.
|
||||
- `evals/swe-bench/record_results.py:main` and
|
||||
`regenerate_leaderboard` — define and write the tracked scoreboard record
|
||||
formats.
|
||||
|
||||
## Recommended additions to existing components
|
||||
|
||||
These files are assigned in the coverage accounting but do not justify new
|
||||
components:
|
||||
|
||||
| File | Recommended component | Reason |
|
||||
| --- | --- | --- |
|
||||
| `test/bin/install_test.sh` | documentation/web scout's marketing-site component | It is a black-box shell contract test whose sole product target is `apps/marketing/public/install.sh`; it owns a fake `gh` executable and temporary install home only for that test. |
|
||||
| `test/bin/release_test.sh` | `fabro-build-tooling` | It is an executable release-mode shell contract and changes with the repository release-automation lifecycle. |
|
||||
| `test/analysis/bench-tests-diff.sql` | `fabro-build-tooling` | Its documented inputs are the two CSVs produced by `cargo dev bench-tests`, whose implementation is `lib/foundation/fabro-dev/src/commands/bench_tests.rs`. |
|
||||
|
||||
## Global exclusion
|
||||
|
||||
### Recorded SWE-bench scoreboards
|
||||
|
||||
- **Globs:** `evals/swe-bench/scoreboard/**`
|
||||
- **Tracked files:** 16 (1 leaderboard JSON plus 5 run directories containing
|
||||
one `README.md`, one `meta.json`, and one `instances.jsonl` each)
|
||||
- **Reason:** committed evaluation records generated by
|
||||
`evals/swe-bench/record_results.py`, not executable evaluation source.
|
||||
- **Evidence:** `evals/swe-bench/README.md` calls the directory a Git-tracked
|
||||
permanent record; `record_results.py` writes `instances.jsonl`, `meta.json`,
|
||||
each run `README.md`, and regenerates `leaderboard.json`.
|
||||
|
||||
Raw `evals/swe-bench/results/**` data is also described as generated output,
|
||||
but it is not tracked at the assessed revision and therefore is not part of
|
||||
the 180-file inventory.
|
||||
|
||||
No `test/docs/**` files are excluded. Although the extractor derives some
|
||||
files from documentation, the tracked corpus includes assembled/adapted
|
||||
executable fixtures and companion stubs/configuration, and the runner consumes
|
||||
those files as test inputs.
|
||||
|
||||
## Coverage
|
||||
|
||||
| Assignment | Tracked files |
|
||||
| --- | ---: |
|
||||
| `twin-openai` | 35 |
|
||||
| `twin-github` | 20 |
|
||||
| `workflow-test-corpus` | 42 |
|
||||
| `documentation-workflow-tests` | 55 |
|
||||
| `swe-bench-evaluation` | 9 |
|
||||
| Recommended addition to marketing-site component | 1 |
|
||||
| Recommended additions to `fabro-build-tooling` | 2 |
|
||||
| Global exclusion: SWE-bench scoreboards | 16 |
|
||||
| **Scoped inventory** | **180** |
|
||||
|
||||
- **Assigned:** 164 (161 in proposed test/evaluation components and 3 additions
|
||||
to existing components)
|
||||
- **Excluded:** 16
|
||||
- **Unmapped:** 0
|
||||
- **Overlap:** 0
|
||||
- **Accounting check:** `164 + 16 + 0 = 180`
|
||||
- **Unmapped files:** `[]`
|
||||
|
||||
## External boundary evidence consulted
|
||||
|
||||
These files are outside the scoped inventory and are neither assigned nor
|
||||
counted as unmapped:
|
||||
|
||||
- `Cargo.toml` — workspace membership and workspace dependency declarations for
|
||||
both twin services.
|
||||
- `lib/foundation/fabro-test/Cargo.toml` and
|
||||
`lib/foundation/fabro-test/src/lib.rs` — shared fixture installation and twin
|
||||
service consumption.
|
||||
- `lib/apps/fabro-cli/tests/it/**` — black-box workflow fixture and twin-GitHub
|
||||
consumers.
|
||||
- `lib/components/fabro-workflow/tests/it/attractor_compat.rs` — Attractor
|
||||
corpus consumer.
|
||||
- `lib/components/fabro-graphviz/src/render.rs` and
|
||||
`lib/components/fabro-validate/src/lib.rs` — shared DOT compatibility corpus
|
||||
consumers.
|
||||
- `docs/internal/testing-strategy.md` — repository test-layer and fixture
|
||||
ownership policy.
|
||||
- `.claude/skills/docs/SKILL.md` — documentation test-runner invocation policy.
|
||||
- `apps/marketing/public/install.sh` — install shell-test target.
|
||||
- `lib/foundation/fabro-dev/src/commands/bench_tests.rs` — benchmark CSV
|
||||
producer consumed by the analysis SQL.
|
||||
|
||||
## Genuine boundary questions
|
||||
|
||||
1. Should `workflow-test-corpus` remain a distinct 42-file shared data
|
||||
component, as proposed, or should reconciliation distribute its three
|
||||
subcorpora to `fabro-cli` (25 general/template fixtures),
|
||||
`fabro-workflow` (14 Attractor fixtures), and `fabro-graphviz` (3 shared DOT
|
||||
compatibility fixtures)? The cross-crate consumers support a shared
|
||||
boundary, while the production behaviors they exercise support attachment.
|
||||
2. Should `documentation-workflow-tests` remain a separate executable harness,
|
||||
or should its 55 files be included in the documentation-site component?
|
||||
Its runner and phase lifecycle support separation; its source derivation and
|
||||
documentation-change trigger support inclusion with documentation.
|
||||
3. Should `test/bin/release_test.sh` be assigned to `fabro-build-tooling` as a
|
||||
release-lifecycle contract, or remain separately unmapped until the final
|
||||
map determines which current release entry point owns that shell contract?
|
||||
|
|
@ -1,271 +0,0 @@
|
|||
import { execFileSync } from "node:child_process";
|
||||
import { readFileSync, writeFileSync } from "node:fs";
|
||||
|
||||
function fail(message) {
|
||||
throw new Error(message);
|
||||
}
|
||||
|
||||
function globRegex(glob) {
|
||||
let source = "^";
|
||||
for (let index = 0; index < glob.length; index += 1) {
|
||||
const character = glob[index];
|
||||
if (character === "*") {
|
||||
if (glob[index + 1] === "*") {
|
||||
source += ".*";
|
||||
index += 1;
|
||||
} else {
|
||||
source += "[^/]*";
|
||||
}
|
||||
} else if (character === "?") {
|
||||
source += "[^/]";
|
||||
} else {
|
||||
source += character.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
|
||||
}
|
||||
}
|
||||
return new RegExp(`${source}$`);
|
||||
}
|
||||
|
||||
function matchesAny(path, globs) {
|
||||
return globs.some((glob) => globRegex(glob).test(path));
|
||||
}
|
||||
|
||||
function requireKeys(value, expected, label) {
|
||||
const actual = Object.keys(value).sort();
|
||||
const wanted = [...expected].sort();
|
||||
if (JSON.stringify(actual) !== JSON.stringify(wanted)) {
|
||||
fail(
|
||||
`${label} keys differ\nexpected ${JSON.stringify(wanted)}\nfound ${JSON.stringify(actual)}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
function referencedPath(reference) {
|
||||
return reference.split(" — ", 1)[0].split(":", 1)[0];
|
||||
}
|
||||
|
||||
function validate(map) {
|
||||
requireKeys(
|
||||
map,
|
||||
[
|
||||
"schema_version",
|
||||
"cartography_version",
|
||||
"created_at",
|
||||
"repository",
|
||||
"instructions",
|
||||
"overview",
|
||||
"global_exclusions",
|
||||
"components",
|
||||
"unmapped_files",
|
||||
"coverage",
|
||||
"open_questions",
|
||||
],
|
||||
"map",
|
||||
);
|
||||
requireKeys(
|
||||
map.repository,
|
||||
["name", "root", "revision", "short_revision"],
|
||||
"repository",
|
||||
);
|
||||
requireKeys(
|
||||
map.coverage,
|
||||
[
|
||||
"relevant_file_count",
|
||||
"assigned_file_count",
|
||||
"excluded_file_count",
|
||||
"unmapped_file_count",
|
||||
],
|
||||
"coverage",
|
||||
);
|
||||
if (map.schema_version !== 1) fail("schema_version must be 1");
|
||||
if (map.cartography_version !== 1) fail("cartography_version must be 1");
|
||||
|
||||
const files = execFileSync(
|
||||
"git",
|
||||
["ls-tree", "-r", "--name-only", map.repository.revision],
|
||||
{ encoding: "utf8" },
|
||||
)
|
||||
.trim()
|
||||
.split("\n")
|
||||
.filter(Boolean);
|
||||
const fileSet = new Set(files);
|
||||
const ids = map.components.map(({ id }) => id);
|
||||
if (new Set(ids).size !== ids.length) fail("component IDs are not unique");
|
||||
for (const id of ids) {
|
||||
if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id)) {
|
||||
fail(`invalid component ID: ${id}`);
|
||||
}
|
||||
}
|
||||
|
||||
const allGlobs = [];
|
||||
for (const exclusion of map.global_exclusions) {
|
||||
requireKeys(exclusion, ["globs", "reason"], "global exclusion");
|
||||
allGlobs.push(...exclusion.globs);
|
||||
}
|
||||
for (const component of map.components) {
|
||||
requireKeys(
|
||||
component,
|
||||
[
|
||||
"id",
|
||||
"name",
|
||||
"purpose",
|
||||
"globs",
|
||||
"exclude_globs",
|
||||
"entry_points",
|
||||
"owns",
|
||||
"depends_on",
|
||||
"evidence",
|
||||
],
|
||||
`component ${component.id}`,
|
||||
);
|
||||
allGlobs.push(...component.globs, ...component.exclude_globs);
|
||||
for (const dependency of component.depends_on) {
|
||||
if (!ids.includes(dependency)) {
|
||||
fail(`${component.id} depends on missing component ${dependency}`);
|
||||
}
|
||||
if (dependency === component.id) {
|
||||
fail(`${component.id} depends on itself`);
|
||||
}
|
||||
}
|
||||
for (const reference of [...component.entry_points, ...component.evidence]) {
|
||||
const path = referencedPath(reference);
|
||||
if (!fileSet.has(path)) {
|
||||
fail(`${component.id} references missing path ${path}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
for (const instruction of map.instructions) {
|
||||
if (!fileSet.has(instruction)) fail(`missing instruction ${instruction}`);
|
||||
}
|
||||
for (const glob of allGlobs) {
|
||||
if (!files.some((path) => globRegex(glob).test(path))) {
|
||||
fail(`glob resolves to no tracked files: ${glob}`);
|
||||
}
|
||||
}
|
||||
|
||||
const excluded = new Set(
|
||||
files.filter((path) =>
|
||||
map.global_exclusions.some(({ globs }) => matchesAny(path, globs)),
|
||||
),
|
||||
);
|
||||
const claims = new Map();
|
||||
for (const component of map.components) {
|
||||
for (const path of files) {
|
||||
if (
|
||||
matchesAny(path, component.globs) &&
|
||||
!matchesAny(path, component.exclude_globs)
|
||||
) {
|
||||
if (excluded.has(path)) {
|
||||
fail(`${path} is both globally excluded and claimed by ${component.id}`);
|
||||
}
|
||||
const previous = claims.get(path);
|
||||
if (previous) {
|
||||
fail(`${path} is claimed by both ${previous} and ${component.id}`);
|
||||
}
|
||||
claims.set(path, component.id);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
for (const path of map.unmapped_files) {
|
||||
if (!fileSet.has(path)) fail(`unmapped file does not exist: ${path}`);
|
||||
if (excluded.has(path) || claims.has(path)) {
|
||||
fail(`unmapped file also has another disposition: ${path}`);
|
||||
}
|
||||
}
|
||||
const unmapped = new Set(map.unmapped_files);
|
||||
const missing = files.filter(
|
||||
(path) => !claims.has(path) && !excluded.has(path) && !unmapped.has(path),
|
||||
);
|
||||
if (missing.length > 0) {
|
||||
fail(`files lack a disposition:\n${missing.join("\n")}`);
|
||||
}
|
||||
|
||||
const computed = {
|
||||
relevant_file_count: files.length,
|
||||
assigned_file_count: claims.size,
|
||||
excluded_file_count: excluded.size,
|
||||
unmapped_file_count: unmapped.size,
|
||||
};
|
||||
if (JSON.stringify(computed) !== JSON.stringify(map.coverage)) {
|
||||
fail(
|
||||
`coverage mismatch\nexpected ${JSON.stringify(computed)}\nfound ${JSON.stringify(map.coverage)}`,
|
||||
);
|
||||
}
|
||||
if (
|
||||
computed.assigned_file_count +
|
||||
computed.excluded_file_count +
|
||||
computed.unmapped_file_count !==
|
||||
computed.relevant_file_count
|
||||
) {
|
||||
fail("coverage counts do not add up");
|
||||
}
|
||||
return computed;
|
||||
}
|
||||
|
||||
function inline(values) {
|
||||
return values.map((value) => `\`${value}\``).join(", ");
|
||||
}
|
||||
|
||||
function render(map) {
|
||||
const lines = [
|
||||
"# Chisel Codebase Map",
|
||||
"",
|
||||
`Cartography v${map.cartography_version} · revision \`${map.repository.revision}\` · ${map.created_at}`,
|
||||
`Assigned ${map.coverage.assigned_file_count} files · excluded ${map.coverage.excluded_file_count} · unmapped ${map.coverage.unmapped_file_count} · instructions: ${map.instructions.join(", ")}`,
|
||||
"",
|
||||
map.overview,
|
||||
"",
|
||||
"## Components",
|
||||
];
|
||||
|
||||
for (const component of map.components) {
|
||||
lines.push(
|
||||
"",
|
||||
`### \`${component.id}\` — ${component.name}`,
|
||||
"",
|
||||
`- **Purpose:** ${component.purpose}`,
|
||||
`- **Paths:** ${inline(component.globs)}`,
|
||||
);
|
||||
if (component.exclude_globs.length > 0) {
|
||||
lines.push(`- **Excludes:** ${inline(component.exclude_globs)}`);
|
||||
}
|
||||
if (component.entry_points.length > 0) {
|
||||
lines.push(`- **Entry points:** ${inline(component.entry_points)}`);
|
||||
}
|
||||
if (component.owns.length > 0) {
|
||||
lines.push(`- **Owns:** ${component.owns.join("; ")}`);
|
||||
}
|
||||
if (component.depends_on.length > 0) {
|
||||
lines.push(`- **Depends on:** ${inline(component.depends_on)}`);
|
||||
}
|
||||
if (component.evidence.length > 0) {
|
||||
lines.push(`- **Evidence:** ${component.evidence.join("; ")}`);
|
||||
}
|
||||
}
|
||||
|
||||
if (map.global_exclusions.length > 0 || map.unmapped_files.length > 0) {
|
||||
lines.push("", "## Exclusions and Unmapped Code", "");
|
||||
for (const exclusion of map.global_exclusions) {
|
||||
lines.push(`- ${inline(exclusion.globs)} — ${exclusion.reason}`);
|
||||
}
|
||||
for (const path of map.unmapped_files) {
|
||||
lines.push(`- \`${path}\` — unmapped`);
|
||||
}
|
||||
}
|
||||
|
||||
if (map.open_questions.length > 0) {
|
||||
lines.push("", "## Open Questions", "");
|
||||
for (const question of map.open_questions) {
|
||||
lines.push(`- ${question}`);
|
||||
}
|
||||
}
|
||||
lines.push("");
|
||||
return lines.join("\n");
|
||||
}
|
||||
|
||||
const [inputPath, outputPath] = process.argv.slice(2);
|
||||
if (!inputPath) fail("usage: validate-render.mjs <map.json> [map.md]");
|
||||
const map = JSON.parse(readFileSync(inputPath, "utf8"));
|
||||
const coverage = validate(map);
|
||||
if (outputPath) writeFileSync(outputPath, render(map));
|
||||
process.stdout.write(`${JSON.stringify(coverage)}\n`);
|
||||
|
|
@ -1,305 +0,0 @@
|
|||
# JavaScript/TypeScript cartography proposal
|
||||
|
||||
Assessed revision: `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a`
|
||||
|
||||
Owned scout scope: every tracked file under `apps/**` and
|
||||
`lib/packages/**` at the assessed revision. `package.json`, `bun.lock`, and
|
||||
`docs/public/api-reference/fabro-api.yaml` were consulted only as dependency
|
||||
evidence and are not included in the scope counts. Applicable repository
|
||||
instructions are `AGENTS.md` (the `CLAUDE.md` project instructions) and
|
||||
`CONTRIBUTING.md`.
|
||||
|
||||
## Boundary decisions
|
||||
|
||||
- `apps/fabro-web` contains three coherent assessable responsibilities, not
|
||||
just one directory-shaped component:
|
||||
- the normal-mode React application, shared browser runtime, and bundle
|
||||
production;
|
||||
- the alternate first-run installation mode, with its own route graph,
|
||||
reducer/form lifecycle, session token, API facade, and focused tests;
|
||||
- the workflow playground subtree, which explicitly defines a standalone
|
||||
prop boundary and owns a browser-persisted workflow draft, graph
|
||||
simulation, chat adapter, and generated project files.
|
||||
- The marketing site and Remotion project are separate applications. Each has
|
||||
its own package manifest, framework entry point, build command, assets, and
|
||||
output/deployment lifecycle.
|
||||
- The hand-written Fabro API client generation package is an assessable
|
||||
component, but its checked-in `src/**` tree is generator output and should
|
||||
be excluded from assessment. The distinction and counts are documented
|
||||
below.
|
||||
|
||||
## Proposed components
|
||||
|
||||
### `fabro-web-app` — Fabro browser application
|
||||
|
||||
- **Purpose:** Build and run the normal-mode React SPA for run operations,
|
||||
chats, automations, insights, settings, profiles, and their shared browser
|
||||
infrastructure.
|
||||
- **Tracked files:** 309.
|
||||
- **Globs:** `apps/fabro-web/**`
|
||||
- **Exclude globs (assigned to sibling components):**
|
||||
`apps/fabro-web/app/components/playground/**`,
|
||||
`apps/fabro-web/app/install-*`,
|
||||
`apps/fabro-web/app/mode.ts`,
|
||||
`apps/fabro-web/app/mode.test.ts`,
|
||||
`apps/fabro-web/app/hooks/use-install-effects.ts`
|
||||
- **Entry points:** `apps/fabro-web/scripts/build.ts:main`,
|
||||
`apps/fabro-web/app/entry.tsx`,
|
||||
`apps/fabro-web/app/router.tsx:routes`,
|
||||
`apps/fabro-web/index.template.html`
|
||||
- **Owns:** Browser bundle assembly and content-hashed publication under
|
||||
`dist/`; the normal-mode route graph; run, chat, automation, insight,
|
||||
settings, and profile UX; shared API/query/mutation/event-stream adapters;
|
||||
app-wide layouts, components, hooks, browser view preferences, and public
|
||||
UI assets.
|
||||
- **Depends-on candidates:** `fabro-web-install` (alternate route graph
|
||||
composed by the browser entry), `fabro-workflow-playground` (route-level
|
||||
feature composition), `fabro-api-client-generation` (through its generated
|
||||
package output), and the parent map's server HTTP/API-contract component
|
||||
(likely `fabro-server` and/or `fabro-api`).
|
||||
- **Evidence:**
|
||||
- `apps/fabro-web/package.json` — declares a private React application,
|
||||
custom build/dev commands, browser dependencies, tests, and a workspace
|
||||
dependency on `@qltysh/fabro-api-client`.
|
||||
- `apps/fabro-web/scripts/build.ts:main` — bundles
|
||||
`app/entry.tsx`, compiles Tailwind CSS, copies public/worker assets, writes
|
||||
the HTML shell, publishes a content-addressed build, and provides the
|
||||
watch lifecycle.
|
||||
- `apps/fabro-web/app/entry.tsx` — creates the React root, browser router,
|
||||
SWR runtime, build-version guard, and toaster, then selects the normal or
|
||||
install route graph.
|
||||
- `apps/fabro-web/app/router.tsx:routes` — explicitly composes the
|
||||
normal-mode route tree for chats, playground, automations, runs, insights,
|
||||
settings, and profile pages beneath the app shell.
|
||||
- `apps/fabro-web/app/lib/api-client.ts` and
|
||||
`apps/fabro-web/app/lib/queries.ts` — form the browser-side API and query
|
||||
integration boundary used across normal-mode routes.
|
||||
|
||||
### `fabro-web-install` — First-run browser installer
|
||||
|
||||
- **Purpose:** Drive the browser-only first-run installation workflow that
|
||||
configures server URL, object storage, sandbox, LLM providers, and GitHub
|
||||
before finishing installation.
|
||||
- **Tracked files:** 14.
|
||||
- **Globs:** `apps/fabro-web/app/install-*`,
|
||||
`apps/fabro-web/app/mode.ts`,
|
||||
`apps/fabro-web/app/mode.test.ts`,
|
||||
`apps/fabro-web/app/hooks/use-install-effects.ts`
|
||||
- **Exclude globs:** none.
|
||||
- **Entry points:** `apps/fabro-web/app/install-router.tsx:installRoutes`,
|
||||
`apps/fabro-web/app/install-app.tsx:InstallApp`,
|
||||
`apps/fabro-web/app/mode.ts:resolveFabroMode`
|
||||
- **Owns:** The `install` browser mode; installation step navigation and form
|
||||
reducer state; install-session query lifecycle; the
|
||||
`fabro-install-token` session-storage value; URL token/GitHub callback
|
||||
consumption; install-specific validation, persistence, finish, and restart
|
||||
health-poll behavior.
|
||||
- **Depends-on candidates:** `fabro-web-app` for the shared root, common UI,
|
||||
hooks, and browser API transport; `fabro-api-client-generation` through
|
||||
generated Install DTOs/API methods; and the parent map's server
|
||||
installation/API-contract component.
|
||||
- **Evidence:**
|
||||
- `apps/fabro-web/app/entry.tsx` — selects `installRoutes` instead of the
|
||||
normal `routes` when `window.__FABRO_MODE__` resolves to `install`.
|
||||
- `apps/fabro-web/app/install-router.tsx:installRoutes` — defines a separate
|
||||
catch-all route graph centered on `InstallApp`.
|
||||
- `apps/fabro-web/app/install-app.tsx` — owns the seven-step install flow
|
||||
and its installation-specific reducer/form state.
|
||||
- `apps/fabro-web/app/install-api.ts` — wraps generated Install API methods
|
||||
and owns the session-storage token contract.
|
||||
- `docs/public/api-reference/fabro-api.yaml` — dependency evidence outside
|
||||
owned scope: declares the `Install` tag as the first-run browser install
|
||||
workflow.
|
||||
|
||||
### `fabro-workflow-playground` — Browser workflow playground
|
||||
|
||||
- **Purpose:** Provide a self-contained workflow drafting, simulation, chat,
|
||||
visualization, file-generation, download, and run-launch surface.
|
||||
- **Tracked files:** 44.
|
||||
- **Globs:** `apps/fabro-web/app/components/playground/**`
|
||||
- **Exclude globs:** none.
|
||||
- **Entry points:**
|
||||
`apps/fabro-web/app/components/playground/playground.tsx:Playground`
|
||||
- **Owns:** The `WorkflowDraft` graph schema and reducer; the versioned
|
||||
`fabro:playground:draft:v1` local-storage document; draft validation and
|
||||
animation; workflow simulation state; canvas rendering; playground chat/SSE
|
||||
adaptation; `workflow.fabro`, TOML, and README rendering; download and
|
||||
real-run launch controls.
|
||||
- **Depends-on candidates:** `fabro-web-app` for a small set of shared chat,
|
||||
graph-theme, dynamic-import, event-hook, and test utilities; and the parent
|
||||
map's server component for `/api/v1/playground/chat` and `/api/v1/runs`.
|
||||
- **Evidence:**
|
||||
- `apps/fabro-web/app/components/playground/playground.tsx:Playground` —
|
||||
exposes `chatEndpoint`, `authMode`, and optional redirect props and states
|
||||
that the subtree is framed for re-embedding without the app shell or
|
||||
app-wide stores.
|
||||
- `apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft` —
|
||||
defines the complete workflow document and describes it as a
|
||||
self-contained, re-embeddable island.
|
||||
- `apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft`
|
||||
— owns reducer-driven browser persistence and the versioned storage key.
|
||||
- `apps/fabro-web/app/components/playground/chat/runtime.ts:createPlaygroundAdapter`
|
||||
— adapts chat turns and streamed tool calls into draft changes.
|
||||
- `apps/fabro-web/app/routes/playground.tsx:PlaygroundRoute` — integration
|
||||
evidence in the sibling app component: mounts the feature at
|
||||
`/playground` and supplies its endpoint/auth contract.
|
||||
|
||||
### `fabro-marketing-site` — Fabro marketing site
|
||||
|
||||
- **Purpose:** Build and deploy the public Fabro site, including product
|
||||
landing content, blog, roadmap, showcase, install resources, and social
|
||||
metadata/assets.
|
||||
- **Tracked files:** 51 assigned; two generated Vercel link files excluded
|
||||
below.
|
||||
- **Globs:** `apps/marketing/**`
|
||||
- **Exclude globs:** `apps/marketing/.vercel/**`
|
||||
- **Entry points:** `apps/marketing/astro.config.mjs`,
|
||||
`apps/marketing/src/pages/index.astro`,
|
||||
`apps/marketing/src/content.config.ts`
|
||||
- **Owns:** Astro page routing and layout; global marketing presentation;
|
||||
blog, roadmap, and showcase content collections; workflow showcase
|
||||
rendering; public install script/instructions and brand/social assets;
|
||||
public redirects and Vercel deployment configuration.
|
||||
- **Depends-on candidates:** none within this scout's assessable components.
|
||||
It has framework dependencies and renders workflow graphs via Viz.js but
|
||||
does not import another repository workspace.
|
||||
- **Evidence:**
|
||||
- `apps/marketing/package.json` — declares an independent private Astro
|
||||
application with dev/build/preview lifecycle.
|
||||
- `apps/marketing/astro.config.mjs` — integrates React/Tailwind and defines
|
||||
public redirects.
|
||||
- `apps/marketing/src/content.config.ts` — defines separately typed roadmap,
|
||||
blog, and showcase content collections whose source documents are owned
|
||||
under `src/content/**`.
|
||||
- `apps/marketing/src/pages/**` — Astro's file-based entries own the landing,
|
||||
roadmap, blog, and showcase URL surfaces.
|
||||
- `apps/marketing/vercel.json` — owns production redirect behavior for the
|
||||
deployed site.
|
||||
|
||||
### `fabro-remotion-video` — Fabro Remotion composition
|
||||
|
||||
- **Purpose:** Render the branded `FabroIntro` motion-graphics video.
|
||||
- **Tracked files:** 9.
|
||||
- **Globs:** `apps/remotion/**`
|
||||
- **Exclude globs:** none.
|
||||
- **Entry points:** `apps/remotion/src/index.ts`,
|
||||
`apps/remotion/src/Root.tsx:RemotionRoot`,
|
||||
`apps/remotion/src/FabroIntro.tsx:FabroIntro`
|
||||
- **Owns:** The `FabroIntro` composition registration, 1920x1080/30fps/150
|
||||
frame timeline, image-format configuration, logo animation, brand assets,
|
||||
and `out/intro.mp4` render lifecycle.
|
||||
- **Depends-on candidates:** none within this scout's assessable components.
|
||||
- **Evidence:**
|
||||
- `apps/remotion/package.json` — declares an independent Remotion project
|
||||
whose studio and render/build scripts target composition `FabroIntro`.
|
||||
- `apps/remotion/src/index.ts` — registers the Remotion root.
|
||||
- `apps/remotion/src/Root.tsx:RemotionRoot` — declares the composition ID,
|
||||
component, dimensions, frame rate, and duration.
|
||||
- `apps/remotion/src/FabroIntro.tsx:FabroIntro` — owns the composition's
|
||||
animation timeline and use of the two local public assets.
|
||||
|
||||
### `fabro-api-client-generation` — TypeScript API client generation contract
|
||||
|
||||
- **Purpose:** Configure, normalize, and type-check the generated
|
||||
TypeScript/Axios client for the Fabro OpenAPI contract.
|
||||
- **Tracked files:** 6 assigned; 554 generated/output files excluded below.
|
||||
- **Globs:** `lib/packages/fabro-api-client/package.json`,
|
||||
`lib/packages/fabro-api-client/openapitools.json`,
|
||||
`lib/packages/fabro-api-client/scripts/**`,
|
||||
`lib/packages/fabro-api-client/tests/**`,
|
||||
`lib/packages/fabro-api-client/tsconfig.json`
|
||||
- **Exclude globs:** `lib/packages/fabro-api-client/src/**`
|
||||
- **Entry points:**
|
||||
`lib/packages/fabro-api-client/package.json:scripts.generate`,
|
||||
`lib/packages/fabro-api-client/scripts/normalize-generated.ts`
|
||||
- **Owns:** OpenAPI Generator CLI/template options and version selection;
|
||||
output location; deterministic whitespace normalization; strict TypeScript
|
||||
compilation of output; hand-written exhaustiveness/invariant checks for
|
||||
generated discriminated unions and API shapes.
|
||||
- **Depends-on candidates:** the parent map's `fabro-api`/OpenAPI-contract
|
||||
component, whose source is
|
||||
`docs/public/api-reference/fabro-api.yaml`.
|
||||
- **Evidence:**
|
||||
- `lib/packages/fabro-api-client/package.json` — `generate` invokes pinned
|
||||
OpenAPI Generator CLI `2.20.2`, reads the repository OpenAPI YAML, selects
|
||||
`typescript-axios` with separate model/API packages and tag-based APIs,
|
||||
writes to `src`, then runs the normalizer.
|
||||
- `lib/packages/fabro-api-client/openapitools.json` — selects generator
|
||||
version `7.20.0`.
|
||||
- `lib/packages/fabro-api-client/scripts/normalize-generated.ts` — is
|
||||
explicitly hand-written normalization logic and scans exactly
|
||||
`src/**/*.ts`.
|
||||
- `lib/packages/fabro-api-client/tests/principal-exhaustive.ts` and
|
||||
`tests/reasoning-output-invariant.ts` — hand-written compile-time
|
||||
assertions over generated types.
|
||||
- `lib/packages/fabro-api-client/tsconfig.json` — type-checks both
|
||||
`src/**/*` and `tests/**/*`.
|
||||
|
||||
## Evidence-backed exclusions
|
||||
|
||||
### Generated TypeScript/Axios client output
|
||||
|
||||
- **Glob:** `lib/packages/fabro-api-client/src/**`
|
||||
- **Count:** 554 tracked files: 551 TypeScript files and three generator
|
||||
bookkeeping/ignore files
|
||||
(`.openapi-generator/FILES`, `.openapi-generator/VERSION`, and
|
||||
`.openapi-generator-ignore`).
|
||||
- **Reason/evidence:**
|
||||
- The hand-written package script directs OpenAPI Generator to `-o src`.
|
||||
- 550 of the 551 TypeScript files carry the literal header
|
||||
`NOTE: This class is auto generated by OpenAPI Generator` and
|
||||
`Do not edit the class manually`.
|
||||
- The only TypeScript file without that header is
|
||||
`src/models/index.ts`; it is explicitly named in
|
||||
`src/.openapi-generator/FILES`.
|
||||
- `src/.openapi-generator/FILES` contains 545 generated path entries and
|
||||
`src/.openapi-generator/VERSION` records `7.20.0`.
|
||||
- Six additional TypeScript files are not in that `FILES` snapshot, but
|
||||
each has the same auto-generation marker:
|
||||
`models/daytona-network-layer-one-of-allow-list.ts`,
|
||||
`models/daytona-network-layer-one-of.ts`,
|
||||
`models/daytona-network-layer.ts`, `models/docker-settings.ts`,
|
||||
`models/run-projection-checkpoints-inner-inner.ts`, and
|
||||
`models/sandbox-provider.ts`.
|
||||
- Therefore the stable exclusion is the output-root glob `src/**`, not only
|
||||
the metadata's current list or only marker-bearing files.
|
||||
|
||||
### Vercel CLI link metadata
|
||||
|
||||
- **Glob:** `apps/marketing/.vercel/**`
|
||||
- **Count:** 2 tracked files.
|
||||
- **Reason/evidence:** `apps/marketing/.vercel/README.txt` states that the
|
||||
folder is automatically created when linking a directory to a Vercel
|
||||
project, describes `project.json` as the linked project/team IDs, and says
|
||||
the directory should not be committed/shared. These are generated local
|
||||
deployment-link records rather than marketing-site source.
|
||||
|
||||
## Computed coverage
|
||||
|
||||
| Category | Count |
|
||||
| --- | ---: |
|
||||
| Tracked files in owned scope | 989 |
|
||||
| Assigned to proposed components | 433 |
|
||||
| Evidence-backed excluded | 556 |
|
||||
| Unmapped | 0 |
|
||||
|
||||
Assigned counts are `309 + 14 + 44 + 51 + 9 + 6 = 433`. Excluded counts are
|
||||
`554 + 2 = 556`. The total is `433 + 556 + 0 = 989`. No file is claimed by
|
||||
two proposed components.
|
||||
|
||||
## Open questions
|
||||
|
||||
1. Should the 14-file first-run installer remain a separate component in the
|
||||
final map? Its alternate route graph, lifecycle, state, and API boundary
|
||||
support the split, but it imports shared web UI/runtime code while the
|
||||
shared browser entry imports its route graph, so source dependencies are
|
||||
reciprocal at composition time.
|
||||
2. Should `apps/fabro-web/app/routes/playground.tsx` remain assigned to
|
||||
`fabro-web-app` as the app-level integration adapter (the proposal here),
|
||||
or move into `fabro-workflow-playground`? Keeping the 44-file subtree as
|
||||
the playground boundary matches its own standalone/re-embedding contract.
|
||||
3. Which final Rust component ID owns
|
||||
`docs/public/api-reference/fabro-api.yaml` and the server endpoints:
|
||||
`fabro-api`, `fabro-server`, or a separately reconciled API-contract
|
||||
component? The JavaScript dependencies above should be renamed to that
|
||||
final ID.
|
||||
6
.gitignore
vendored
6
.gitignore
vendored
|
|
@ -11,9 +11,6 @@ evals/swe-bench/repos/
|
|||
evals/swe-bench/results/
|
||||
evals/swe-bench/dockerfiles/
|
||||
__pycache__
|
||||
.ai/plans
|
||||
.ai/comments
|
||||
.ai/tmp
|
||||
.worktrees/
|
||||
**/*.pending-snap
|
||||
.worktrees
|
||||
|
|
@ -21,3 +18,6 @@ __pycache__
|
|||
.mcp.json
|
||||
docs/internal/agent
|
||||
.amp/portals/*
|
||||
|
||||
# AI-generated artifacts stay local.
|
||||
/.ai/
|
||||
|
|
|
|||
|
|
@ -1,69 +0,0 @@
|
|||
---
|
||||
date: 2026-04-08
|
||||
topic: eliminate-scratch-artifact-cache
|
||||
---
|
||||
|
||||
# Eliminate Scratch Artifact Cache
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The artifact collection pipeline uses `scratch/cache/artifacts/files/` as a staging area for CLI uploads: files are downloaded from the sandbox to local disk, hashed, then uploaded to the server's `ArtifactStore`. Now that `ArtifactStore` (backed by object store) is the durable source of truth, this persistent local cache is unnecessary overhead. It adds disk usage and complicates the scratch directory contract. It also obscures a separate bug: server-managed runs currently start `ArtifactLifecycle` with no artifact sink configured, so collected artifacts are discarded. Eliminating the cache alone does not fix that bug; server-managed runs also need a direct `ArtifactStore` write path.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Pipeline: Replace persistent cache with transient local staging**
|
||||
|
||||
- R1. `collect_artifacts` must download each file from the sandbox into a transient per-attempt local directory tree that preserves each artifact's relative path, compute MD5/SHA256 from those transient local files, and keep that transient tree available until the configured artifact sink has finished consuming it, including upload retries. Delete the transient tree immediately after direct store writes or HTTP uploads finish. No persistent `cache/artifacts/` directory.
|
||||
- R2. `CapturedArtifactInfo` (path, mime, hashes, bytes) must still be produced for each collected file and emitted via `ArtifactCaptured` events.
|
||||
|
||||
**Store: Write artifacts directly to ArtifactStore**
|
||||
|
||||
- R3. When running server-side, `ArtifactLifecycle` writes collected artifacts directly to the server's `ArtifactStore`, fixing the current gap where server-managed runs configure no artifact sink and silently discard artifacts.
|
||||
- R4. When running via CLI, the existing HTTP upload path (`HttpArtifactUploader`) continues to work. Internal uploader abstractions may change as needed, but the CLI must continue uploading artifacts to the server rather than writing directly to `ArtifactStore`.
|
||||
- R5. `ArtifactLifecycle` must be configured with exactly one artifact sink for artifact-enabled runs: either a direct `ArtifactStore`-backed sink for server-managed runs or an HTTP uploader-backed sink for CLI runs. It must also hold a `RunId` for direct `ArtifactStore::put` calls. The internal representation of that sink (enum, unified trait, or refined existing trait) is deferred to planning.
|
||||
|
||||
**Scratch cleanup**
|
||||
|
||||
- R6. Remove `artifact_cache_dir()`, `artifact_files_dir()`, and `artifact_stage_dir()` from `RunScratch` in `fabro-config/src/storage.rs`.
|
||||
- R7. Remove the `create_dir_all(self.artifact_files_dir())` from `RunScratch::create()`.
|
||||
- R8. Update `docs/reference/run-directory.mdx` and `docs-internal/run-directory-keys.md` to remove all `cache/artifacts/` entries (including `cache/artifacts/files/`).
|
||||
- R10. Update integration tests in `fabro-workflow/tests/it/integration.rs` and `daytona_integration.rs` that assert on `artifact_stage_dir` paths to verify artifacts via `ArtifactStore` or uploader behavior instead of local filesystem paths.
|
||||
|
||||
**CLI output**
|
||||
|
||||
- R9. The post-run "=== Artifacts ===" output must stop printing local scratch paths. It should list durable artifact identifiers derived from stored metadata, at minimum `node_slug`, `retry`, and `relative_path`, and reference `fabro artifact cp` for retrieval.
|
||||
- R11. Removing `artifact_stage_dir()` must not change durable per-stage/per-attempt grouping. Artifacts must still be addressable by `StageId`, and CLI/server artifact surfaces must continue exposing `node_slug`, `retry`, and `relative_path` from store-backed metadata rather than reconstructing local scratch paths.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Server-managed workflow runs produce artifacts in `ArtifactStore` (previously they did not).
|
||||
- No `cache/artifacts/` directory is created or written to during any workflow run.
|
||||
- `fabro artifact list` and `fabro artifact cp` continue to work unchanged.
|
||||
- The post-run artifact summary prints logical artifact identifiers (`node_slug`, `retry`, `relative_path`) instead of local scratch paths.
|
||||
- `ArtifactCaptured` events still contain correct hashes and byte counts.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No changes to `fabro artifact list` or `fabro artifact cp` commands.
|
||||
- No changes to the `Sandbox` trait (no streaming download API).
|
||||
- No changes to the HTTP artifact upload protocol between CLI and server.
|
||||
- `runtime/blobs/` (context value materialization) is a separate concern, unchanged.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Transient local staging, not persistent scratch cache**: The `Sandbox` trait only has `download_file_to_local`. Rather than adding a streaming API to all sandbox impls, use transient local files outside `RunScratch`, but keep them alive until the configured sink has finished consuming them.
|
||||
- **Server writes to ArtifactStore directly**: The server already owns the `ArtifactStore` instance. Server-managed runs should use that directly instead of relying on an uploader being present.
|
||||
- **CLI keeps HTTP upload path**: The CLI continues uploading artifacts to the server over HTTP. The internal uploader interface may change, but the wire protocol stays the same. Smaller blast radius than giving the CLI its own local `ArtifactStore`.
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Deferred to Planning
|
||||
|
||||
- [Affects R5][Technical] What internal representation should `ArtifactLifecycle` use for the exactly-one artifact sink? Options: an enum with server/CLI variants, a new unified trait, or a refactor of the existing uploader trait.
|
||||
- [Affects R1][Technical] Should `collect_artifacts` return transient local handles/paths alongside `CapturedArtifactInfo`, or should store/upload happen inside the collection step while the transient files are definitely still present?
|
||||
- [Affects R1][Technical] Should transient staging use `tempfile::TempDir` (auto-cleanup on drop) or manual `std::fs::remove_dir_all`? The former is more robust against panics.
|
||||
- [Affects R9][Needs research] What does the current CLI output look like for artifacts, and what is the best replacement format? Check `lib/crates/fabro-cli/src/commands/run/output.rs`.
|
||||
|
||||
## Next Steps
|
||||
|
||||
-> `/ce:plan` for structured implementation planning
|
||||
|
|
@ -1,541 +0,0 @@
|
|||
---
|
||||
date: 2026-04-08
|
||||
topic: settings-toml-redesign
|
||||
---
|
||||
|
||||
# Settings TOML Redesign
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Fabro has three layered TOML config files:
|
||||
|
||||
- `~/.fabro/settings.toml` for machine defaults
|
||||
- `fabro.toml` for project defaults
|
||||
- `workflow.toml` for workflow-local defaults
|
||||
|
||||
All three layer into one unified settings object. In same-host setups, the CLI and server may both read `~/.fabro/settings.toml`. In split-host setups, the CLI host and server host each read their own local `settings.toml` and consume only the sections relevant to that process.
|
||||
|
||||
The current config shape grew organically. It now has naming drift, mixed ownership boundaries, uneven merge semantics, and several top-level sections that no longer reflect a clean mental model. Fabro is still greenfield with no deployed compatibility burden, so this is the right time to make a hard cut and establish a coherent, future-proof config language.
|
||||
|
||||
The new design must optimize for:
|
||||
|
||||
- a small, elegant top-level structure
|
||||
- coherent ownership boundaries between run, CLI, server, project, and workflow concerns
|
||||
- paste-anywhere ergonomics across the three config files
|
||||
- explicit and predictable layering semantics
|
||||
- future provider growth without provider-specific sprawl in the core model
|
||||
|
||||
## Requirements
|
||||
|
||||
**Config language and layering**
|
||||
|
||||
- R1. `settings.toml`, `fabro.toml`, and `workflow.toml` must share the same schema. Files differ by precedence only, not by allowed sections.
|
||||
- R2. Any config section may appear in any Fabro TOML file. Consumers must ignore sections they do not use.
|
||||
- R3. The top-level schema must be strictly namespaced. The only top-level config domains are `[project]`, `[workflow]`, `[run]`, `[cli]`, `[server]`, and `[features]`, plus reserved underscore-prefixed meta keys.
|
||||
- R4. The schema version key must be `_version`, not `version`.
|
||||
- R5. Underscore-prefixed keys are reserved only at the top level for config-language metadata. Nested underscore keys are not part of the language.
|
||||
- R6. The config language must not add a general unset mechanism in this pass.
|
||||
- R7. Unknown config keys against the full union schema must be hard errors. This is schema validation, not consumer-specific validation.
|
||||
- R8. Duplicate keys and duplicate hook `id` values within the same file must be hard errors.
|
||||
|
||||
**Object model and namespace boundaries**
|
||||
|
||||
- R9. `[workflow]` and `[run]` must be sibling top-level sections. Do not nest `[workflow.run]`.
|
||||
- R10. `[workflow]` is descriptive for now. It must support first-class fields such as `name`, `description`, optional `graph`, and `metadata`. Structured workflow inputs are deferred.
|
||||
- R11. `workflow.toml` remains the canonical workflow config filename. The default graph file remains `workflow.fabro`, with optional `[workflow].graph` override.
|
||||
- R12. `[project]` must be a first-class project object with fields such as `name`, `description`, `directory`, and `metadata`.
|
||||
- R13. `project.directory` replaces the old Fabro project root concept and means the Fabro-managed project directory inside the repo, defaulting to `fabro/`.
|
||||
- R14. Workflow discovery remains conventional: `<project.directory>/workflows/<name>/workflow.toml`. Do not add a separate configurable workflows directory.
|
||||
- R15. `[run]` is the shared execution domain. It may appear in all three files and layer normally.
|
||||
- R16. `[cli]` and `[server]` are owner-first process domains. Settings belong to the process that reads them, not to whether the host is “local” or “remote.” For trust-boundary reasons, CLI and server processes consume their owner-specific sections only from the local `~/.fabro/settings.toml` plus explicit process-local overrides. Same-shaped `cli.*` and `server.*` stanzas in `fabro.toml` and `workflow.toml` remain schema-valid but inert for those processes.
|
||||
- R17. `[features]` is a reserved cross-cutting namespace for Fabro capability flags only. It must have a high admission bar and must not become a junk drawer.
|
||||
- R18. Logging is process-owned. Use `[cli.logging]` and `[server.logging]`; do not keep a shared logging section.
|
||||
|
||||
**Run model**
|
||||
|
||||
- R19. `[run]` must keep a small direct manifest surface for cross-cutting run fields such as `goal` and `working_dir`.
|
||||
- R20. `working_dir` replaces `work_dir`.
|
||||
- R21. `metadata` replaces Fabro-owned `labels` and exists on `project`, `workflow`, and `run` as flat string-to-string maps.
|
||||
- R22. `run.inputs` replaces `vars`. `run.inputs` must accept TOML scalar values. `metadata` remains string-to-string. `run.inputs` intentionally replaces the full inherited map rather than merging by key.
|
||||
- R23. `[run.model]` is the default model selection surface for LLM-backed workflow stages. `[run.agent]` is only for agent-specific settings.
|
||||
- R24. `[run.agent]` owns agent-only knobs such as `fabro_tools` and `mcps`. `[run.sandbox]` owns the sandbox selection and execution-environment surface, including `provider`, shared sandbox knobs, `env`, and provider-specific nested tables.
|
||||
- R25. Workspace tool permissions belong to `[cli.exec.agent]`.
|
||||
- R26. `[run.git]` and `[run.scm]` must remain separate concepts. `git` is local Git behavior such as commit author; `scm` is remote host/provider behavior.
|
||||
- R27. `[run.pull_request]` remains the provider-neutral run surface for PR behavior.
|
||||
- R28. `[run.prepare]` is the run preparation surface and replaces the old `setup` naming.
|
||||
- R29. `run.prepare` must be an ordered list of steps at `[[run.prepare.steps]]`.
|
||||
- R30. `run.prepare.steps` replaces as a whole ordered list across layers.
|
||||
- R31. `[run.execution]` groups run-conduct knobs such as `mode`, `approval`, and `retros`. In the first pass, `mode` is `normal | dry_run`, `approval` is `prompt | auto`, and `retros` is a positive-form boolean. Do not keep negated or ambiguous booleans like `no_retro`.
|
||||
- R32. `[run.checkpoint]` remains its own run domain. `[[run.hooks]]` is the ordered run-hook surface for run lifecycle automation.
|
||||
- R33. `[run.artifacts]` defines what run artifacts are collected. Server-side artifact storage is separate.
|
||||
- R34. `[run.notifications.<name>]` is a keyed set of named notification routes. Notification routes merge by field across layers and support `enabled = false`.
|
||||
- R35. `[run.interviews]` is a single optional external/default interview delivery surface. HTTP/API answering is always available and is not modeled as an interview provider.
|
||||
- R36. Notification and interview event selection must use raw Fabro event names, not a second notification-specific vocabulary.
|
||||
|
||||
**CLI model**
|
||||
|
||||
- R37. CLI target resolution lives under `[cli.target]`, not `[server]` or `[cli.remote]`.
|
||||
- R38. CLI target transport must be explicit with `type = "http" | "unix"` and transport-specific fields, not overloaded scheme strings.
|
||||
- R39. CLI transport TLS lives under `[cli.target.tls]`.
|
||||
- R40. CLI auth is a separate domain at `[cli.auth]`, with explicit `strategy` selection. `strategy = "none"` explicitly disables inherited auth.
|
||||
- R41. `fabro exec` defaults live under `[cli.exec]`, with `[cli.exec.model]` and `[cli.exec.agent]` split cleanly.
|
||||
- R42. Generic CLI output defaults live under `[cli.output]`, not under `exec`.
|
||||
- R43. Upgrade checks live under `[cli.updates]`.
|
||||
- R44. Idle sleep prevention lives under `[cli.exec]`.
|
||||
|
||||
**Server model**
|
||||
|
||||
- R45. `[server]` is a namespace container. Actual settings live in named subdomains.
|
||||
- R46. The server binds the API and web surfaces on one shared listener. Bind transport must live under `[server.listen]`, not separately under `[server.api]` and `[server.web]`.
|
||||
- R47. `[server.listen]` must use explicit transport types such as `tcp` and `unix`.
|
||||
- R48. Shared listener TLS must live under `[server.listen.tls]`.
|
||||
- R49. `[server.api]` holds only API-surface settings such as public URL, not bind/auth/TLS settings.
|
||||
- R50. `[server.web]` holds only web-surface settings such as `enabled` and public URL, not auth settings.
|
||||
- R51. Server auth is a cohesive domain at `[server.auth]`.
|
||||
- R52. `[server.auth.api]` must support multiple strategies concurrently.
|
||||
- R53. `[server.auth.web]` must support multiple providers concurrently via `[server.auth.web.providers.<provider>]`.
|
||||
- R54. Web-auth access rules remain provider-neutral on `[server.auth.web]`; provider-specific config lives under each provider subtable.
|
||||
- R55. Web-auth providers must support `enabled = true|false` to disable inherited provider config cleanly.
|
||||
- R56. Inbound provider webhooks belong under provider integrations such as `[server.integrations.github.webhooks]`, not under generic server auth or web sections.
|
||||
- R57. `[server.storage]` refers only to a managed local disk root on the host. It must expose a single managed `root`.
|
||||
- R58. `[server.artifacts]` is separate from `[server.storage]` and is backed by an object store provider.
|
||||
- R59. `[server.slatedb]` is separate from both `[server.storage]` and `[server.artifacts]`. It is backed by its own object store provider and may include database-specific tunables such as `flush_interval`.
|
||||
- R60. `[server.scheduler]` owns server-managed execution policy such as concurrency limits. It must not compete with `[run]`.
|
||||
|
||||
**Provider and future-proofing rules**
|
||||
|
||||
- R61. Core Fabro concepts should be provider-neutral. Provider-specific details should live in provider-specific nested tables where the domain genuinely requires them.
|
||||
- R62. Sandbox config must remain provider-specific because provider differences are too large to hide behind one flat abstraction.
|
||||
- R63. Model config must remain intentionally provider-neutral. It should not grow provider-specific subtables. `run.model.fallbacks` is a single ordered array of model references. Each entry may be a bare provider token such as `openai`, a bare model alias or model id such as `gpt-5.4`, or a qualified reference such as `gemini/gemini-flash`. Bare references are allowed only when unambiguous. Ambiguous bare references must hard-error and require qualification. A bare provider token means “choose the best matching model from that provider.”
|
||||
- R64. SCM config must be provider-neutral at the core (`[run.scm]`) with room for provider-specific nested tables such as `[run.scm.github]` only where necessary.
|
||||
- R65. Slack is the chat integration. Its server-owned setup lives under `[server.integrations.slack]`; run behavior lives under `[run.notifications.*]` and `[run.interviews]`.
|
||||
- R66. Object-store-backed domains must use a shared pattern: a small provider-neutral envelope plus provider-specific nested tables.
|
||||
- R67. For local object-store providers, default to `server.storage.root`, but allow explicit local override roots when needed.
|
||||
|
||||
**Merge, validation, and runtime semantics**
|
||||
|
||||
- R68. Scalars replace.
|
||||
- R69. Structured tables merge by field.
|
||||
- R70. Freeform maps replace by default.
|
||||
- R71. A small, explicit set of maps may merge by key where additive inheritance is the least surprising behavior, including `run.sandbox.env` and provider-native maps such as `run.sandbox.daytona.labels`. These maps are intentionally sticky in v1: higher-precedence layers may overwrite keys but cannot remove inherited keys.
|
||||
- R72. Arrays replace by default.
|
||||
- R73. Arrays must support splice semantics via `...` in declared splice-capable string arrays, for example `["...", "c"]` for append and `["a", "..."]` for prepend. At most one exact `"..."` marker may appear per array. In the base layer with no inherited parent, the splice marker resolves to an empty inherited segment. In splice-capable arrays, the literal string value `"..."` is reserved and may not be used as data.
|
||||
- R74. Security and policy lists must replace by default and only inherit via explicit `...`.
|
||||
- R75. Keyed named objects such as notifications, MCPs, and web-auth providers must merge by field across layers. User-defined keyed object names in namespaces that also host provider-specific subtables must not equal built-in provider identifiers, to avoid ambiguous shapes such as `[run.notifications.slack.slack]`.
|
||||
- R76. Named keyed objects that may need to be disabled must support `enabled = false`.
|
||||
- R77. `[[run.hooks]]` remains an ordered list. Hooks may define an optional `id`; `name` remains human-facing only. Hooks without `id` append. Hooks with the same `id` replace whole entries in place. Hooks without `id` from a higher-precedence layer append after the fully merged inherited hook list, preserving per-file declaration order. Hook ordering remains significant.
|
||||
- R78. Provider-specific required fields should only be validated when that provider/section is actually consumed.
|
||||
- R79. Unresolved `${env.NAME}` references should only error when the field is actually consumed.
|
||||
- R80. The config language must not require separate validation modes for CLI, server, and run config in this pass. Runtime consumption drives context-specific validation.
|
||||
|
||||
**String interpolation and value formats**
|
||||
|
||||
- R81. Any string field may use `${env.NAME}` interpolation, either as the whole value or as a substring inside a larger string. Multiple `${env.NAME}` tokens may appear in the same string.
|
||||
- R82. Do not support config-to-config references such as `${run.inputs.foo}` in this pass.
|
||||
- R83. All time-like values should use human-readable durations such as `"30s"`, `"1m"`, or `"1h"`, not `_ms` or `_secs` fields.
|
||||
- R84. Memory and disk settings should accept generous human-readable size syntax. Bare values such as `8`, plus `8G`, `8GB`, and `8GiB`, should all parse successfully.
|
||||
- R85. Docs and examples should use `GB` as the canonical style. Parsing should remain generous.
|
||||
- R86. CPU remains an integer core count.
|
||||
|
||||
**Command execution shape**
|
||||
|
||||
- R87. Shell-evaluated actions use `script = "..."`.
|
||||
- R88. Direct process launches use `command = ["..."]`.
|
||||
- R89. `script` and `command` are mutually exclusive.
|
||||
- R90. The `script` xor `command` rule must apply consistently across prepare steps, hooks, and MCP transports that launch a local process. Non-launching MCP transports such as plain HTTP do not use either field.
|
||||
|
||||
## Precedence and Override Order
|
||||
|
||||
The config language has one schema but two consumption models.
|
||||
|
||||
Shared layered domains such as `[project]`, `[workflow]`, `[run]`, and `[features]` use this override order:
|
||||
|
||||
1. Explicit process-local command args or flags
|
||||
2. Explicit process-local environment override channels, where Fabro defines them
|
||||
3. `workflow.toml`
|
||||
4. `fabro.toml`
|
||||
5. `~/.fabro/settings.toml`
|
||||
6. Built-in defaults
|
||||
|
||||
Owner-specific process domains use a narrower trust boundary:
|
||||
|
||||
1. Explicit process-local command args or flags
|
||||
2. Explicit process-local environment override channels, where Fabro defines them
|
||||
3. `~/.fabro/settings.toml`
|
||||
4. Built-in defaults
|
||||
|
||||
Additional rules:
|
||||
|
||||
- String interpolation via `${env.NAME}` is not a separate precedence layer. It is value resolution inside the winning layered config value.
|
||||
- Server start flags override only the server-consumed settings for that process invocation. They do not change persisted TOML values.
|
||||
- CLI flags override only the CLI-consumed settings for that process invocation.
|
||||
- `cli.*` and `server.*` stanzas in `fabro.toml` and `workflow.toml` remain parseable but are not part of runtime precedence for those processes.
|
||||
- If a future env override channel exists for a setting, it must sit between explicit args/flags and layered TOML.
|
||||
|
||||
## Validation Boundary
|
||||
|
||||
Schema validation and runtime validation are separate concerns:
|
||||
|
||||
- All config files validate against the full union schema before consumer-specific filtering.
|
||||
- Unknown-key validation and duplicate-key validation run at schema-validation time, not at consumer-specific runtime.
|
||||
- Lazy validation applies only to provider-specific required fields, selected strategies/providers, and `${env.NAME}` resolution for fields that a consumer actually uses.
|
||||
- Unused but schema-valid `cli.*` and `server.*` stanzas in lower-trust files remain inert rather than invalid.
|
||||
|
||||
## Disable Semantics
|
||||
|
||||
The config language must use one explicit rule for inherited config suppression:
|
||||
|
||||
- Absence means inherit or express no opinion.
|
||||
- `enabled = false` disables inherited keyed named objects such as notification routes, MCP entries, and web-auth providers.
|
||||
- `provider = "none"` or `strategy = "none"` disables inherited singleton selectable sections such as interviews or auth.
|
||||
- Disabled sections suppress provider-specific required-field validation for their disabled subtree.
|
||||
|
||||
## Public URL Semantics
|
||||
|
||||
`server.listen` is only the bind transport. It must not be treated as a public URL source.
|
||||
|
||||
- `server.api.url` and `server.web.url` are optional public URLs.
|
||||
- They are not derived from `server.listen`.
|
||||
- They are not derived from each other.
|
||||
- If omitted, Fabro must treat the corresponding public URL as unspecified rather than synthesizing one implicitly.
|
||||
|
||||
## Normative Merge Matrix
|
||||
|
||||
This redesign should specify exact merge behavior for the first-pass config surface rather than relying only on structural categories.
|
||||
|
||||
| Path | Merge behavior |
|
||||
|---|---|
|
||||
| `project` direct scalar fields such as `name`, `description`, and `directory` | replace by field |
|
||||
| `project.metadata` | replace |
|
||||
| `workflow` direct scalar fields such as `name`, `description`, and `graph` | replace by field |
|
||||
| `workflow.metadata` | replace |
|
||||
| `run` direct scalar fields such as `goal` and `working_dir` | replace by field |
|
||||
| `run.metadata` | replace |
|
||||
| `run.inputs` | replace |
|
||||
| `run.model` direct scalar fields such as `provider` and `name` | replace by field |
|
||||
| `run.model.fallbacks` | replace, with `...` splice support |
|
||||
| `run.git.author` | merge by field |
|
||||
| `run.execution` | merge by field |
|
||||
| `run.checkpoint` | merge by field |
|
||||
| `run.sandbox` direct scalar fields such as `provider` and `preserve` | merge by field |
|
||||
| `run.sandbox.<provider>` | merge by field |
|
||||
| `run.sandbox.env` | merge by key |
|
||||
| provider-native maps such as `run.sandbox.daytona.labels` | merge by key |
|
||||
| notification route `events` arrays | replace, with `...` splice support |
|
||||
| `run.pull_request` | merge by field |
|
||||
| `run.interviews` | merge by field |
|
||||
| `run.interviews.<provider>` | merge by field |
|
||||
| `run.prepare.steps` | replace whole ordered list |
|
||||
| `run.notifications.<name>` | merge by field |
|
||||
| `run.notifications.<name>.<provider>` | merge by field |
|
||||
| `run.agent.mcps.<name>` | merge by field |
|
||||
| `cli.target` | merge by field |
|
||||
| `cli.auth` | merge by field |
|
||||
| `cli.exec` | merge by field |
|
||||
| `cli.exec.model` | merge by field |
|
||||
| `cli.exec.agent` | merge by field |
|
||||
| `cli.output` | merge by field |
|
||||
| `cli.updates` | merge by field |
|
||||
| `server.listen` | merge by field |
|
||||
| `server.api` | merge by field |
|
||||
| `server.web` | merge by field |
|
||||
| `server.auth.api` | merge by field |
|
||||
| `server.auth.api.<strategy>` | merge by field |
|
||||
| `server.auth.web.providers.<name>` | merge by field |
|
||||
| `server.storage` | merge by field |
|
||||
| `server.artifacts` | merge by field |
|
||||
| `server.artifacts.<provider>` | merge by field |
|
||||
| `server.slatedb` | merge by field |
|
||||
| `server.slatedb.<provider>` | merge by field |
|
||||
| `server.scheduler` | merge by field |
|
||||
| `[[run.hooks]]` | ordered list with special optional-`id` replacement rule |
|
||||
|
||||
New config paths added later should declare one of these behaviors explicitly in docs and implementation. Do not let merge behavior be accidental from Rust type shape alone.
|
||||
|
||||
## Canonical Rendering
|
||||
|
||||
Fabro should parse generously but render consistently in docs and config-inspection output.
|
||||
|
||||
- Durations should render in human-readable form such as `30s`, `1m`, or `1h`.
|
||||
- Memory and disk should render using `GB` in user-facing examples and normalized output.
|
||||
- `fabro settings` or equivalent config-inspection output should emit canonicalized values rather than the user's original alternate spelling when values have been normalized internally.
|
||||
- `fabro settings` or equivalent config-inspection output must redact values that were sourced from `${env.NAME}` by default, rather than printing the resolved secret-bearing value verbatim.
|
||||
|
||||
## Object Store Credential Semantics
|
||||
|
||||
First-pass object store configuration must work without a Fabro-specific secret reference language.
|
||||
|
||||
- Object store providers may rely on provider-native ambient auth such as IAM roles, workload identity, local credential files, or equivalent external mechanisms.
|
||||
- Provider-specific object-store config fields may also take ordinary string values populated via `${env.NAME}`.
|
||||
- This redesign does not add `${secret.NAME}` or a separate secret-backend reference syntax.
|
||||
|
||||
## Executable Config Trust Boundary
|
||||
|
||||
Config-executed actions are part of Fabro's trusted configuration model, not the agent permission model.
|
||||
|
||||
- `script` and `command` in prepare steps, hooks, and launching MCP transports are executable configuration, not passive metadata.
|
||||
- These actions execute under the trust boundary of the consuming process.
|
||||
- They are not mediated by `cli.exec.agent.permissions`.
|
||||
- Users should treat `fabro.toml` and `workflow.toml` as executable project configuration, not as untrusted data blobs.
|
||||
|
||||
## Migration and Failure Behavior
|
||||
|
||||
This is a hard-cut redesign, but migration still needs explicit failure semantics.
|
||||
|
||||
- Missing `_version` defaults to `1` in the first pass.
|
||||
- `_version` values higher than the parser supports must hard-fail with an upgrade hint before deeper validation continues.
|
||||
- The legacy top-level `version` key must hard-fail with a targeted rename hint to `_version`.
|
||||
- Historical keys and obsolete top-level shapes should hard-fail rather than silently aliasing forward.
|
||||
- Error messages should point to the new replacement path whenever the replacement is known.
|
||||
- Historical file names that are no longer read should fail or warn deterministically with a rename hint.
|
||||
- There should be no silent compatibility layer that keeps old and new shapes both alive indefinitely.
|
||||
- Migration guidance must explicitly call out that the new default `project.directory = "fabro/"` changes workflow discovery relative to the old implicit project-root behavior.
|
||||
- Historical string command forms such as `command = "cargo fmt"` must migrate to either `script = "cargo fmt"` or `command = ["cargo", "fmt"]`.
|
||||
- Historical hook `name` remains display-only in the new language. Cross-layer hook replacement uses the optional `id` field, so users must add `id` explicitly where merge identity is intended.
|
||||
|
||||
Known first-pass migration mappings:
|
||||
|
||||
| Old shape | New shape |
|
||||
|---|---|
|
||||
| `version = 1` | `_version = 1` |
|
||||
| top-level `goal` | `[run].goal` |
|
||||
| top-level `work_dir` or `directory` | `[run].working_dir` |
|
||||
| top-level `labels` | `[run.metadata]` |
|
||||
| `[vars]` | `[run.inputs]` |
|
||||
| `[llm]` | `[run.model]` |
|
||||
| `[setup]` | `[run.prepare]` |
|
||||
| `[sandbox]` | `[run.sandbox]` |
|
||||
| `[checkpoint]` | `[run.checkpoint]` |
|
||||
| `[pull_request]` | `[run.pull_request]` |
|
||||
| `[artifacts]` | `[run.artifacts]` |
|
||||
| `[exec]` | `[cli.exec]` |
|
||||
| `[mcp_servers]` | `[run.agent.mcps]` or `[cli.exec.agent.mcps]`, depending on the consumer |
|
||||
| `[api]` | `[server.api]` |
|
||||
| `[web]` | `[server.web]` |
|
||||
| `[artifact_storage]` | `[server.artifacts]` |
|
||||
| Git commit author settings | `[run.git.author]` |
|
||||
| GitHub App and webhook settings | `[server.integrations.github]` |
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- The new config language has a small, defensible top-level schema with clear object ownership boundaries.
|
||||
- Users can paste a stanza between `settings.toml`, `fabro.toml`, and `workflow.toml` and still parse successfully.
|
||||
- Same-host and split-host deployments both fit the model without separate schema branches.
|
||||
- Merge behavior is predictable enough that users can explain it from the docs without reading implementation code.
|
||||
- Provider growth in SCM, chat integrations, and object stores does not force repeated top-level redesigns.
|
||||
- Users can disable inherited singleton and keyed-object behavior without a general unset language.
|
||||
- Users can predict flag/env/TOML precedence without reading implementation code.
|
||||
- When users supply old config keys, Fabro fails with targeted upgrade guidance rather than silently ignoring or partially accepting them.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No backwards-compatibility requirements. This is a hard-cut redesign.
|
||||
- No secret-reference syntax such as `${secret.NAME}` in this pass.
|
||||
- No secret backend configuration in this pass.
|
||||
- No structured workflow input schema in this pass.
|
||||
- No prompt-specific run config section in this pass.
|
||||
- No separate validation modes such as “validate as server config” in this pass.
|
||||
- No automatic migration tool in this pass.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Strict top-level namespaces**: Keep the root schema extremely small and reserve underscore-prefixed top-level keys for config-language metadata.
|
||||
- **Same schema everywhere**: File type controls precedence, not which sections are legal.
|
||||
- **Owner-first process config**: CLI and server settings belong to the process that reads them, even in same-host setups.
|
||||
- **Provider-neutral core with provider-specific leaves**: Use this for SCM, notifications, interviews, sandboxes, and object stores where it improves long-term coherence.
|
||||
- **No general unset**: Prefer explicit disable mechanisms such as `enabled = false` and `"none"` selectors.
|
||||
- **Lazy validation for unused stanzas**: This preserves the “paste any stanza anywhere” rule without weakening strict unknown-key validation.
|
||||
- **Shared server listener**: Bind transport and transport TLS are shared at `[server.listen]`; API and web remain separate surfaces above that.
|
||||
- **Separate storage, artifacts, and SlateDB**: These are materially different server concerns and should not be collapsed into one storage section.
|
||||
- **Ordered lists are rare**: Keep them where order is semantically important, especially hooks and prepare steps. Prefer keyed named objects elsewhere.
|
||||
- **Hard-fail migration**: The system should aggressively reject obsolete keys and point users at replacements instead of carrying a compatibility burden into the new language.
|
||||
|
||||
## Canonical Shape
|
||||
|
||||
```toml
|
||||
_version = 1
|
||||
|
||||
[project]
|
||||
[workflow]
|
||||
[run]
|
||||
[cli]
|
||||
[server]
|
||||
[features]
|
||||
```
|
||||
|
||||
Representative subtree:
|
||||
|
||||
```toml
|
||||
_version = 1
|
||||
|
||||
[project]
|
||||
name = "Fabro"
|
||||
description = "AI workflow orchestration"
|
||||
directory = "fabro/"
|
||||
|
||||
[workflow]
|
||||
name = "Implement Feature"
|
||||
description = "Turns a request into a code change"
|
||||
|
||||
[run]
|
||||
goal = "Implement OAuth refresh tokens"
|
||||
working_dir = "/workspace"
|
||||
|
||||
[run.model]
|
||||
provider = "anthropic"
|
||||
name = "sonnet"
|
||||
fallbacks = ["openai", "gpt-5.4", "gemini/gemini-flash"]
|
||||
|
||||
[run.notifications.ops]
|
||||
enabled = true
|
||||
provider = "slack"
|
||||
events = ["run.failed"]
|
||||
|
||||
[run.notifications.ops.slack]
|
||||
channel = "#ops"
|
||||
|
||||
[run.interviews]
|
||||
provider = "slack"
|
||||
|
||||
[run.interviews.slack]
|
||||
channel = "#approvals"
|
||||
|
||||
[cli.target]
|
||||
type = "http"
|
||||
url = "https://fabro.example.com/api/v1"
|
||||
|
||||
[cli.auth]
|
||||
strategy = "mtls"
|
||||
|
||||
[cli.exec.model]
|
||||
provider = "anthropic"
|
||||
name = "claude-opus"
|
||||
|
||||
[cli.exec.agent]
|
||||
permissions = "read-write"
|
||||
|
||||
[server.listen]
|
||||
type = "tcp"
|
||||
address = "127.0.0.1:32276"
|
||||
|
||||
[server.api]
|
||||
url = "https://fabro.example.com/api/v1"
|
||||
|
||||
[server.web]
|
||||
enabled = true
|
||||
url = "https://fabro.example.com"
|
||||
|
||||
[server.storage]
|
||||
root = "/var/lib/fabro"
|
||||
|
||||
[server.artifacts]
|
||||
provider = "s3"
|
||||
prefix = "artifacts"
|
||||
|
||||
[server.slatedb]
|
||||
provider = "s3"
|
||||
prefix = "runs"
|
||||
flush_interval = "1s"
|
||||
```
|
||||
|
||||
## Canonical File Examples
|
||||
|
||||
Minimal `~/.fabro/settings.toml`:
|
||||
|
||||
```toml
|
||||
_version = 1
|
||||
|
||||
[cli.target]
|
||||
type = "unix"
|
||||
path = "~/.fabro/fabro.sock"
|
||||
|
||||
[cli.exec]
|
||||
prevent_idle_sleep = true
|
||||
|
||||
[cli.exec.model]
|
||||
provider = "anthropic"
|
||||
name = "claude-opus"
|
||||
|
||||
[cli.exec.agent]
|
||||
permissions = "read-write"
|
||||
|
||||
[cli.output]
|
||||
format = "text"
|
||||
verbosity = "normal"
|
||||
|
||||
[cli.updates]
|
||||
check = true
|
||||
|
||||
[server.listen]
|
||||
type = "unix"
|
||||
path = "~/.fabro/fabro.sock"
|
||||
|
||||
[server.storage]
|
||||
root = "~/.fabro/storage"
|
||||
|
||||
[run.interviews]
|
||||
provider = "slack"
|
||||
|
||||
[run.interviews.slack]
|
||||
channel = "#approvals"
|
||||
```
|
||||
|
||||
Minimal `fabro.toml`:
|
||||
|
||||
```toml
|
||||
_version = 1
|
||||
|
||||
[project]
|
||||
name = "Fabro"
|
||||
description = "AI workflow orchestration"
|
||||
directory = "fabro/"
|
||||
|
||||
[run.model]
|
||||
provider = "anthropic"
|
||||
name = "sonnet"
|
||||
|
||||
[run.sandbox]
|
||||
provider = "daytona"
|
||||
|
||||
[[run.prepare.steps]]
|
||||
script = "bun install"
|
||||
```
|
||||
|
||||
Minimal `workflow.toml`:
|
||||
|
||||
```toml
|
||||
_version = 1
|
||||
|
||||
[workflow]
|
||||
name = "Implement Feature"
|
||||
description = "Turns a request into a code change"
|
||||
|
||||
[run]
|
||||
goal = "Implement OAuth refresh tokens"
|
||||
|
||||
[run.inputs]
|
||||
repo = "fabro"
|
||||
|
||||
[run.notifications.ops]
|
||||
enabled = true
|
||||
provider = "slack"
|
||||
events = ["run.failed", "run.completed"]
|
||||
|
||||
[run.notifications.ops.slack]
|
||||
channel = "#ops"
|
||||
```
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Deferred to Planning
|
||||
|
||||
- [Affects R64][Technical] What exact run-side SCM targeting fields should live under `[run.scm]` in the first pass: repo slug, owner/repo split, base branch defaults, or additional checkout/ref context?
|
||||
- [Affects R66][Technical] What exact shared field set should the object-store envelope expose before provider-specific subtables begin?
|
||||
- [Affects R90][Technical] What exact field set should the MCP launcher schema expose in addition to `script` xor `command`, `type`, and timeouts?
|
||||
- [Affects R34][Technical] What minimal first-pass notification route surface is required beyond `enabled`, `provider`, and `events`?
|
||||
- [Affects R83][Technical] What duration parser will Fabro standardize on, and what canonical normalization should be shown in error messages and generated examples?
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Update the user-facing config docs to match this new object model.
|
||||
- `/ce:plan` for a migration and implementation plan covering parser changes, merge semantics, docs, and test updates.
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
---
|
||||
date: 2026-04-15
|
||||
topic: ip-whitelist
|
||||
---
|
||||
|
||||
# IP Address Whitelisting
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Some fabro users deploy without network-level controls (VPN, firewall). These users need fabro itself to restrict access by client IP address so that only trusted networks can reach the web UI and API.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Access Control**
|
||||
- R1. When an IP whitelist is configured, requests from non-whitelisted IPs receive 403 Forbidden before authentication is evaluated. This applies to all requests: API, web UI, and static assets
|
||||
- R2. When no IP whitelist is configured, all IPs are allowed (current behavior, no breaking change)
|
||||
- R3. Health check endpoints (e.g., `/health`) are exempt from IP filtering so load balancers and monitoring continue to work
|
||||
- R10. Log rejected requests (client IP, request path, timestamp) at warn level for security auditing and debugging
|
||||
|
||||
**IP Matching**
|
||||
- R4. Support individual IPv4 and IPv6 addresses (e.g., `1.2.3.4`, `::1`)
|
||||
- R5. Support CIDR notation for ranges (e.g., `10.0.0.0/8`, `fd00::/8`)
|
||||
|
||||
**Reverse Proxy Support**
|
||||
- R6. When deployed behind a reverse proxy, detect client IP from `X-Forwarded-For` or `X-Real-IP` headers
|
||||
- R7. Proxy header trust must be explicitly configured (trusted proxy count or trusted proxy list) to prevent spoofing; without configuration, use the TCP remote address
|
||||
- R11. When the server listens on a Unix socket and an IP whitelist is configured, proxy header trust must also be configured or the server refuses to start
|
||||
|
||||
**Configuration**
|
||||
- R8. IP whitelist is configured via server settings (settings.toml / environment variables), not via the web UI
|
||||
- R9. Changes require a server restart (IP whitelist does not participate in the existing settings hot-reload cycle)
|
||||
- R12. Server must refuse to start if the IP whitelist contains invalid entries (malformed CIDR, unparseable addresses). Fail-closed prevents a false sense of security
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A fabro instance with an IP whitelist configured rejects requests from non-whitelisted IPs with 403
|
||||
- Health checks remain accessible from any IP
|
||||
- The feature has zero impact when unconfigured (default: allow all)
|
||||
- IP detection works correctly behind common reverse proxies (nginx, AWS ALB) when trust is configured
|
||||
- Invalid whitelist configuration prevents server startup with a clear error message
|
||||
- Rejected requests appear in server logs with enough detail to diagnose misconfiguration
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No web UI for managing the whitelist
|
||||
- No per-user or per-role IP rules
|
||||
- No rate limiting (separate concern)
|
||||
- No IP blocklist (deny-list) -- only allowlist
|
||||
- No hot-reload of IP rules without restart
|
||||
- No geo-IP or DNS-based filtering
|
||||
- No implicit localhost/loopback exemption -- admins must explicitly whitelist 127.0.0.1/::1 if needed
|
||||
- GitHub webhook listener (separate TcpListener) is out of scope -- it uses HMAC signature verification for its own access control
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Config-only, no UI management**: Keeps the attack surface small -- an attacker who bypasses IP filtering can't weaken it through the UI
|
||||
- **Block before auth**: Reduces exposure -- non-whitelisted IPs can't even probe auth endpoints
|
||||
- **Health check exemption**: Practical necessity for load-balanced deployments
|
||||
- **Explicit proxy trust**: Prevents IP spoofing via forged headers in direct-connection deployments
|
||||
- **Fail-closed on invalid config**: Server refuses to start rather than silently degrading to allow-all
|
||||
- **No implicit loopback exemption**: Keeps behavior strict and predictable; admin error is recoverable via config file edit
|
||||
- **Unix socket requires proxy trust**: Since Unix sockets have no TCP remote address, proxy headers are the only way to determine client IP
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Deferred to Planning
|
||||
- [Affects R6, R7][Needs research] What reverse proxy IP detection does Axum's ecosystem already provide (e.g., `axum-client-ip`, `ConnectInfo`) and what needs custom implementation? Note: the server currently does not use `into_make_service_with_connect_info`, and the TLS path does not propagate `remote_addr`
|
||||
- [Affects R8][Technical] What is the best configuration shape in settings.toml? Note: `ServerLayer` uses `#[serde(deny_unknown_fields)]`, which constrains field additions
|
||||
- [Affects R3][Technical] Which health check endpoints should be exempted? Currently `/health` and `/health/diagnostics` exist; the latter probes server internals and may not be safe to exempt
|
||||
- [Affects R4, R5][Technical] How should IPv4-mapped IPv6 addresses (e.g., `::ffff:10.0.0.1`) be handled -- should they match plain IPv4 whitelist entries?
|
||||
- [Affects R6][Technical] For X-Forwarded-For with multiple IPs, which position in the chain should be treated as the client IP? (rightmost-minus-N is the secure approach)
|
||||
|
||||
## Next Steps
|
||||
|
||||
-> `/ce:plan` for structured implementation planning
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# `fabro upgrade --prerelease` — requirements
|
||||
|
||||
## Problem
|
||||
|
||||
`fabro upgrade` hits GitHub's `/releases/latest`, which excludes prereleases. Users on a prerelease (e.g. `0.204.0-beta.0`) or wanting to opt into betas must supply an exact `--version v0.X.Y-alpha.N`. There is no channel opt-in.
|
||||
|
||||
## Goal
|
||||
|
||||
Add `--prerelease` to `fabro upgrade` so a single invocation picks the highest semver across stable **and** prereleases.
|
||||
|
||||
## Behavior
|
||||
|
||||
- New bool flag `--prerelease` on `fabro upgrade`. Conflicts with `--version` (explicit version already selects any tag).
|
||||
- Scope: only the explicit `fabro upgrade` command. Background auto-check (`spawn_upgrade_check` / `check_and_print_notice`) stays stable-only.
|
||||
- Selection when `--prerelease` is set:
|
||||
1. Fetch `GET /repos/fabro-sh/fabro/releases` (first page, 30 items — `gh` and HTTP backends).
|
||||
2. Drop entries with `draft: true` or an unparseable `tag_name`.
|
||||
3. Pick the max by semver over the remaining set (stable + prereleases together). This means a newer stable beats an older beta; `--prerelease` *widens* the candidate set, it does not prefer prereleases.
|
||||
4. If the filtered set is empty, fall back to the existing stable-latest path (`/releases/latest`).
|
||||
- Downgrade protection unchanged:
|
||||
- Target < current, no explicit version → bail ("latest release … is older than installed version …, skipping").
|
||||
- Target == current, no `--force` → "Already on version …".
|
||||
- `--dry-run`, `--force`, JSON output, SHA256 verify, atomic swap — all unchanged.
|
||||
|
||||
## Code touchpoints
|
||||
|
||||
- `lib/crates/fabro-cli/src/args.rs` — add `prerelease: bool` with `#[arg(long, conflicts_with = "version")]`.
|
||||
- `lib/crates/fabro-cli/src/commands/upgrade.rs`:
|
||||
- New local `ReleaseSummary { tag_name: String, draft: bool, prerelease: bool }` (serde).
|
||||
- New `Backend::fetch_releases(&self) -> Result<Vec<ReleaseSummary>>` that hits `/releases` via HTTP or `gh api repos/{repo}/releases`.
|
||||
- New pure `fn pick_latest_tag(releases: &[ReleaseSummary]) -> Option<String>` — filters drafts + unparseable tags, returns max-semver `tag_name`.
|
||||
- `run_upgrade`: when `args.prerelease`, call `fetch_releases` → `pick_latest_tag`; on `None`, fall back to `fetch_latest_release_tag`.
|
||||
- `spawn_upgrade_check` / `check_and_print_notice` untouched.
|
||||
|
||||
## Tests (unit, no network)
|
||||
|
||||
- `pick_latest_tag`:
|
||||
- mixed stable + prerelease, newest is prerelease → picks prerelease.
|
||||
- mixed stable + prerelease, newest is stable → picks stable.
|
||||
- all drafts → `None` (triggers fallback).
|
||||
- malformed tag (`"weekly-build-3"`) alongside valid tags → skipped, valid winner returned.
|
||||
- empty input → `None`.
|
||||
- Clap: `fabro upgrade --prerelease --version 0.1.0` exits with `conflicts_with` error. (Existing `UpgradeArgs` tests style.)
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Persistent channel config, env var (`FABRO_UPGRADE_CHANNEL`), `--stable` opt-out.
|
||||
- Changing background upgrade notice to include prereleases.
|
||||
- Docs/changelog updates beyond the `--help` string (can follow in the same PR as trivial diffs).
|
||||
|
||||
## Open questions
|
||||
|
||||
None.
|
||||
|
|
@ -1,108 +0,0 @@
|
|||
---
|
||||
date: 2026-04-19
|
||||
topic: run-archived-status
|
||||
---
|
||||
|
||||
# Add a Terminal `archived` Status to Workflow Runs
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Workflow runs accumulate over time. Today the three terminal statuses (`succeeded`, `failed`, `dead`) all share the same shelf: they stay visible in `fabro ps`/`fabro runs list` with `-a`, clutter API listings, and carry no signal about whether the user has actually finished with the run. Users want a way to mark a run "I've reviewed this, no further action needed" that (a) captures that intent explicitly, (b) drops the run out of default listings, and (c) leaves all data readable for reference. The mark is also the natural signal an eventual retention/delete policy would key off, though deletion itself is out of scope here.
|
||||
|
||||
## Behavior by Status
|
||||
|
||||
| Operation | Active (submitted/starting/running/paused) | Terminal (succeeded/failed/dead) | Archived |
|
||||
|---|---|---|---|
|
||||
| Read detail, logs, artifacts, attach-replay | ✓ | ✓ | ✓ |
|
||||
| Resume / rewind / retro re-run | ✓ where valid | ✓ where valid | ✗ (unarchive first) |
|
||||
| Archive | ✗ (finish first) | ✓ | — |
|
||||
| Unarchive | — | — | ✓ (restores prior terminal status) |
|
||||
| Shown in default `fabro ps` / `runs list` | ✓ | ✗ | ✗ (hidden; opt-in flag) |
|
||||
|
||||
## Requirements
|
||||
|
||||
**Status model**
|
||||
- R1. Add `archived` as a new terminal variant of `RunStatus`, surfaced as the run's `status` field in CLI, API, and UI consumers.
|
||||
- R2. Archiving is permitted only from existing terminal statuses: `succeeded`, `failed`, `dead`. Archiving an active run is rejected.
|
||||
- R3. Archiving is reversible. `unarchive` restores the exact terminal status the run held immediately before it was archived.
|
||||
- R4. The prior terminal status must be retained durably — either captured in the unarchive event payload or persisted on the run record — so unarchive is deterministic across restarts, reloads, and event replay.
|
||||
- R5. All three source terminal statuses archive identically — no per-source gating, reasons, or side effects differ between `succeeded`/`failed`/`dead`.
|
||||
|
||||
**Operations**
|
||||
- R6. `fabro archive <run_id> [<run_id>...]` archives one or more runs in a single invocation. Per-id failures are surfaced individually; the batch does not abort on the first error.
|
||||
- R7. `fabro unarchive <run_id> [<run_id>...]` reverses the archive for one or more runs in a single invocation, with the same per-id failure semantics as R6.
|
||||
- R8. HTTP API exposes archive and unarchive operations and supports the same multi-id bulk behavior the CLI uses.
|
||||
- R9. Archive and unarchive appear on the run-timeline event stream with the actor that performed the action, so the transition is captured for audit alongside existing status events. Whether this is implemented as new `RunArchived`/`RunUnarchived` event variants or by extending the existing status-transition event family is deferred to planning.
|
||||
|
||||
**Visibility**
|
||||
- R10. `fabro ps` and `fabro runs list` hide archived runs by default. An explicit flag opts them in; the exact flag shape (extend `-a/--all` vs. add `--archived`) is a planning decision.
|
||||
- R11. The JSON listing API exposes an equivalent archived-visibility control so API consumers opt in to archived runs explicitly and don't get surprised by a new default set.
|
||||
- R12. In v1, direct run-detail reads by run ID continue to succeed regardless of archived state — archive is a listing-filter concern, not an access-control one. Future retention/deletion layers may reintroduce access-control semantics on top of archive; v1 does not foreclose that.
|
||||
|
||||
**Safety of archived runs**
|
||||
- R13. Archived runs are read-only (see R14 for the mutation-rejection contract). Read surfaces — viewing detail, logs, artifacts, attach-replay, checkpoint inspection — all continue to work as they did in the prior terminal status.
|
||||
- R14. Any operation that would mutate a run — lifecycle (resume, rewind, retro re-run, run-control actions, further status transitions) *and* metadata (label edits, tag changes, any future annotation/comment surface) — must reject with a clear error that tells the user to `fabro unarchive` first. Archived is a fully frozen state from a user perspective; R13's "read-only" is defined by this rejection list. The one preserved escape hatch is the system's existing "always-allow `Dead`" path in `can_transition_to` — supervisor/orphan handling may still mark an archived run `Dead` (with the archive then effectively discarded). The exhaustive endpoint-level audit is a planning task (see Deferred Questions).
|
||||
- R15. Archiving does not change storage, retention, or cleanup behavior. Checkpoints, artifacts, logs, and blob references remain as they were in the prior terminal status.
|
||||
- R16. When a consumer explicitly asks for archived runs — either by the archived-visibility opt-in flag, or (if/when a status filter is introduced) by `status=archived` — the explicit ask is sufficient; consumers should not need to *also* set a second gate. Note: today neither the CLI (`RunsListArgs`) nor the `listRuns` API exposes a generic `status=` filter; introducing one is not a v1 requirement, but if it arrives later it should interact with the archived opt-in per this rule.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A user runs `fabro archive <id>`. Listings that would previously surface the run's terminal status (e.g. `fabro ps -a`, `fabro runs list -a`, or the JSON list API) no longer include it. A listing with the archived-opt-in flag surfaces it with `status = archived`.
|
||||
- `fabro unarchive <id>` returns the run to its original terminal status; listings and behavior match the pre-archive state exactly.
|
||||
- Attempting any mutating operation on an archived run produces an actionable error referencing `unarchive`.
|
||||
- Archive/unarchive actions appear in the run's event timeline with actor information.
|
||||
- Bulk form (`fabro archive A B C`) archives each independently and surfaces per-run success/failure without aborting the whole batch.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Web UI archive/unarchive controls — deferred; CLI + API only in v1. The web UI is itself an API consumer, so it will pick up the new default-hide listing behavior passively; no UI code change is required in v1 to keep that surface consistent.
|
||||
- Automatic archive policies (age, count, per-workflow retention) — deferred.
|
||||
- Storage reduction tied to archive (checkpoint pruning, log compaction, artifact eviction) — explicitly out of scope.
|
||||
- Deletion of archived runs — out of scope; archived is a signal that deletion *could* later key off, not a step toward it in this feature. Making archived runs efficiently queryable as a set (needed for a future retention job) is not a v1 requirement beyond what R16 already provides.
|
||||
- Permission/authorization model for who can archive whose runs — assumed to match existing mutation authorization; no new authz surface introduced here. Planning should confirm this during the mutation-endpoint audit (see Deferred Questions).
|
||||
- Archiving active (non-terminal) runs — not supported; users cancel/complete first.
|
||||
- Forward-compat of stored `prior_status` values across a future `RunStatus` enum evolution — out of scope; if the enum later changes shape, archived runs persisted at that time will be handled by whatever migration that change introduces.
|
||||
- Idempotency of repeated archive/unarchive invocations — planning decision (no-op vs. error). This *is* user-visible via the bulk per-id result shape in R6/R7, so planning must pick a concrete behavior before shipping; the decision is only deferred in the sense that brainstorm didn't choose between no-op and error.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **Auto-hide terminal runs by default (no archive action)** — rejected. The whole premise is to *capture user intent*. Auto-hiding silently removes runs the user has not acknowledged, producing a false "it's handled" signal and leaving users guessing which of a large terminal set they've actually reviewed. The explicit-action model trades a small amount of ceremony for a clear, user-driven triage state. It is also compatible with a future auto-archive policy layered on top (out of scope for v1), so nothing is lost.
|
||||
- **Boolean `archived` flag orthogonal to status** — rejected for v1. Keeps status semantics stable and avoids the prior-status-restoration problem entirely, but forces every consumer (CLI, API, UI, reports) to learn a second axis. The single-status-axis model is simpler at the point of use given the v1 shape; see Key Decisions for the accepted tradeoff.
|
||||
- **Predicate-based bulk archive (`--status succeeded --older-than 14d`)** — deferred. Would make mass-triage frictionless for users with many accumulated runs, but ID-based bulk (R6) is enough to validate the core premise in v1 and avoids defining a query language up front. Can be added once adoption is observed.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **New first-class terminal enum value, not a boolean flag** — shown as the surface status in `ps`, API, and UI. Keeping status as the single axis avoids teaching every consumer about a parallel `archived` dimension. Accepted tradeoff: a future orthogonal lifecycle axis (e.g. `superseded`, soft-delete) would need its own modeling rather than composing with `archived`. For the stated v1 shape (reversible user-intent triage on a reached-terminal run), the single-axis model is simpler at the point of use even though it costs more if lifecycle gains a second axis later. This choice is also load-bearing and expensive to reverse: once `Archived` is serialized into the event log, checkpoint metadata, the OpenAPI spec, and the TypeScript client, converting to an orthogonal boolean later would require a data migration across every one of those surfaces.
|
||||
- **Reversible via unarchive, restoring prior terminal status** — archival is triage intent, not a destructive operation. Accidental archives must be trivially undoable without data loss.
|
||||
- **Read-only while archived; mutation requires explicit unarchive** — prevents the "I said I was done with this" run from silently mutating. Forces a conscious lift.
|
||||
- **Hidden from default listings with opt-in flag** — the whole point of the feature is reducing noise in default views. Direct-by-ID access stays unrestricted.
|
||||
- **No storage impact** — keeps blast radius small. Storage/retention is a separate future feature.
|
||||
- **All three source terminal statuses archive identically** — simplest state machine; avoids carving out `dead` or `failed` as "un-archivable."
|
||||
|
||||
## Dependencies / Assumptions
|
||||
|
||||
- `RunStatus` and its transition guard in `lib/crates/fabro-types/src/status.rs` will be extended with `Archived`, and with transitions from each of `Succeeded`/`Failed`/`Dead` into `Archived` and back. *Verified against current code.* Note: `can_transition_to` today uses `is_terminal()` to hard-block any exit from a terminal state (except to `Dead`). Introducing archived therefore requires either narrowing `is_terminal()` into two concepts — "reached a terminal outcome" vs. "immutable / not transitionable" — or special-casing archive/unarchive transitions in the guard. Which direction to take is a planning decision; whichever is chosen, planning must audit every existing caller of `is_terminal()` (UI state, completion detection, billing roll-ups, reporting) and decide per caller whether `Archived` should be treated as "reached terminal" or "immutable / not transitionable."
|
||||
- `RunStatusRecord` carries a single status + optional reason + `updated_at`. `RunProjection` in `lib/crates/fabro-store/src/run_state.rs` holds only the most recent `RunStatusRecord` — each status-change event overwrites `self.status` and there is no queryable status-history projection. *Verified against current code.* The event log itself retains the full sequence of status-change events via a per-run monotonic `event_seq` (`AtomicU32` in `lib/crates/fabro-store/src/slate/run_store.rs`), so events for a given run are replayed in append order; prior terminal status is therefore recoverable via replay. Given the existing projection shape, the cleanest pattern for R4 is to carry the restored status on the unarchive event payload itself so replay reconstructs state without scanning backward. Final mechanism choice is still a planning decision.
|
||||
- The OpenAPI spec `docs/api-reference/fabro-api.yaml` is the source of truth for the HTTP interface; archive/unarchive endpoints and the new status value are added there first, and both the Rust progenitor client and the TS Axios client regenerate per the existing workflow. The existing `listRuns` operation must also gain a query parameter (e.g. `include_archived`) — today it only accepts pagination params — so API consumers have an explicit way to opt in; this is an edit to an existing endpoint, not purely additive.
|
||||
- Run events are extensible; existing variants like `RunRemoving` in `lib/crates/fabro-workflow/src/event.rs` serve as shape precedents for `RunArchived`/`RunUnarchived`.
|
||||
- Run IDs are assumed to be globally unique and resolvable without additional workspace/project scoping. R6/R7's bare-positional-ID CLI shape depends on this. If namespacing is later introduced, scoping will need to be added to the archive CLI as a compat-aware change.
|
||||
- Existing mutation operations in `lib/crates/fabro-workflow/src/operations/` are the set that must be taught to reject when the run is archived.
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
|
||||
- (none)
|
||||
|
||||
### Deferred to Planning
|
||||
|
||||
- [Affects R4][Technical] Record prior terminal status on the unarchive event payload (preferred pattern given the existing projection shape — see Dependencies), vs. add a `prior_status` field to the run record, vs. walk the event log on unarchive. Pick the mechanism and update the projection accordingly.
|
||||
- [Affects R10][User decision] Extend `-a/--all` to also include archived, vs. add a separate `--archived` flag (and whether `-a --archived` composes). This also drives the 'No running processes found' hint text. Compat note: today `-a` means "show all runs including terminal"; extending it silently narrows that meaning, while a separate `--archived` flag preserves it.
|
||||
- [Affects R8][Technical] API shape — dedicated endpoints (`POST /runs/{id}/archive`, `POST /runs/{id}/unarchive`, plus a bulk form) vs. extending the existing `RunControlAction` enum with `Archive`/`Unarchive`.
|
||||
- [Affects R9][Technical] Exact event variant names and payload shape (`RunArchived { actor }`, `RunUnarchived { actor, restored_status }`?), including whether they piggyback on the existing status-transition event family.
|
||||
- [Affects R14][Technical] The full list of endpoints and operations that must reject on archived runs; planning should audit `operations/*.rs` and the server's mutation routes, including label/tag write paths and any event-producing endpoint that bypasses `can_transition_to`.
|
||||
- [Affects R11][Technical] Whether other internal list surfaces (dashboards, summaries, PR cross-references, usage roll-ups) need the same default-hide treatment, or whether they're acceptable as-is.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ `/ce:plan` for structured implementation planning
|
||||
|
|
@ -1,132 +0,0 @@
|
|||
---
|
||||
date: 2026-04-19
|
||||
topic: run-files-changed-tab
|
||||
---
|
||||
|
||||
# Run "Files Changed" Tab — Make It Real
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Every workflow run modifies files in a sandboxed worktree. Today the run detail UI has a **Files** tab skeleton that imports `@pierre/diffs` and renders hardcoded `fallbackFiles` when the loader's response is empty — which is always the case in a non-demo server, because the endpoint `GET /runs/{id}/files` the tab calls does not exist. The OpenAPI spec even defines `PaginatedRunFileList` and `FileDiff`, but no operation references them.
|
||||
|
||||
Users cannot see what a run actually changed without leaving the product. The goal of this brainstorm is to replace the demo/fallback content with a real, per-run diff rendered by `@pierre/diffs`, with sensible behavior across the run lifecycle (running → succeeded/partial → failed → sandbox destroyed).
|
||||
|
||||
Persistence reality today (verified in code):
|
||||
- `RunProjection.final_patch: Option<String>` is captured on `RunCompleted` via the lifecycle git hook (`lib/crates/fabro-workflow/src/lifecycle/git.rs`) and stored in SlateDB (`lib/crates/fabro-store/src/run_state.rs`).
|
||||
- It is a **unified-patch string** (output of `git diff <base_sha> HEAD`), not structured per-file `{old_file, new_file}` contents.
|
||||
- It is set only for `Success` / `PartialSuccess` — `RunFailed` does not populate it.
|
||||
- Successful checkpoint commits are pushed to `origin` (E2E: `daytona_integration.rs:1541`), so the branch + SHAs are typically reachable from origin after the sandbox is gone — though **branch retention is not a guarantee** (auto-delete on merge, admin cleanup, force-push, repo archival can prune refs). We treat origin as a best-effort source, not an authority.
|
||||
|
||||
### Failure modes this plan must avoid
|
||||
- **Partial-coverage trust erosion.** The tab silently shows content in some states and nothing in others. Users form the impression "works sometimes."
|
||||
- **Stale-but-plausible content.** The UI shows a diff that's minutes old with no indication of freshness; users act on it as current.
|
||||
- **Secret exfiltration.** A working-tree file contains a token/credential and the tab happily displays it to anyone with run access.
|
||||
- **Server DoS.** An authenticated caller hits the endpoint in a loop against a massive run and pegs the box.
|
||||
|
||||
Each requirement below names the failure mode it addresses.
|
||||
|
||||
## Requirements
|
||||
|
||||
**Presentation (Files tab UI)**
|
||||
- R1. The Files tab renders a real `FileDiff[]` via `@pierre/diffs`' `MultiFileDiff` for the current run.
|
||||
- R2. Keep the existing split/unified and disable-background toggles. Persist the split/unified choice in browser localStorage (scope is per-browser, not per-account; note: shared-machine users inherit the last setting). If an md-breakpoint collapse fires (R8), it overrides the rendered view without overwriting the stored preference.
|
||||
- R3. Remove (or hide behind a feature flag) the inline "Steer" comment affordance — out of scope here; it will be brainstormed separately when the backend `/runs/{id}/steer` is designed.
|
||||
- R4. **Empty-state taxonomy** (expected: no diff exists): distinct messaging for (a) the run has not produced a `base_sha` yet (Submitted/Starting), (b) the run produced a `base_sha` but touched no files, (c) the run completed but has no recoverable diff (Failed with no checkpoint, or Succeeded-but-`final_patch`-absent + origin unreachable). The toolbar stays usable in all three.
|
||||
- R5. **Error-state taxonomy** (diff should exist but we could not retrieve it): distinct UI treatment for (a) transient / retriable (network, timeout, reconnect failure) with a Retry affordance, (b) permanent / data-loss — typically caught by R4(c) instead, (c) auth/config (e.g. origin credentials invalid) with a contact-admin affordance, (d) unknown 5xx with a request ID for support. When `final_patch` is available and origin is unreachable, the response flows into R12's degraded view, not R5.
|
||||
- R6. **Loading and refresh**: initial fetch shows a diff-area skeleton (toolbar still visible). The tab exposes an explicit **Refresh** button in the toolbar. For **Running** runs the freshness indicator reads "Checkpoint Xm ago" sourced from the `to_sha` commit time (not the HTTP response time) so users can distinguish "tab fetched seconds ago" from "nothing has changed on the agent side in minutes". For completed runs it reads "Fetched Xs ago" sourced from HTTP response time. Prior content remains visible during re-fetch; a failed refresh leaves the last good data on screen with an inline error banner. The Refresh button is disabled when the last response's `to_sha` equals the currently-displayed `to_sha`. No auto-refresh in v1.
|
||||
- R7. **Deep linking**: the URL supports a per-file anchor (`#file=<path>`) that scrolls to that file and expands it on load.
|
||||
- R8. **Accessibility and responsive**: below Tailwind `md` the split view auto-collapses to unified; `j`/`k` keys move between files; `change_kind` indicators carry accessible names; toolbar controls meet WCAG touch-target size; focus returns to the refresh button after refresh.
|
||||
|
||||
**Diff semantics**
|
||||
- R9. Show the **net diff between the run's `base_sha` and its current head commit** (equivalent to `git diff <base_sha> HEAD`). Committed changes only; uncommitted working-tree state is **not** surfaced in v1.
|
||||
- R10. **Live (Running)** reads the sandbox's HEAD via the sandbox's git (effectively "diff as of the most recent checkpoint"). **Semantics** match `sandbox_git::git_diff` (`git diff <base_sha> HEAD`), but that helper is `pub(crate)`, has a 30 s timeout that conflicts with R32, and returns a single unbounded string — it cannot satisfy R24/R25/R27/R28. A new sibling helper is required: enumerates via `git diff --raw -z --find-renames=50% <base>..HEAD` with an early-stop at the 200-file cap, then per-file materializes via `git cat-file --batch` (size-gated) and `git show <sha>:<path>` for non-binary entries. Committed-HEAD reads are safe to interleave with in-progress agent work (no index/working-tree mutation).
|
||||
- R11. **Post-sandbox** reconstructs the diff from the origin-side checkpoint branch using the run's recorded `base_sha` and head SHA.
|
||||
- R12. **Fallback when origin cannot be read** (branch pruned, fetch failure, repo archived) and `final_patch` is available (Success / PartialSuccess only per Persistence reality): parse the stored `final_patch` string into a degraded `FileDiff[]` — each entry has the file name, `change_kind`, and hunks, but **no full old/new contents**. The UI renders a "patch-only view" indicator so users know contents are not available. `@pierre/diffs` consumes this via empty `contents` plus a visible banner on each affected file (exact UI treatment is a planning concern; behavior is specified here). Note: the current `DiffFile` schema has only `{name, contents}`; R12 requires either (a) a new optional `hunks` field on `FileDiff`, or (b) dropping R12 in favor of R4's empty-state path — see Outstanding Questions. The degraded view must re-apply R24/R25/R26/R31 caps + denylist during parsing; filters apply to the response, not the source. If `final_patch` is `None` on a completed run, treat as R4(c) (no recoverable diff).
|
||||
- R13. **Coverage by run state**: `Running` / `Succeeded` / `PartialSuccess` always produce a diff. `Failed` produces a diff **if** the run checkpointed at least once before failing: use `RunFailed.git_commit_sha` (already carried on the event) as the head SHA and reconstruct from origin via R11, or from the sandbox if reachable via R10. Failed runs with no successful checkpoint fall through to R4(c). No changes to the run lifecycle or the `RunFailed` event are required.
|
||||
|
||||
**Backend / API contract**
|
||||
- R14. Add `GET /api/v1/runs/{id}/files` with `operationId: listRunFiles`, returning the existing `PaginatedRunFileList` schema. The name is retained (additive change); v1 repurposes the existing `meta` object with top-level `truncated: bool` + `total_changed: int` per R27 rather than populating cursor fields. A rename can happen in a later additive version.
|
||||
- R15. The endpoint accepts optional `from_sha` and `to_sha` query parameters. Defaults: `from_sha = base_sha`, `to_sha = current HEAD`. Clients omit both in v1 and the server **rejects non-default values with 400** in v1 (prevents arbitrary-ref reads outside the run's branch; re-enable once an ancestry check against the run's branch head is in place). A future version can enable non-default values without a schema break. Rationale: keep the forward-compat slot without opening a read-ref surface before it's validated.
|
||||
- R16. Materialize the `FileDiff[]` **on demand** at request time. No new run-time persistence of per-file contents.
|
||||
- R17. Do not remove or change SlateDB's existing `final_patch` string projection. Other paths depend on it (PR body generation). The new endpoint is additive.
|
||||
- R18. No changes to the run lifecycle (no new events, no push-on-failure, no new event props). The tab works with existing persisted state.
|
||||
|
||||
**Schema changes to `FileDiff`** (`docs/api-reference/fabro-api.yaml`)
|
||||
- R19. Add `change_kind: added | modified | deleted | renamed` to `FileDiff` as an **optional** field (the server always populates it on new responses; absence is tolerated for schema back-compat with pre-existing clients). Clients should consume `change_kind` when present and fall back to inferring from `old_file`/`new_file` content presence per R20.
|
||||
- R20. For added files: `old_file.contents = ""` and `old_file.name = new_file.name`. For deleted files: `new_file.contents = ""` and `new_file.name = old_file.name`. For renames: both `old_file.name` and `new_file.name` populated with distinct values; contents populated.
|
||||
- R21. Add **independent** booleans `truncated: bool` and `binary: bool` (both default `false`). `truncated` means size/line caps were hit (R24) or response-level budget was exhausted (R25). `binary` means content is not textual (R26). The two can coexist on a single entry.
|
||||
- R22. Add `sensitive: bool` (default `false`) to mark entries skipped by the denylist (R29). Contents empty, but the name/change_kind surface so reviewers know a change happened.
|
||||
- R23. Schema additions are additive: `old_file`/`new_file` stay `required` on `FileDiff` (empty-string contents represent added/deleted sides). New fields are optional for client back-compat; existing consumers that ignore them still render correctly.
|
||||
|
||||
**Practical limits**
|
||||
- R24. Per-file cap (**Provisional, pending cap calibration below**): **256 KB** and **20,000 lines**. Over-cap entries return `truncated: true` with empty `contents`.
|
||||
- R25. Aggregate response cap (**Provisional**): **5 MB** of total `contents` bytes. Once the running byte budget is exceeded, subsequent entries are returned with `name` + `change_kind` only (empty contents, `truncated: true`). The response `meta.truncated` flag also flips to `true` so the UI can show an aggregate banner.
|
||||
- R26. Skip binary files: return `{name, change_kind, binary: true, contents: ""}`. Do **not** set `truncated` on the binary entry itself unless it also exceeds the per-file size cap; binary files that exhaust the aggregate budget do not retroactively change; they affect only the cap for subsequent entries.
|
||||
- R27. File-count cap (**Provisional**): **200 files**. Overflow surfaces as `meta.truncated: true` + `meta.total_changed` with a persistent banner on the tab. v1 repurposes the existing `meta` object rather than implementing cursor pagination; a real cursor is deferred until a consumer needs it.
|
||||
- R28. Rename detection uses `git diff --find-renames=50%`. Below threshold, changes are emitted as add + delete (no `renamed` entry). This is a git invocation contract, not a hand-rolled heuristic.
|
||||
|
||||
**Security & observability**
|
||||
- R29. The endpoint enforces **`AuthenticatedService` authentication** (the same extractor used by other `/runs/{id}/*` endpoints). Run-ownership / workspace authorization is **not** currently enforced on sibling endpoints; adding it is a cross-cutting concern tracked separately. Unauthorized callers receive 404 (not 403) to avoid run-ID enumeration. If a workspace-membership layer is introduced later, this endpoint inherits it automatically via the shared extractor.
|
||||
- R30. **Committed-only scope is the primary secret-exposure control.** Because R9 restricts the diff to committed content, `.gitignore` is not itself a mitigation (git already respects it) — the real control is the denylist (R31) plus the caller's pre-existing run-access authorization. This requirement exists to make the threat model explicit: the tab shows what a user with the same repo access would see via `git diff` locally, no more and no less.
|
||||
- R31. **Sensitive-path denylist** (defense-in-depth, not a complete control): skip entries whose repo-relative paths match a built-in denylist (`.env`, `.env.*`, `*.pem`, `id_rsa*`, `.aws/credentials`, `.git/config`, `*.p12`, `*.keystore`, `*.key`). Return a placeholder entry with `sensitive: true` (R22). The denylist is owned by `fabro-server` and can be extended via config in a follow-up. Content-based secret detection is **out of scope**: a committed secret in a non-matching path is visible to anyone with run access, same as it would be via `git show` against the origin repo. The denylist narrows the accidental-exposure surface on common filenames; it is not a guarantee.
|
||||
- R32. **Request budget**: hard timeout on the git subprocess (10 s in sandbox, 20 s on host), per-caller rate limit on `/runs/{id}/files` (shared with sibling run endpoints), and **request coalescing per run**: concurrent callers for the same run share a single in-flight materialization — the second caller does not kick off its own git work nor receive a 429. Stop enumeration early once the 200-file cap is hit; do not enumerate-then-truncate.
|
||||
- R33. **Server-side git hardening**: the `git` process (on host for the origin path) runs with `core.hooksPath=/dev/null`, `protocol.ext.allow=never`, smudge/clean filters disabled, and no `GIT_CONFIG_*` leakage. All interpolated inputs (SHAs, paths, refs) go through `shell_quote()` per project rules. Content comes from `git show <sha>:<path>` (blob addressing), never from filesystem reads. Committed symlinks are surfaced as a file whose `contents` is the literal link-target string; they are never dereferenced. **Applicability** depends on the post-sandbox read mechanism choice (see Outstanding Questions): under a GitHub REST read path, the subprocess flags are moot and blob addressing is via the REST API.
|
||||
- R34. `X-Fabro-Demo: 1` short-circuits to fixture output and must never trigger a real run lookup or sandbox/origin access. A real run ID without the header always goes through the normal auth + materialization path; the two modes cannot cross-contaminate.
|
||||
- R35. Diff contents, full changed-file paths, and raw git stderr must **not** appear in `tracing` logs, Sentry breadcrumbs, or Segment events. Log only counts, sizes, durations, and run IDs. See `docs-internal/logging-strategy.md`.
|
||||
|
||||
**Demo mode**
|
||||
- R36. Demo mode returns a static `FileDiff[]` fixture so homepage/marketing demos work. The fixture currently hardcoded in `apps/fabro-web/app/routes/run-files.tsx` (`fallbackFiles`) moves to the server's demo handler alongside the other `/runs/{id}/*` demo stubs; the frontend no longer ships a fallback.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A typical successful run's Files tab shows the same content as `git diff <base_sha> HEAD` run against the sandbox — not `fallbackFiles`.
|
||||
- A currently-running run's Files tab shows the diff as of its most recent checkpoint; a **Refresh** click re-queries the sandbox and updates within the p95 budget.
|
||||
- A `Failed` run whose sandbox is still reachable shows the diff through its last checkpoint. A `Failed` run whose sandbox is gone shows the distinct empty-state message from R4, not a blank fallback.
|
||||
- A completed run whose sandbox has been destroyed still shows its diff when the origin branch is present; if origin cannot be read, the UI renders the `final_patch`-derived degraded view with a visible banner.
|
||||
- Pathological runs (many files, huge files, binary files) complete within **p95 < 3 s** for runs up to 200 files and 5 MB aggregate content on a warm host-side cache. First contentful paint within 500 ms of data arrival. Binary, truncated, and sensitive entries render with clear markers.
|
||||
- Demo mode (`X-Fabro-Demo: 1`) still shows a recognizable fixture without touching any real run / sandbox / origin.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- "Steer" inline commenting is **not** in scope.
|
||||
- **Uncommitted working-tree state is not surfaced in v1** — live runs show the diff as of the last checkpoint only. Revisit once @pierre/diffs and caching behavior are proven on committed state.
|
||||
- No per-stage / per-checkpoint UI view; only the aggregate `base → current`. The optional `from_sha`/`to_sha` query params in R15 exist purely as forward compatibility.
|
||||
- No search, filtering, grouping, or collapse UX beyond what `@pierre/diffs` provides out of the box.
|
||||
- No diff download / export / copy-as-patch.
|
||||
- No changes to the run lifecycle, `RunFailed` event, or the existing `final_patch` persistence.
|
||||
- No live streaming updates — refresh is user-initiated via R6's Refresh control.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Committed-HEAD-only in v1.** Removes working-tree concurrency with the agent, removes the gitignore/secret-exfil risk unique to uncommitted content, and makes live and post-sandbox views semantically identical. Uncommitted-tree view is a deliberate v2 candidate, not a cut corner.
|
||||
- **Materialize on demand + `final_patch` fallback, no new run-time persistence.** Primary path reads git (sandbox or origin). When origin cannot be read, fall back to parsing the existing `final_patch` into a degraded hunks-only view. This keeps the architecture read-heavy without duplicating content, and explicitly does not depend on origin retention as an authority.
|
||||
- **Don't touch the run lifecycle.** An earlier draft proposed a push-on-failure lifecycle change; that approach is dropped. It introduced side-effect surface (ref pollution, CI triggers, crash-time credentials) that outweighed the benefit; the Failed-post-sandbox empty state is an acceptable v1 UX.
|
||||
- **Extend `FileDiff` schema additively.** `change_kind`, `truncated`, `binary`, and `sensitive` are independent fields so each can be reasoned about on its own; `old_file`/`new_file` stay required for back-compat.
|
||||
- **Security at the edge, not in clients.** Server-side enforces authz (R29), `.gitignore` (R30), sensitive-path denylist (R31), request budget (R32), and git-process hardening (R33). The UI assumes it receives safe data.
|
||||
- **Drop `PaginationMeta` cursoring.** A single `meta.truncated: bool` + `total_changed: int` matches what v1 actually needs; a real cursor is deferred until there is a consumer.
|
||||
|
||||
## Dependencies / Assumptions
|
||||
|
||||
- `base_sha` is reliably recorded on `StartRecord` for runs that pass `RunStarted`. Runs in `Submitted`/`Starting` have no `base_sha` yet — covered by R4(a).
|
||||
- The `fabro-server` process can read from origin using the same GitHub credentials resolver as `git_push_host`. The exact read mechanism (REST blob/tree API vs. a server-side bare clone vs. a shared mirror) is explicitly flagged below as Resolve-Before-Planning.
|
||||
- `@pierre/diffs` accepts the existing `{old_file, new_file}` contents shape and treats the added fields (`change_kind`, `truncated`, `binary`, `sensitive`) as inert metadata the callsite can read. A quick spike confirms this before the OpenAPI change is locked.
|
||||
- `reconnect_run_sandbox` in `fabro-server` dispatches to `fabro_sandbox::reconnect::reconnect`, which already supports Local, Docker, and Daytona providers (verified in `lib/crates/fabro-sandbox/src/reconnect.rs`). Live-state diff therefore works for all three. When reconnect fails at runtime for any provider, the endpoint returns R5(a) (transient, retriable) — failure is a runtime condition, not a provider-support gap.
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
- [Affects R11][Needs research] **Post-sandbox read mechanism**: GitHub REST `git/trees` + `git/blobs` vs. server-side bare clone (with cache) vs. a shared mirror. Each has different latency, rate-limit, and privacy profile. Pick one before planning because it shapes the handler, caching, and failure modes. Current leaning: GitHub REST with a per-installation token scoped to the run's repo, because it avoids server-side disk state; validate with a quick LOE estimate for a bare-clone alternative.
|
||||
- [Affects R24, R25, R27][Needs research] **Cap calibration**: sample P50/P95 `final_patch` sizes and file counts across recent runs before locking numeric caps. The 200 / 256 KB / 20 k / 5 MB targets are placeholders; confirm (or revise) against real data. Target: keep the truncation rate on common workflows under **5%**. Until calibrated, treat the Success Criteria p95 as conditional on whatever caps survive.
|
||||
- [Affects R12][Decision] **Keep R12 (degraded patch-only view) or drop it in favor of R4(c) empty state?** R12 requires either (a) a new optional `hunks` field on `FileDiff`, or (b) a non-standard rendering in `@pierre/diffs` that may not be supported, plus a server-side patch parser. A scope-guardian review argues the empty state is sufficient; an adversarial review flags that the fallback is load-bearing only when origin retention fails (unknown frequency). Resolve before planning: run a two-day spike on (a) parse feasibility + @pierre/diffs input shape, and (b) telemetry on branch retention in the target repos. Then keep or drop R12 with evidence.
|
||||
|
||||
### Deferred to Planning
|
||||
- [Affects R9, R10][Technical] Should the sandbox-side `git` invocation be reused via `sandbox_git::git_diff`, or does the `--find-renames` + `-z` + raw machine-readable listing suggest a sibling helper? Either is fine; pick the smaller diff.
|
||||
- [Affects R12][Technical] The `final_patch`-derived degraded view needs a patch parser on the server. Is there an existing Rust patch parser we prefer (`gix-diff`, `unidiff`, hand-rolled)? Decide based on workspace dependency policy.
|
||||
- [Affects R22, R31][Technical] Denylist lives in `fabro-server` initially; revisit whether it should be config-driven in a follow-up.
|
||||
- [Affects R32][Technical] Concurrency cap of 1 per run: is this coarse-grained lock sufficient, or do we need request coalescing so concurrent viewers share one materialization?
|
||||
- [Affects R6][Technical] "Last updated Xs ago" freshness indicator — is the timestamp the HTTP response time, or the `to_sha` commit time? Probably the former; confirm with a UX spike.
|
||||
- [Affects R31][Technical] Which specific redaction-related primitives from `fabro-util` should we reuse? (Log scrubbing redaction is different from content redaction; content-redaction is explicitly **out of scope** per Key Decisions — skipping is simpler than masking.)
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ `/ce:plan` for structured implementation planning.
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
---
|
||||
date: 2026-04-19
|
||||
topic: web-ui-lifecycle-actions
|
||||
---
|
||||
|
||||
# Expose CLI Lifecycle Actions in the Web UI
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The Fabro web UI today is essentially read-only for run management. The only mutating action exposed is **Preview** (opens a sandbox port URL). Every other run lifecycle action — cancelling a stuck run, cleaning up the board, revisiting archived runs — requires dropping to the CLI.
|
||||
|
||||
Two concrete user problems drive this work:
|
||||
|
||||
1. **Daily friction for CLI users.** People live in the board view and detail pages but have to context-switch to a terminal to manage state.
|
||||
2. **Excludes non-CLI teammates.** PMs, reviewers, and stakeholders can watch runs but cannot participate in managing them, cutting the UI off as a collaboration surface.
|
||||
|
||||
The web UI should own the **everyday lifecycle operations** these users hit. Rarer or more dangerous CLI verbs (force-delete of active runs, checkpoint ops, etc.) can remain CLI-only by design; the goal is user value per surface, not parity for parity's sake.
|
||||
|
||||
Most server infrastructure already exists — `POST /runs/{id}/{cancel,archive,unarchive}` are live, wired to the workflow engine's operations, and emit SSE events. The remaining work is UI surface + a handful of concrete SSE reconciliation gaps (see Dependencies).
|
||||
|
||||
## Requirements
|
||||
|
||||
**Action set**
|
||||
- R1. Expose three lifecycle actions on the run detail page (`/runs/{id}`): **cancel**, **archive**, **unarchive**.
|
||||
- R2. Do not expose `pause`, `unpause`, or `delete` in this first pass. Pause/unpause has no evidenced daily-user need; delete's tab-close-mid-undo failure mode is unacceptable for a non-CLI teammate because observability is destroyed (there's no run to revisit to self-verify).
|
||||
- R3. Do not expose checkpoint operations (resume, rewind, fork) or HITL question answering in this first pass.
|
||||
- R4. Do not expose these actions on the board kanban cards or as bulk selection in this first pass.
|
||||
|
||||
**State-aware visibility**
|
||||
- R5. Only show an action when the run's current status makes it valid:
|
||||
- **cancel (primary)**: visible as a primary affordance when status is `submitted`, `runnable`, `starting`, `running`, or `paused`. Not shown as primary when `blocked` — see R6. The server also accepts cancel on `blocked` runs; that path is only reachable via the secondary surface from R6.
|
||||
- **archive**: visible only when status is terminal (`succeeded`, `failed`, `dead`) AND not already archived.
|
||||
- **unarchive**: visible only when `archived`.
|
||||
- R6. When a run is `blocked` (waiting on an HITL question), do not show cancel as a primary action. Instead, show an inline notice with the pending question text (from `GET /api/v1/runs/{id}/questions`, whose `ApiQuestion.text` field is already human-readable) and the instruction: "Answer this question via `fabro` CLI to continue." Cancel remains reachable via an overflow/secondary affordance (e.g., a "…" menu) for users who truly want to abandon the run. This protects the common case (non-CLI teammate accidentally cancelling work that was waiting for them) without fully hiding the escape hatch.
|
||||
- R7. Visibility updates live when the run status changes. The detail page must subscribe to the run's SSE event stream (`GET /runs/{id}/attach`) so action affordances appear/disappear without a manual refresh.
|
||||
|
||||
**Interaction & feedback**
|
||||
|
||||
Two toast patterns, matched to the reversibility of each action:
|
||||
|
||||
- R8. **Cancel uses a client-side deferred toast with a fixed 5-second countdown.** Cancel has partially-irreversible side effects (the agent stops mid-stage) so the undo window guards against misclicks.
|
||||
- Clicking cancel shows a toast with the action description, a 5-second countdown, and an **Undo** button. The cancel affordance enters a disabled/pending state during the window (not hidden — hiding mid-window misrepresents actual run state).
|
||||
- If the user clicks **Undo** before the countdown expires, the pending client-side timer is cancelled and no API call is made.
|
||||
- If the countdown expires, the client fires the API call. **Before firing**, the UI performs a `GET /api/v1/runs/{id}` refetch: if the run's status is no longer one where cancel is valid (e.g., the run completed or was cancelled elsewhere), the pending action is aborted and a brief "Run transitioned — cancel aborted" notice is shown instead. This covers the SSE-channel-unreachable case where R9's event-driven abort cannot fire.
|
||||
- If the tab is closed or navigated away (including SPA navigation to another route) mid-window, the pending action is silently cancelled. Accepted tradeoff of the client-only approach.
|
||||
|
||||
- R9. **Archive and unarchive fire immediately with an inverse-action toast.** Both are fully reversible by the opposite API call, so the 5-second countdown is overhead with no safety benefit. Gmail-archive shape:
|
||||
- Clicking archive fires `POST /runs/{id}/archive` immediately (optimistic UI: the run disappears from terminal views / moves to archived views right away).
|
||||
- On success, show a toast: "Run archived. **Unarchive**" with a visible action button. The toast remains dismissable for ~8 seconds.
|
||||
- Clicking **Unarchive** in the toast fires `POST /runs/{id}/unarchive`. The toast updates to "Run restored" briefly, then dismisses.
|
||||
- Unarchive-triggered-from-the-primary-affordance works identically, with the inverse verb.
|
||||
|
||||
- R10. **Undo-window collisions (cancel only).** While the cancel timer is pending for a run, other primary affordances for that run are disabled (not hidden). If an SSE event arrives for that run that would change its status (another tab, a CLI user, the run finishing naturally), the pending client-side timer is cancelled, the toast is dismissed with a brief notice ("Run transitioned — action cancelled"), and the UI reconciles to the new status. If a newly-valid action (e.g., archive becomes valid because the run just completed) results from the transition, its affordance lights up immediately rather than waiting for the toast to fully dismiss.
|
||||
|
||||
- R11. On a successful async cancel (status unchanged in the response body), the UI relies on SSE for the final status flip. No additional success toast beyond the deferred-toast already shown.
|
||||
|
||||
- R12. On API failure (including 409 precondition failures — e.g., the run transitioned out of a valid state between toast-expiry and API call), show an error toast that includes the server's error message, and refetch the run so the UI reconciles to actual state. For the archive/unarchive fire-immediately path, additionally roll back the optimistic UI change on failure.
|
||||
|
||||
- R13. **Multi-tab behavior (single-client rules apply per tab).** R8/R10 are scoped per-client: each tab runs its own timer. An SSE-delivered status transition in tab B (caused by tab A firing cancel) will cancel tab B's own pending timer for the same run per R10 and surface the transition notice. Cross-tab action coordination beyond what SSE already provides is not a requirement for this pass.
|
||||
|
||||
**Accessibility**
|
||||
- R14. Both toast patterns (deferred cancel toast; immediate archive/unarchive toast) must meet baseline a11y expectations:
|
||||
- Toast container uses `role="status"` with `aria-live="polite"` (assertive interrupts screen-reader output and is wrong here). Announcement names the action, e.g., "Cancel run requested, undoing in 5 seconds" or "Run archived. Press Unarchive to undo."
|
||||
- Toast does **not** steal focus, but is reachable via keyboard (tab order places the action button — Undo or Unarchive — immediately after the triggering affordance).
|
||||
- For the cancel deferred toast, while keyboard focus is on the **Undo** button, the 5-second countdown **pauses** and resumes counting down from the paused value when focus leaves. Focus leaving the Undo button after the countdown would have expired does not auto-fire the action — the user must still explicitly close the toast or navigate away for the countdown to resume its final tick.
|
||||
- Archive/unarchive toasts do not count down (they fire on click); they remain dismissable and focusable for ~8 seconds.
|
||||
- Touch targets (Undo / Unarchive buttons) meet 44×44 CSS px minimum. The detail page is expected to work on tablet and larger; phone-size support is not a requirement for this pass.
|
||||
- The action cluster is keyboard-operable end to end (no mouse-only affordances). Keyboard shortcuts for individual actions are out of scope for this pass.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- A user managing runs day-to-day can complete a full session (cancelling a stuck run, archiving finished ones, revisiting an archived one) without touching the CLI.
|
||||
- A non-CLI teammate can cancel or archive a run in the web UI without onboarding documentation beyond "click the button."
|
||||
- A non-CLI teammate who lands on a `blocked` run understands the run is waiting on a human answer, sees the question text, and does not accidentally cancel work in progress. **Note:** unblocking the teammate so they can actually *answer* the question requires HITL-answering in the web UI, which is deferred — this first pass prevents destruction, not participation. If blocked-teammate-can't-proceed proves to be a real painful pattern in usage, HITL answering should be the next scope to pick up.
|
||||
- When a run transitions state while the detail page is open (e.g., finishes, gets archived from the CLI, gets cancelled by someone else), the available actions update live without a page refresh.
|
||||
- The cancel deferred-toast component (toast container + Undo + pause-on-focus countdown + polite aria-live) is shaped so it can host future destructive actions (delete if we solve the observability problem; force-cancel if ever added) without redesign. The archive/unarchive immediate-inverse toast is a simpler shape that other reversible fire-and-forget actions can reuse.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
**Out of scope for this first pass:**
|
||||
- `pause` and `unpause` (no evidenced daily-user pain for the target personas; revisit if a real workflow surfaces).
|
||||
- `delete` (tab-close-silently-cancels destroys observability — there's no run to revisit to self-verify — which is unacceptable for the non-CLI teammate persona; revisit with server-side soft-delete or a different UX).
|
||||
- Force-delete of active runs (`rm --force`).
|
||||
- Checkpoint operations: `resume`, `rewind`, `fork`. These need parameter input (which checkpoint? which branch?) that doesn't fit the uniform button+toast pattern.
|
||||
- Answering HITL questions from the web UI. R6 surfaces the question read-only and points to the CLI.
|
||||
- Board-card actions and bulk multi-select on the board.
|
||||
- Dense table/list view of runs.
|
||||
- Server-side deferred/pending states.
|
||||
- Keyboard shortcuts for individual actions.
|
||||
- Role-based authorization (assumed unchanged from today; all authenticated users can take all actions).
|
||||
- Phone-size responsive layout.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Cancel + archive + unarchive only.** Cancel addresses the clearest daily pain (stuck runs). Archive/unarchive addresses board clutter and is fully reversible by the opposite action — lowest-risk place to validate the interaction pattern. Pause/unpause are deferred for lack of evidenced need; delete is deferred because its client-side-undo failure mode destroys observability for the non-CLI teammate persona.
|
||||
- **Run detail page only, not the board.** Keep the first pass tight.
|
||||
- **Two toast patterns matched to reversibility, not one uniform pattern.** Cancel is partially irreversible → deferred-toast with a bound 5-second countdown. Archive/unarchive are fully reversible via the opposite API call → fire-immediately with an inverse-action toast (Gmail-archive shape). This is more spec than "one pattern for everything" but maps to a real property of the actions and eliminates a pointless friction tax on the reversible ones. The shared toast infrastructure (container, action-button slot, aria-live, keyboard reachability) is reused across both; only the cancel path carries the countdown + focus-pause machinery.
|
||||
- **Pre-fire status recheck on the deferred cancel path.** At countdown expiry, the client refetches `GET /runs/{id}` before firing the cancel API call. This covers the SSE-unreachable failure mode where R10's event-driven abort cannot fire: without the recheck, a dead SSE channel would silently degrade to "timer fires, 409 error, user sees error toast for a race they didn't create." One extra GET per cancel is a cheap premium for reliable UX.
|
||||
- **Blocked runs suppress cancel as a primary affordance and show the pending question.** Protects non-CLI teammates from the worst failure mode (cancelling work that was waiting for them). Cancel remains reachable via a secondary/overflow affordance for users who genuinely want to abandon. This solves the destruction problem but leaves the participation problem for HITL-in-the-web to solve later.
|
||||
- **Client-side deferral, not server-side.** Chosen on shipping speed; does not add new lifecycle states. Accepted tradeoff: the "undo" promise is soft — tab close or SPA nav silently cancels. This is tolerable precisely because the action with the worst silent-cancellation consequence (delete) was scoped out.
|
||||
- **Accessibility is in the requirements, not deferred to implementation.** ARIA semantics, keyboard reachability, focus-pauses-countdown, touch-target sizing, and aria-live politeness are specified rather than left as "standard best practices."
|
||||
- **Pattern reuse is claimed only within this action family.** We do not claim "adding resume/rewind/fork/HITL later is same shape, new button." Those need parameter input (checkpoint choice, answer text) that the button+toast pattern doesn't host. That's fine — these patterns are for fire-and-forget lifecycle mutations, and the rest of the verbs will need their own UX.
|
||||
|
||||
## Dependencies / Assumptions
|
||||
|
||||
- The existing API endpoints (`POST /runs/{id}/{cancel,archive,unarchive}`) are stable and will not require spec changes. Verified against `docs/api-reference/fabro-api.yaml`.
|
||||
- The generated TypeScript client in `lib/packages/fabro-api-client` exposes (or will trivially expose after regeneration) methods for these endpoints.
|
||||
- **SSE coverage is not uniform.** The server emits `run.*` events for status transitions including `run.archived` / `run.unarchived` (`fabro-workflow/src/event.rs`, `fabro-server/src/server.rs`). Known gaps the plan must address:
|
||||
- The board's event allowlist (`apps/fabro-web/app/routes/runs.tsx` `BOARD_STATUS_EVENTS`) does not currently include `run.archived` / `run.unarchived`. Adding them is in scope.
|
||||
- The per-run `/attach` SSE stream terminates on `RunCompleted` / `RunFailed`. Archive/unarchive events fire on already-terminal runs, so the detail page must either reconnect to a non-terminating channel, refetch on the successful archive/unarchive response, or listen at a layer above `/attach`. Planning should pick an approach.
|
||||
- **Run detail page is not yet SSE-subscribed.** `apps/fabro-web/app/routes/run-detail.tsx` currently fetches the run once via the React Router loader and does not subscribe to `/api/v1/runs/{id}/attach`. Wiring this subscription at the detail-page level (the owner of `run.status` that drives R5 visibility) is net-new work for R7. Individual tab components (stage-sidebar, run-files) already have per-run SSE subscriptions that can be used as a pattern.
|
||||
- **No undo-capable toast system exists yet.** The only Toast in `apps/fabro-web` is a read-only live-region banner (`apps/fabro-web/app/routes/run-files/states.tsx`) with local `useState`/`setTimeout`. R8 + R9 + R12 together require a shared toast component with: a countdown, action-button slot, programmatic dismiss, multi-toast coexistence, polite aria-live, and focus-pauses-countdown behavior. This is net-new UI infrastructure.
|
||||
- **Cancel semantics.** For `submitted` and `runnable` runs, cancel synchronously flips lifecycle `status` to `failed` with `status_reason: cancelled` and returns that on the response. For `starting`/`running`/`blocked`/`paused` runs, cancel returns 200 with unchanged status and the transition lands asynchronously via the workflow engine. The UI should treat cancel as "request accepted" and rely on SSE for the final status flip — R10 covers this implicitly, but the plan should make the optimistic-UI behavior explicit (e.g., the cancel affordance stays in its disabled/pending state until either the response body carries the synchronous `failed`/`cancelled` result or the SSE-driven reconciliation arrives).
|
||||
- **Per-run `/attach` stream has silent termination paths beyond the terminal-event case.** `attach_event_is_terminal` only matches `RunCompleted | RunFailed`, but the task that drives the stream can also exit without a terminal marker if the store read errors, if the run projection becomes non-active mid-replay, or if cancel lands on a runnable run that never transitioned to running (covered by the `cancel_before_run_transitions_to_running_returns_empty_attach_stream` test in `fabro-server/src/server.rs`). R7 and R10 must therefore not assume a terminal event will always land: the plan needs a fallback refetch path for "SSE stream ended without a terminal marker" and for "SSE channel unreachable during an undo window."
|
||||
- Authorization is a non-issue today (single-user / trusted deployment assumption). If multi-tenant auth lands, the action affordances will need to respect it, but that's a separate workstream.
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Deferred to Planning
|
||||
- [Affects R8][Design] Exact visual placement of the action cluster in the detail page header: single "Actions" dropdown vs. inline buttons vs. split primary+overflow. Behavior is specified here; visual placement resolves in design/implementation. Consider how cancel-on-blocked lives in the overflow while the primary slot is occupied by the R6 inline notice.
|
||||
- [Affects R11][Technical] Confirm the 409 error-body shape from the server so error-toast copy can use the server-provided message verbatim.
|
||||
- [Affects R7, R10][Technical] Decide the post-terminal reconciliation mechanism for archive/unarchive: reconnect SSE after terminal close, refetch on 2xx archive/unarchive response, or subscribe on a non-terminating channel. Either the per-run `/attach` contract extends or the UI uses response-driven reconciliation.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ `/ce:plan` for structured implementation planning
|
||||
|
|
@ -1,146 +0,0 @@
|
|||
---
|
||||
date: 2026-04-20
|
||||
topic: fabro-store-record-abstractions
|
||||
---
|
||||
|
||||
# Fabro-store Record Abstractions
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Adding a new persisted record type to `fabro-store` today means writing ~200–400 LOC of repetitive plumbing in a new `Slate*Store`: key construction, JSON serialization, `get`/`put`/`delete`/`scan_prefix` wrappers, optional per-key consume mutex, optional GC-by-prefix-scan, optional secondary index. The existing four record families — `RefreshToken`, `AuthCode`, `Blob`, and the Run catalog index — share most of that plumbing mechanically, but each duplicates it inside `lib/crates/fabro-store/src/slate/`. As more record types land (new auth flows, sessions, vault entries, agent state), the duplication compounds and each copy is one more place where serialization, locking, or key encoding can drift.
|
||||
|
||||
Greenfield, no production deployments — backwards compat can be broken freely.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
lib/crates/fabro-store/
|
||||
Database
|
||||
.refresh_tokens() -> Arc<RefreshTokenStore>
|
||||
.auth_codes() -> Arc<AuthCodeStore>
|
||||
.blobs() -> Arc<BlobStore>
|
||||
.catalog_index() -> Arc<RunCatalogIndex>
|
||||
.runs() -> Runs (unchanged)
|
||||
|
||||
*Store wrappers (one per Record)
|
||||
own: Repository<R> + domain helpers (KeyedMutex, ReplayCache, …)
|
||||
expose: domain-named methods (consume_and_rotate, delete_chain, …)
|
||||
|
||||
Repository<R: Record> ← reusable typed K/V layer
|
||||
get / put / delete / scan_stream / scan_prefix_stream / gc
|
||||
serializes via R::Codec
|
||||
keys built from R::PREFIX + R::Id::key_segments
|
||||
pub(crate) — wrapper Stores own it; never exposed on Database
|
||||
|
||||
trait Record / trait RecordId / trait Codec<R>
|
||||
Record::PREFIX (const)
|
||||
Record::Codec (associated type; each impl writes `type Codec = JsonCodec;`)
|
||||
Record::id(&self) (-> Self::Id)
|
||||
RecordId::key_segments(&self) -> Vec<String> (Repository assembles SlateKey)
|
||||
|
||||
transaction(&db, |tx| { tx.put(&r1)?; tx.put(&r2)?; })
|
||||
← cross-record atomic batch
|
||||
```
|
||||
|
||||
Run's event log, projection cache, broadcast channel, and per-run mutex stay in `RunDatabase` and are deliberately out of scope. The Run catalog *index* (today's `slate/catalog.rs`) is in scope and becomes `RunCatalogIndex` on top of `Repository`.
|
||||
|
||||
## Records in Scope
|
||||
|
||||
| Record | PREFIX | Id type | Codec | Special semantics |
|
||||
|------------------|-------------------------|---------------------|-----------|---------------------------------------------------------|
|
||||
| RefreshToken | `auth/refresh` | `[u8; 32]` (hex) | JsonCodec | KeyedMutex consume lock, in-memory replay revocation |
|
||||
| AuthCode | `auth/code` | `String` (opaque) | JsonCodec | KeyedMutex consume lock, single-use |
|
||||
| Blob | `blobs/sha256` | `RunBlobId` | RawBytesCodec | Immutable, content-addressed, never deleted |
|
||||
| RunCatalogEntry | `runs/_index/by-start` | `RunId` | EmptyCodec | Empty value; date segment derived from `RunId.created_at()` |
|
||||
|
||||
## Requirements
|
||||
|
||||
**Core abstraction**
|
||||
- R1. Define `trait Record: Sized + Send + Sync + 'static` with associated `type Id: RecordId`, `type Codec: Codec<Self>`, `const PREFIX: &'static str`, and `fn id(&self) -> Self::Id`. Each `impl Record` writes `type Codec = JsonCodec;` (or its override) explicitly — no associated-type default, since `associated_type_defaults` is unstable on stable Rust as of 2026. One extra line per impl is the lowest-magic alternative; the workspace doesn't have a proc-macro sub-crate today and adding one is more weight than the savings justifies. `PREFIX` is a `/`-separated path of segments (e.g. `"auth/refresh"`, `"runs/_index/by-start"`) that `Repository` splits before assembling the `\0`-separated `SlateKey`; `/` is therefore reserved inside any single segment.
|
||||
- R2. Define `trait RecordId { fn key_segments(&self) -> Vec<String>; }`. Implementations return segment data; `Repository` assembles the SlateKey internally so `SlateKey` (and its `\0`-segment-boundary invariant) stay `pub(crate)`. Built-in impls: `[u8; 32]` writes one hex segment; `String` writes itself; `RunBlobId` writes its sha256 hex segment; `RunId` writes two segments — `<YYYY-MM-DD>` derived from `RunId.created_at()` followed by the RunId string. (`RunId`-as-Record-Id is used only by `RunCatalogEntry` today; if a future record needs a single-segment RunId encoding it uses a newtype wrapper.)
|
||||
- R3. Define `trait Codec<R> { fn encode(r: &R) -> Result<Vec<u8>>; fn decode(bytes: &[u8]) -> Result<R>; }` with built-in implementations: `JsonCodec` (used by most records), `RawBytesCodec` (for `Blob`), `EmptyCodec` (for index entries with no value). `JsonCodec::encode` is implemented as a one-line literal forwarding to `serde_json::to_vec(&value)` (and `decode` to `serde_json::from_slice`); the implementation IS the proof of byte-identity. A snapshot test on a representative `RefreshToken` and `AuthCode` is kept as a regression net so any accidental change to the forwarding impl (e.g. someone adds an envelope) fails CI loudly. The snapshot files commit the on-disk wire format to the repo and are reviewed as wire-format changes when they change.
|
||||
- R4. Provide `Repository<R: Record>` exposing the typed K/V primitives: `get(&R::Id)`, `put(&R)`, `delete(&R::Id)`, `scan_stream() -> impl Stream<Item = Result<(R::Id, R)>>` (full prefix), `scan_prefix_stream(extra_segments)`, and `gc(predicate: impl Fn(&R) -> bool) -> Result<u64>` (scans, filters, deletes — replaces the three hand-rolled GC-by-prefix-scan loops in today's stores). `Repository<R>` is `pub(crate)`. The `gc` predicate is sync `Fn` (so it cannot mutate caller state across the scan), MUST NOT perform I/O or block (it runs once per scanned record), and MUST be free of side effects (gc may be called more than once on the same record set during retries or future caller logic). `gc` issues all deletes in a single `slatedb::WriteBatch` — atomic vs today's per-key delete loop, deliberate behaviour change. No capability traits, no marker subtraits — domain logic lives in the wrapper Store.
|
||||
|
||||
**Wrapper stores**
|
||||
- R5. Each record family has a named domain `*Store` type that owns a `Repository<R>` and any domain-specific helpers (per-key mutex, in-memory caches, replay revocation set). Trivial stores (`BlobStore`, `RunCatalogIndex`) are still concrete named types even when they are thin pass-throughs. **Security boundary**: `Repository<R>` is `pub(crate)`; construction is gated to the wrapper Store and to test fixtures. The `Repository` field on each wrapper Store is private (`pub(super)` at most); wrapper Stores never expose `.scan_stream()` / `.gc()` / `.repository()` accessors. `Database` exposes only the wrapper Stores, never `Repository<R>` directly. Domain methods that need a scan (e.g. `gc_expired`, `delete_chain`) perform it internally and return aggregate results, never raw records. The boundary is enforced for crate-external callers by the `pub(crate)` visibility; for crate-internal contributors it is convention + code review (a future fabro-store author who constructs `Repository<RefreshToken>` directly is bypassing the design and the PR review should catch it).
|
||||
- R6. `RefreshTokenStore` keeps its existing API (`insert_refresh_token`, `find_refresh_token`, `consume_and_rotate`, `delete_chain`, `gc_expired`, `mark_refresh_token_replay`, `was_recently_replay_revoked`). `consume_and_rotate` uses the new `transaction` helper while still holding its `KeyedMutex` guard around the call. The replay revocation set (`mark_refresh_token_replay` / `was_recently_replay_revoked`) is in-memory only with a 60s TTL — it MUST NOT be moved into `Repository<R>` or otherwise persisted. Rationale: it's a transient signal so the current process can recognize replays within the rotation window; persisting attacker-supplied token hashes adds disk I/O and a new GC surface with no security benefit and an unbounded-growth risk under token-stuffing attack.
|
||||
- R7. `AuthCodeStore` keeps its existing API (`insert`, `consume`, `gc_expired`). The `AuthCode` struct gains a `code: String` first field carrying its own key (today's struct receives the code as a separate parameter to `insert`); this lets `Record::id(&self)` return the key from the value, which `Repository::scan_stream` requires. The on-disk JSON shape gains one field — acceptable under greenfield.
|
||||
- R8. `BlobStore` exposes `read(&RunBlobId)`, `write(bytes) -> RunBlobId`, `exists(&RunBlobId)`. `delete` is intentionally not exposed — current behaviour is that blobs survive run deletion (enforced by `delete_run_keeps_global_cas_blobs` test). `RunDatabase::write_blob` / `read_blob` / `list_blobs` keep their signatures and delegate to `BlobStore` internally so existing callers (and tests) require no changes.
|
||||
- R9. `RunCatalogIndex` exposes `add(&RunId)`, `remove(&RunId)`, `list(query: &ListRunsQuery) -> Vec<RunId>`, replacing the free functions in `lib/crates/fabro-store/src/slate/catalog.rs`. `list` scans the prefix, applies `query.start`/`query.end` filtering against `run_id.created_at()`, and sorts by the same key as today's `catalog.rs:39-49` — `(year, month, day, hour, minute, run_id)` ascending — derived inside `RunCatalogIndex::list` from each `RunId`'s embedded ULID timestamp. The post-list summary-building loop in `Database::list_runs` (`slate/mod.rs:170-183`) is **not** absorbed into `RunCatalogIndex`; only the catalog scan + filter + sort move.
|
||||
|
||||
**Cross-record atomic writes**
|
||||
- R10. Provide a `transaction(&db, |tx| { … })` helper producing a single `slatedb::WriteBatch`. `Tx` exposes `put(&R)` and `delete(&R::Id)` for any `R: Record`, so a single transaction can span record types. Replaces the hand-built `slatedb::WriteBatch` in `RefreshTokenStore::consume_and_rotate`. **Atomicity invariants** (security-critical for token rotation): the closure is `FnOnce(&mut Tx) -> Result<T, Error>` (synchronous); on closure `Err`, no slatedb write occurs (codec errors short-circuit via `?`); on closure `Ok`, exactly one `slatedb::WriteBatch::write` commit is issued; no retry, no partial flush, no commit-on-drop. A fault-injection test asserts that an encode failure on the Nth `put` leaves the database unchanged. To restrict the cross-type capability to authorized callers, `transaction` is `pub(crate)` — wrapper Stores expose domain-named atomic methods (e.g. `RefreshTokenStore::consume_and_rotate`) that compose `transaction` internally.
|
||||
|
||||
**Database surface**
|
||||
- R11. `Database` exposes `refresh_tokens()`, `auth_codes()`, `blobs()`, `catalog_index()`, and `runs()`. Each lazily initializes its store via `OnceCell` and returns `Arc<*Store>` (mirrors today's pattern in `lib/crates/fabro-store/src/slate/mod.rs:208-228`).
|
||||
- R12. `RunDatabase`'s event-sourcing machinery (event log, projection cache, broadcast channel, atomic seq counter, per-run state mutex) and public method signatures are unchanged. Two internal touch-points exist: (a) the catalog call sites all live in `Database` itself — `Database::create_run` (`slate/mod.rs:119,127`), `Database::list_runs` (`slate/mod.rs:169`), and `Database::delete_run` (`slate/mod.rs:204`) — and migrate from `catalog::write_index` / `catalog::delete_index` / `catalog::list_run_ids` to the new `RunCatalogIndex` (lazily initialized on `Database` via `OnceCell`, like the other stores); (b) `RunDatabase::write_blob` / `read_blob` / `list_blobs` (`run_store.rs:283-302`) keep their public signatures and behaviour but delegate internally to `BlobStore` per R8. No callers change.
|
||||
|
||||
**Reusable helpers**
|
||||
- R13. Extract `KeyedMutex<K: Hash + Eq>` (per-key async mutex on top of `DashMap<K, Arc<Mutex<()>>>` with auto-cleanup when strong count drops to 2) as a shared helper inside `fabro-store`, used by `RefreshTokenStore` and `AuthCodeStore`. **Security purpose**: `KeyedMutex` serializes concurrent `consume` operations on the same key. Required by single-use semantics for `AuthCode` and replay detection for `RefreshToken` — without it, a TOCTOU race between the find/get and the delete/mark-used write permits double-consumption. Auto-cleanup at `strong_count == 2` bounds the map size so a high volume of distinct codes/hashes cannot grow it without limit. The cleanup check and the entry insertion happen under the same `DashMap` shard lock so a concurrent `lock(&key)` cannot observe a soon-to-be-dropped Arc and acquire a different `Mutex` instance for the same key. `KeyedMutex` exposes only `lock(&self, key: K) -> Guard<'_>` — never returns or clones the inner `Arc`; `Guard` holds the Arc internally so the strong-count==2 check happens after `Guard` drops. The lock MUST NOT be made optional, replaced with a TTL/janitor, or relocated to a separate process without explicit security review.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Adding a 5th simple K/V record type requires writing only: a struct + `impl Record` + an `impl RecordId` (if its ID type isn't already covered) + a thin `*Store` wrapper. No new key-construction code, no `serde_json::to_vec`/`from_slice` per store, no copy of get/put/delete/scan plumbing.
|
||||
- All existing public store APIs (`RefreshTokenStore::consume_and_rotate`, `AuthCodeStore::consume`, etc.) keep their signatures and observable behaviour. Existing unit and integration tests pass without modification.
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs` and `auth_codes.rs` shrink to roughly their domain logic (consume lock, GC traversal, replay cache) — kv plumbing moves into `Repository`.
|
||||
- `lib/crates/fabro-store/src/slate/catalog.rs` is deleted; `RunCatalogIndex` exposes the same operations through `Repository<RunCatalogEntry>`.
|
||||
- A single `transaction(…)` call replaces the hand-built `slatedb::WriteBatch` in `RefreshTokenStore::consume_and_rotate`.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Run aggregate's event-sourcing machinery (`RunDatabase` event log, projection cache, broadcast channel, `recover_next_seq`, `EventProjectionCache`, atomic seq counter) is not refactored. `RunDatabase`'s blob methods are touched only to delegate to `BlobStore` per R8 — no signature or behaviour change.
|
||||
- No marker capability traits (`ExpiringRecord`, `ConsumableRecord`, `IndexedRecord`, `ContentAddressed`). Capabilities are hand-written per `*Store`.
|
||||
- No record schema versioning or migration framework. Greenfield, can break compat.
|
||||
- No swap-out of the storage backend (still SlateDB on `Arc<dyn ObjectStore>`). Repository is parameterized by `R`, not by storage.
|
||||
- No changes to `ArtifactStore` or other non-SlateDB storage.
|
||||
- No changes to the public `Database::create_run` / `open_run` / `delete_run` / `list_runs` API signatures or observable behaviour. Internal implementations of `create_run`, `list_runs`, and `delete_run` consume the new `RunCatalogIndex` per R12.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Two worlds** (Run separate from simple K/V records): unifying an event-sourced aggregate (atomic seq counter, projection cache, live broadcast, per-run state mutex) with single-key records would either flatten to a lowest-common-denominator API or force Run's complexity onto records that don't need it.
|
||||
- **Hand-written `*Store` wrappers on a thin `Repository`** (not marker capability traits): chose lowest magic. Capability variations are small in number, infrequently added, and easy to read inline. A reader of `RefreshTokenStore` should see exactly what `consume_and_rotate` does without crossing trait-bound boundaries.
|
||||
- **Multi-segment IDs via data-only `key_segments() -> Vec<String>`**: `SlateKey` stays `pub(crate)`. `Repository` assembles the key internally — `RecordId` impls cannot violate the `\0`-segment-boundary invariant by accident. Small allocation per key derivation is acceptable for the encapsulation gain.
|
||||
- **Codec specified explicitly per impl** (no associated-type default): `associated_type_defaults` is unstable on stable Rust as of 2026. Rather than wait, pull in a derive-macro sub-crate, or split into sub-traits, every `impl Record` writes `type Codec = JsonCodec;` (or its override). One extra line per impl, no nightly, no proc-macro infra.
|
||||
- **`transaction(...)` as a single-batch atomic primitive, `pub(crate)`**: `consume_and_rotate` already needs an atomic two-key write; one helper covers it and any future cross-record flows. Closure is `FnOnce`, all-or-nothing, no commit-on-drop. Crate-private visibility prevents callers from bypassing per-store invariants — wrapper Stores expose domain-named atomic methods that compose `transaction` internally.
|
||||
- **Repository for security-sensitive records is store-private**: `Database` exposes only wrapper Stores. `RefreshTokenStore` and `AuthCodeStore` never hand out a `Repository` accessor or generic `scan`. Prevents a new caller in `fabro-server` (or anywhere else) from walking the entire token table.
|
||||
- **Named `*Store` for every record**: discoverability matters more than line count. `db.blobs()` and `db.catalog_index()` read more clearly than `db.repository::<Blob>()`. The trivial wrappers (`BlobStore`, `RunCatalogIndex`) are accepted overhead — see Alternatives Considered for the leaner shape we rejected.
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
Three lighter shapes were considered. The full scaffold (R1–R13) was chosen anyway. Comparison:
|
||||
|
||||
| Option | New types | Approx. scaffold | Per-record cost (5th) | Trade |
|
||||
|---|---|---|---|---|
|
||||
| (1) Copy-paste-and-rename | 0 | 0 LOC | ~200 LOC duplicated | Zero abstraction tax now; drift risk grows linearly. |
|
||||
| (2) `JsonStore<T>` helper only | 1 (~30 LOC) | ~30 LOC | ~80 LOC | Removes JSON serde duplication only. No typed key, no codec abstraction, no transaction helper, no security boundary. Each store keeps bespoke key construction and consume locks. |
|
||||
| (3) Minimum-viable subset (R1+R2+R3 JsonCodec only+R4+R6+R7+R13) | ~5 traits + Repository + KeyedMutex | ~120 LOC | ~30 LOC | Touches only `auth_tokens.rs` and `auth_codes.rs`. Drops `BlobStore`, `RunCatalogIndex`, cross-record `transaction`, `RawBytesCodec`, `EmptyCodec`. Loses the boundary requirement (no Blob/catalog pass-through to demonstrate the pattern). |
|
||||
| **(chosen) Full scaffold (R1–R13)** | ~6 traits + Repository + Tx + 4 wrapper stores + KeyedMutex | ~250 LOC | ~30 LOC | All of (3) plus Blob CAS and catalog refactor onto the same shape. R8 (`BlobStore` as a public Database surface) and R9 (catalog migration) are forward-looking in their *value* — they don't have a new today-consumer beyond what already works through `RunDatabase::write_blob` and `catalog::*` — but they are concrete refactors of existing code, not speculative new code. R10's cross-type Tx is similarly forward-looking. |
|
||||
|
||||
**Why (chosen) over (3)**: standardizes the shape across every K/V record the crate has, so new entrants (sessions, vault, agent state) hit one well-understood pattern instead of choosing between "use `Repository`" and "use the older bespoke style." Designs the security boundary (R5) once for the whole crate so a future security-sensitive record inherits the discipline by default rather than reinventing it. (Note: only `RefreshToken` and `AuthCode` actually need the boundary today; for `Blob` and `RunCatalogEntry` the boundary is "free" — there's nothing sensitive to protect — so the security argument is forward-leaning, not load-bearing right now.)
|
||||
|
||||
**Why not (2) `JsonStore<T>`**: removes the JSON duplication but nothing else. Each store still hand-writes its own key construction (so the scan/key-parsing invariants stay scattered), its own consume mutex (so KeyedMutex can't naturally land), and its own atomic-write batch (so the security invariants in R10 stay implicit). Reduction in scaffolding is real, reduction in surface-to-think-about is much smaller than it looks.
|
||||
|
||||
**Why not (1) copy-paste**: works fine until two records drift. The first such drift (e.g., one store fixes a key-encoding bug another doesn't) is a class of bug the abstraction prevents structurally.
|
||||
|
||||
**Acknowledged speculative scope**: R8 (`BlobStore` public surface), R9 (catalog sweep), and R10's cross-type Tx are all forward-looking. The bet is that paying the setup cost once now is cheaper than retrofitting later. If that bet is wrong, the cost is the LOC delta between (3) and (chosen) plus the ongoing readability cost: a new contributor must learn `Record`/`RecordId`/`Codec`/`Repository`/`Tx`/`KeyedMutex` to add a record, vs. learning one `JsonStore<T>` API; trait-resolution makes "where is this key constructed?" harder to grep; generic error messages reference `<RefreshToken as Record>::Codec` instead of `JsonCodec`. The per-record LOC numbers in the table above are rough estimates — the actual delta between (2)/(3) and (chosen) for a 5th record is small (single-digit LOC). The primary argument for (chosen) over (3) is consistency-across-records and one-time security-boundary design, not per-record LOC.
|
||||
|
||||
## Dependencies / Assumptions
|
||||
|
||||
- SlateDB's `WriteBatch` is suitable as the underlying primitive for the `transaction` helper. Already used by `RefreshTokenStore::consume_and_rotate`.
|
||||
- The current public consumers of `Database::auth_codes()` / `auth_tokens()` are limited to `fabro-server` and crate-internal tests. The `Slate*Store` type names are referenced in `fabro-server` (`serve.rs:799-829` types `Arc<fabro_store::SlateAuthCodeStore>` etc.); renaming to `*Store` is a mechanical import update on the order of one PR for `fabro-server`, not a deep API change.
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
|
||||
(none)
|
||||
|
||||
### Deferred to Planning
|
||||
|
||||
- [Affects R13] [Technical] Whether `KeyedMutex` lives at `lib/crates/fabro-store/src/keyed_mutex.rs` or in a small shared util module. Either is fine.
|
||||
- [Affects R5–R9] [Technical] Migration order — which store moves to `Repository` first and in what PR sequence. Suggested order: R13 (`KeyedMutex` extraction, can land first as a precursor PR) → `BlobStore` (greenfield, simplest) → `RunCatalogIndex` (replaces `catalog.rs`) → `AuthCodeStore` → `RefreshTokenStore` (most complex due to consume-and-rotate + replay cache). Planning concern.
|
||||
- [Affects R10] [Technical] Whether to add a separate `per_repository_batch` helper for the common single-type case so callers don't pay the cross-record machinery cost when they don't need it. Performance/ergonomics tweak, not a correctness question.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ `/ce:plan` for structured implementation planning
|
||||
|
|
@ -1,95 +0,0 @@
|
|||
---
|
||||
date: 2026-04-22
|
||||
topic: web-install-object-store-choice
|
||||
---
|
||||
|
||||
# Web Install Object Store Choice
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The browser install wizard currently configures server URL, LLM credentials, and GitHub integration, but it does not let the operator choose where Fabro's object-store-backed data lives. Fabro already supports a local object store and AWS S3 in server configuration, and the runtime model keeps a separate local storage root for host-local state. The missing product behavior is a guided first-run choice for the shared object store used by both SlateDB and artifacts.
|
||||
|
||||
Without this step, operators who want S3-backed storage must finish install and then hand-edit server configuration and startup secrets. That creates avoidable setup drift between "works locally" and "production-like" deployments, especially for remote-first installs where the web wizard is supposed to be the primary setup path.
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A[Welcome]
|
||||
B[Server]
|
||||
C[Object store]
|
||||
D[LLM]
|
||||
E[GitHub]
|
||||
F[Review]
|
||||
G[Finish]
|
||||
|
||||
A --> B --> C --> D --> E --> F --> G
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
**Wizard flow**
|
||||
- R1. The web install wizard must add a new `Object store` step after `Server` and before `LLM`, making the operator-visible order `Welcome → Server → Object store → LLM → GitHub → Review`.
|
||||
- R2. The sidebar/progress UI, route flow, back/next behavior, and review screen must treat `Object store` as a first-class step, with refresh/re-entry behavior matching the existing install steps.
|
||||
- R3. The wizard must explain that Fabro always keeps a local storage directory on the host and that this step chooses only the shared object store for object-store-backed server data.
|
||||
|
||||
**Storage modes**
|
||||
- R4. The `Object store` step must offer exactly two wizard-managed modes: `Local disk` and `AWS S3`.
|
||||
- R5. Choosing `Local disk` must configure both `server.slatedb` and `server.artifacts` to use the local object store provider.
|
||||
- R6. Choosing `Local disk` must not prompt for S3-only fields such as bucket, region, or AWS credentials.
|
||||
- R7. Choosing `AWS S3` must configure both `server.slatedb` and `server.artifacts` to use AWS S3, with one shared bucket and separate fixed prefixes so SlateDB data lives under `slatedb/` and artifact data lives under `artifacts/`.
|
||||
- R8. The wizard must not expose separate object-store choices for SlateDB and artifacts. Operators who need split backends or more advanced layouts must configure them manually after install.
|
||||
- R9. The wizard must not expose S3-compatible endpoint or path-style options in v1. The step must clearly note that non-AWS S3-compatible backends are out of scope for the wizard and require manual configuration.
|
||||
|
||||
**S3 fields and credentials**
|
||||
- R10. When `AWS S3` is selected, the wizard must collect `bucket` and `region`.
|
||||
- R11. The `AWS S3` path must offer exactly two credential modes: `Use AWS runtime credentials` and `Enter AWS access key credentials`.
|
||||
- R12. `Use AWS runtime credentials` must be described as the path for deployments where AWS credentials come from the runtime environment or attached role, and it must not prompt for AWS secret material.
|
||||
- R13. `Enter AWS access key credentials` must prompt only for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
|
||||
- R14. Manual AWS access-key credentials are server-only startup secrets. They must be persisted as server startup env secrets, not as workflow-visible vault secrets.
|
||||
- R15. The wizard must not support session-token or STS inputs in v1. Operators who need temporary-session credential flows must configure object-store access manually outside the wizard.
|
||||
|
||||
**Validation and review**
|
||||
- R16. The `AWS S3` path must perform live validation before the operator can continue past the `Object store` step.
|
||||
- R17. Live validation must confirm that the configured bucket, region, chosen credential mode, and fixed `slatedb/` / `artifacts/` prefixes permit Fabro to reach the target S3 bucket with the intended object-store setup.
|
||||
- R18. Validation errors must render inline on the `Object store` step and make it clear whether the failure is due to bucket/region mismatch, missing runtime credentials, or invalid manually-entered credentials when that distinction is available.
|
||||
- R19. The review step must summarize the chosen object-store mode. For S3, it must show the bucket, region, credential mode, and that Fabro will use the fixed `slatedb/` and `artifacts/` prefixes in the shared bucket without revealing secret values.
|
||||
|
||||
## Success Criteria
|
||||
- Operators can complete first-run setup for either local object storage or AWS S3 without editing `settings.toml` by hand.
|
||||
- An install completed with `Local disk` produces the expected local-provider config for both SlateDB and artifacts.
|
||||
- An install completed with `AWS S3` produces the expected shared-bucket S3 config for both SlateDB and artifacts, with `slatedb/` and `artifacts/` prefixes.
|
||||
- Manual AWS credentials, when provided, are stored only as server startup secrets and are not exposed in workflow-visible secret surfaces.
|
||||
- Misconfigured S3 details are caught during the install wizard instead of surfacing only after install completes and the server restarts.
|
||||
|
||||
## Scope Boundaries
|
||||
- The local host storage root remains separate and is not replaced by S3.
|
||||
- The wizard does not support separate object-store backends for SlateDB and artifacts.
|
||||
- The wizard does not support non-AWS S3-compatible backends.
|
||||
- The wizard does not support session-token or STS credential inputs.
|
||||
- Advanced object-store layouts, custom prefixes beyond the fixed `slatedb/` and `artifacts/`, and other specialized storage topologies remain manual-configuration workflows.
|
||||
|
||||
## Key Decisions
|
||||
- One shared object-store choice for both SlateDB and artifacts: keeps the wizard simple and avoids first-run misconfiguration.
|
||||
- AWS S3 only in the wizard: reduces surface area and avoids exposing endpoint/path-style details meant for manual advanced setups.
|
||||
- Two S3 auth paths: ambient runtime credentials for AWS-native deployments, or manually-entered access keys for non-AWS deployments that still target S3.
|
||||
- Live validation on the wizard step: catches storage errors before the install succeeds and the server exits.
|
||||
- `Object store` comes before provider/integration setup: keeps server-level infrastructure decisions together near the server URL step.
|
||||
|
||||
## Dependencies / Assumptions
|
||||
- The existing server config model continues to treat `server.storage.root` as host-local storage and `server.slatedb` / `server.artifacts` as separate object-store-backed domains.
|
||||
- The runtime continues to initialize S3 access from startup environment credentials or the ambient AWS credential chain.
|
||||
- Using one shared S3 bucket with distinct `slatedb/` and `artifacts/` prefixes is sufficient for the wizard-managed path.
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
|
||||
(none)
|
||||
|
||||
### Deferred to Planning
|
||||
- [Affects R16-R18] [Technical] Define the exact validation probe shape for local vs S3 so the install flow checks the real runtime path without creating misleading side effects in the bucket.
|
||||
- [Affects R14] [Technical] Confirm the exact persistence path and lifecycle for manual AWS credentials in `server.env`, including whether existing install rollback behavior is sufficient for newly-added AWS env keys.
|
||||
- [Affects R19] [Technical] Decide how the review screen and session payload represent the credential mode without leaking secret values and while preserving edit/re-entry behavior.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ `/prompts:ce-plan` for structured implementation planning
|
||||
|
|
@ -1,107 +0,0 @@
|
|||
---
|
||||
date: 2026-04-25
|
||||
topic: cargo-dev-ux-cleanup
|
||||
---
|
||||
|
||||
# `cargo dev` UX Cleanup
|
||||
|
||||
## Problem Frame
|
||||
|
||||
`cargo dev` was created in April 2026 to consolidate five shell scripts into one Rust binary, modeled after `uv`'s ergonomics. Six commands shipped:
|
||||
|
||||
`docker-build`, `refresh-spa`, `check-spa-budgets`, `generate-cli-reference`, `generate-options-reference`, `release`.
|
||||
|
||||
A few rough edges have surfaced now that the surface is in regular use by humans, agents, and CI:
|
||||
|
||||
- `refresh-spa` is mandatory before any TypeScript commit, but CI enforces it via a separate `git diff --exit-code` step rather than a first-class check mode. The dirty-check lives in CI YAML, not in the dev tool.
|
||||
- `check-spa-budgets` is a sibling command instead of part of the same SPA verification pass, so contributors need to remember two commands to "verify the SPA is shippable."
|
||||
- Word order is mixed — `docker-build` is noun-verb, `refresh-spa` and `check-spa-budgets` are verb-noun, the two `generate-*-reference` commands are verb-noun-noun. There is no rule a contributor can apply to guess a command name.
|
||||
- `release [nightly]` uses a positional with a single accepted value (`nightly`), reading awkwardly compared with `--nightly`.
|
||||
|
||||
This brainstorm captures the rename + consolidation pass to fix word order, fold SPA verification into one command, and switch the release prerelease to a flag.
|
||||
|
||||
## Surface Comparison
|
||||
|
||||
| Today | After |
|
||||
|---|---|
|
||||
| `cargo dev docker-build` | `cargo dev docker-build` (unchanged) |
|
||||
| `cargo dev refresh-spa` | `cargo dev spa refresh` |
|
||||
| `cargo dev check-spa-budgets` + CI `git diff --exit-code` | `cargo dev spa check` (folds both) |
|
||||
| `cargo dev generate-cli-reference` | `cargo dev docs refresh` (regenerates both artifacts) |
|
||||
| `cargo dev generate-cli-reference --check` | `cargo dev docs check` (verifies both artifacts) |
|
||||
| `cargo dev generate-options-reference` | `cargo dev docs refresh` |
|
||||
| `cargo dev generate-options-reference --check` | `cargo dev docs check` |
|
||||
| `cargo dev release` | `cargo dev release` (unchanged) |
|
||||
| `cargo dev release nightly` | `cargo dev release --nightly` |
|
||||
| — | `cargo dev spa` prints SPA command help |
|
||||
| — | `cargo dev docs` prints docs command help |
|
||||
|
||||
## Requirements
|
||||
|
||||
### Naming convention
|
||||
|
||||
- R1. Adopt noun-verb word order (uv style): the group/subject comes first, the action second. `docker-build` is grandfathered as a single hyphenated noun-verb name because it has no siblings; `release` stays as a single verb because it has no group.
|
||||
- R2. Group-only invocation is non-mutating help: `cargo dev spa` prints the SPA subcommand help and exits successfully; `cargo dev docs` prints the docs subcommand help and exits successfully. Mutating commands always require an explicit verb (`refresh`).
|
||||
|
||||
### SPA group
|
||||
|
||||
- R3. `cargo dev spa refresh` rebuilds the SPA via `bun run build`, verifies the built `dist/` output against the asset budget gate, and only then replaces `lib/crates/fabro-spa/assets/`. On budget violation, it exits non-zero and leaves the committed asset directory untouched. This extends today's `refresh-spa` behavior with the budget gate so contributors can't ship an oversized bundle by accident without creating a dirty tracked tree on failed refresh.
|
||||
- R4. `cargo dev spa check` is non-mutating with respect to tracked files: it must not rewrite `lib/crates/fabro-spa/assets/`, and it must leave the tracked working tree unchanged whether it passes or fails. It may use ignored temporary output, but it must clean up any temporary directory it creates. It must fail (non-zero exit) when **either** (a) the SPA bundle in `lib/crates/fabro-spa/assets/` does not match what `bun run build` would produce now (given the current `bun.lock` and source tree), **or** (b) the bundle exceeds asset budgets. This subsumes both today's `check-spa-budgets` and the CI `git diff --exit-code -- lib/crates/fabro-spa/assets` step. The bit-exact comparison relies on `bun run build` being reproducible from a frozen lockfile; CI is the authoritative environment because `bun install --frozen-lockfile` runs there. If a contributor sees a `spa check` failure locally that they can't explain, the resolution is to run `cargo dev spa refresh` and commit the result — CI's `spa check` then arbitrates.
|
||||
- R5. Both `.github/workflows/typescript.yml` (Build job) and `.github/workflows/release.yml` (`verify-spa` job, lines 29–31) call `cargo dev spa check` instead of `cargo dev refresh-spa` + `git diff --exit-code -- lib/crates/fabro-spa/assets`. The dirty-check no longer lives in workflow YAML. Both CI workflows must run `bun install --frozen-lockfile` before `cargo dev spa check`; this preserves the TypeScript workflow's existing setup and tightens the release workflow, which currently uses plain `bun install`.
|
||||
|
||||
### Docs group
|
||||
|
||||
- R6. `cargo dev docs refresh` regenerates both `docs/reference/cli.mdx` and `docs/reference/user-configuration.mdx` in one pass. Replaces the two `generate-*-reference` commands' default mode.
|
||||
- R7. `cargo dev docs check` verifies both MDX artifacts are up to date without rewriting them. Replaces the two commands' `--check` mode. Non-zero exit on drift in either file.
|
||||
|
||||
### Release
|
||||
|
||||
- R8. `cargo dev release` cuts a stable release; `cargo dev release --nightly` cuts a nightly prerelease. The `[nightly]` positional is removed. Other release-mode flags (`--dry-run`, `--skip-tests`, `--release-date`) are unchanged.
|
||||
|
||||
### Migration
|
||||
|
||||
- R9. Hard cut: the old names (`refresh-spa`, `check-spa-budgets`, `generate-cli-reference`, `generate-options-reference`, `release nightly` positional) are removed in the same PR. No deprecated aliases.
|
||||
- R10. All in-repo callers update in the same PR. Scope explicitly includes:
|
||||
- CI workflows under `.github/workflows/` (including `nightly.yml`'s `cargo dev release nightly` invocation and `release.yml`'s `verify-spa` job).
|
||||
- `AGENTS.md` (including its release-mode usage line that shows `[nightly]`) and `CLAUDE.md`.
|
||||
- Any live `docs/` references that show the user-facing command (historical artifacts under `docs/plans/` and `docs/brainstorms/` are left alone).
|
||||
- The `lib/crates/fabro-dev/` source crate itself: the subprocess invocation in `src/commands/release.rs` (currently `cargo dev refresh-spa`), `bail!` and help strings inside `src/commands/*.rs` that name the old commands, and integration tests under `tests/it/` that invoke subcommands by name. These must rename in lockstep with the clap subcommand declarations or `cargo nextest run -p fabro-dev` will fail.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- `cargo dev --help` lists `docker-build`, `spa`, `docs`, `release` (four entries) with consistent noun-verb naming.
|
||||
- A contributor can answer "how do I verify the SPA before pushing?" with one command (`cargo dev spa check`) instead of two plus a `git diff`.
|
||||
- CI's TypeScript Build job, the release pipeline's `verify-spa` job, and the docs-reference checks each call exactly one `cargo dev <group> check` command; the workflow YAML no longer contains a `git diff --exit-code` line for SPA assets, and both SPA-checking workflows use `bun install --frozen-lockfile`.
|
||||
- `rg "refresh-spa|check-spa-budgets|generate-cli-reference|generate-options-reference|release nightly|release \\[nightly\\]" .github CLAUDE.md AGENTS.md docs/ lib/crates/fabro-dev/ -g '!docs/plans/**' -g '!docs/brainstorms/**'` returns no live references after the PR merges. Historical matches inside `docs/plans/` and `docs/brainstorms/` are acceptable.
|
||||
- `cargo nextest run -p fabro-dev` passes after the rename, and no `bail!` or help text inside `lib/crates/fabro-dev/src/` references the removed command names.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Out of scope: `cargo dev verify` aggregate command, `cargo dev doctor` environment check, `--json` output for agents, `--watch` mode for `spa refresh`, pre-commit hook installation. These were considered and deferred — worth a separate brainstorm if footgun-reduction proves still painful after this cleanup.
|
||||
- Out of scope: any change to what `docker-build` does or its flag surface.
|
||||
- Out of scope: extending the release prerelease vocabulary beyond `nightly` (`--prerelease <kind>` style). The single `--nightly` flag is enough for the current need; switch to `--prerelease` if/when a second prerelease kind is introduced.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **Noun-verb word order** (uv style) wins over verb-noun (cargo style). Rationale: `cargo dev` was already modeled after `uv` per docs/plans/2026-04-24-001-refactor-adopt-uv-patterns-plan.md, and the user picked `spa refresh` directly.
|
||||
- **One docs command pair, not per-artifact.** `docs refresh` regenerates both MDX files; `docs check` verifies both. Rationale: both regenerations are fast and idempotent, granular targeting has no real use case, and the simpler pair mirrors `spa refresh` / `spa check`.
|
||||
- **`spa check` owns both the diff and the budget gate.** Rationale: contributors think of "is the SPA ready to ship?" as one question; splitting it across two commands and a CI YAML step is what produced today's friction.
|
||||
- **Group-only commands are help-only.** Rationale: `cargo dev spa` and `cargo dev docs` are easy commands for humans and agents to discover; making them mutate the working tree by default is too easy to trigger accidentally. Explicit verbs keep the command surface predictable.
|
||||
- **`spa refresh` also enforces the budget gate before replacing committed assets.** Rationale: a successful refresh that quietly produces an over-budget bundle is a footgun, but a failed refresh should not leave tracked assets dirty. Validate the built output first, then mirror it into `lib/crates/fabro-spa/assets/` only on success.
|
||||
- **`spa check`'s bit-exact comparison relies on `bun install --frozen-lockfile`.** Rationale: CI is the authoritative environment because both SPA-checking workflows run `bun install --frozen-lockfile` before `spa check`; locally, contributors run `spa refresh` to make their working tree match what their bun produces, then trust CI's `spa check` to arbitrate cross-machine drift.
|
||||
- **Hard cut, no deprecated aliases.** Rationale: the tool is internal-only with all callers in this repo; the user's standing preference is "simplest change, don't care about migration."
|
||||
|
||||
## Outstanding Questions
|
||||
|
||||
### Resolve Before Planning
|
||||
|
||||
(none)
|
||||
|
||||
### Deferred to Planning
|
||||
|
||||
- [Affects R4][Technical] Implementation strategy for `spa check`'s diff: build into a temporary output directory and compare it against `lib/crates/fabro-spa/assets/`, or rebuild `apps/fabro-web/dist/` and clean it up after comparison. Whichever path is chosen must leave tracked files untouched and must not require a clean working tree outside `lib/crates/fabro-spa/assets/`.
|
||||
- [Affects R10][Needs research] Confirm the explicit caller list is exhaustive via `rg "refresh-spa|check-spa-budgets|generate-cli-reference|generate-options-reference|release nightly|release \\[nightly\\]" . -g '!target/**' -g '!docs/plans/**' -g '!docs/brainstorms/**'` immediately before merging.
|
||||
|
||||
## Next Steps
|
||||
|
||||
→ `/ce:plan` for structured implementation planning
|
||||
|
|
@ -1,98 +0,0 @@
|
|||
# Specification: Increase Maximum Zoom for Left-to-Right Graph View
|
||||
|
||||
## Intent Description
|
||||
|
||||
Users working with workflow graphs in the left-to-right (LR) orientation currently experience a maximum zoom limit of 200%, which is insufficient for detailed inspection of complex graphs. The top-down (TB) orientation uses the same 200% limit, but the different aspect ratio and layout of TB graphs makes this limit feel more generous in practice. LR graphs, being horizontally oriented, often require higher magnification to read node labels and inspect edges comfortably.
|
||||
|
||||
This change increases the maximum zoom ceiling for the LR graph direction to provide parity in perceived usability between the two orientations. The goal is to allow users to zoom in further when viewing LR graphs while maintaining the existing zoom behavior for TB graphs. Additionally, to improve the user experience when switching between orientations, zoom levels are now persisted separately for each direction — when you switch from TB to LR and back, your previous zoom level for each mode is restored.
|
||||
|
||||
## Architecture Specification
|
||||
|
||||
### Affected Components
|
||||
|
||||
**`apps/fabro-web/app/lib/graph-viewport.ts`**
|
||||
- Replace the single `GRAPH_MAX_ZOOM` constant (currently 200) with direction-aware zoom limits
|
||||
- Export two constants: `GRAPH_MAX_ZOOM_TB = 200` and `GRAPH_MAX_ZOOM_LR = 400` (2x increase from 200%)
|
||||
- Update `clampZoom()` to accept an optional direction parameter and apply the appropriate max limit
|
||||
- Maintain backward compatibility: when direction is not specified, use the TB limit as the default
|
||||
|
||||
**`apps/fabro-web/app/routes/run-overview.tsx`**
|
||||
- Thread the active direction (`activeDirection: "LR" | "TB"`) to `clampZoom()` calls
|
||||
- Relevant call sites: `fitToWindow()` callback and zoom interactions via `zoomAtPoint()`
|
||||
- Pass direction to `zoomAtPoint()` so it can forward it to `clampZoom()`
|
||||
- Hold a separate remembered view per direction via `useRememberedGraphView`, keyed `<runId>-TB` and `<runId>-LR`
|
||||
- Restore the appropriate zoom level when switching between TB and LR orientations
|
||||
|
||||
**`apps/fabro-web/app/components/graph-toolbar.tsx`**
|
||||
- Update zoom button disabled state to use direction-aware max zoom
|
||||
- Import both `GRAPH_MAX_ZOOM_TB` and `GRAPH_MAX_ZOOM_LR`
|
||||
- Receive `direction` prop and check against the appropriate constant
|
||||
|
||||
**`apps/fabro-web/app/lib/graph-viewport.test.ts`**
|
||||
- Update test assertions that reference `GRAPH_MAX_ZOOM` to test both TB and LR limits
|
||||
- Add test coverage for direction-aware clamping behavior
|
||||
|
||||
### Type Signature Changes
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
export const clampZoom = (zoom: number): number
|
||||
|
||||
// After
|
||||
export const clampZoom = (zoom: number, direction?: "LR" | "TB"): number
|
||||
```
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
export function zoomAtPoint(
|
||||
view: GraphView,
|
||||
factor: number,
|
||||
cursor?: { x: number; y: number },
|
||||
): GraphView
|
||||
|
||||
// After
|
||||
export function zoomAtPoint(
|
||||
view: GraphView,
|
||||
factor: number,
|
||||
cursor?: { x: number; y: number },
|
||||
direction?: "LR" | "TB",
|
||||
): GraphView
|
||||
```
|
||||
|
||||
### Constraints
|
||||
|
||||
- **Backward compatibility**: `clampZoom()` and `zoomAtPoint()` must remain callable without the direction parameter for existing call sites outside the run overview route
|
||||
- **Single source of truth**: Zoom limits must be defined as exported constants in `graph-viewport.ts`, not duplicated in component files
|
||||
- **No change to TB behavior**: The TB max zoom remains 200%
|
||||
- **Minimum zoom unchanged**: `GRAPH_MIN_ZOOM` remains 25% for both directions
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. **LR zoom ceiling increased**: When viewing a workflow graph in LR orientation, the user can zoom in to 400% (up from 200%) using toolbar buttons, scroll wheel, or trackpad pinch gestures
|
||||
2. **TB zoom ceiling unchanged**: When viewing a workflow graph in TB orientation, the maximum zoom remains 200%
|
||||
3. **Toolbar button state**: The zoom-in button is disabled when at the direction-specific maximum (LR or TB), and the zoom-out button is disabled at 25% for both directions
|
||||
4. **Fit-to-window respects limits**: The "Fit to window" button clamps the computed zoom to the direction-specific maximum when appropriate
|
||||
5. **Zoom persistence per direction**: When switching from TB to LR (or vice versa), the zoom level you previously used for that direction is restored — each direction remembers its own zoom level independently
|
||||
6. **Tests pass**: All existing `graph-viewport.test.ts` tests pass, and new tests verify direction-aware clamping behavior
|
||||
|
||||
## Ambiguity Log
|
||||
|
||||
| Decision | Classification | Resolved By | Rationale / Answer |
|
||||
|----------|----------------|-------------|-------------------|
|
||||
| What should the new LR maximum zoom be? | requires-stakeholder-input | human | Initially set to 300% (1.5x), but feedback requested increasing it to 400% (2x) for better usability with complex LR graphs. Updated to 400% based on user testing. |
|
||||
| Should the zoom limit change be retroactive to existing remembered zoom states? | inferable | Spec author | When a user switches from TB to LR, their remembered zoom state for that run is already stored. Each direction now maintains its own zoom level in a ref, so switching between TB and LR preserves the zoom you used for each mode. The `clampZoom` behavior ensures each direction's zoom stays within its max limit. |
|
||||
| Should the minimum zoom (25%) also be direction-aware? | inferable | Spec author | The user request specifically mentions "higher zoom in the overview graph in the left-to-right version" and compares max zoom between orientations. The minimum zoom was not mentioned as a problem. Changing the minimum would be scope creep. Keep `GRAPH_MIN_ZOOM` uniform at 25%. |
|
||||
| Should the constants be named `GRAPH_MAX_ZOOM_TB` / `GRAPH_MAX_ZOOM_LR` or use a different naming convention? | inferable | Spec author | The existing constant is `GRAPH_MAX_ZOOM`. The direction-aware version should maintain lexical proximity and clarity. Suffix-based naming (`_TB`, `_LR`) follows the existing `Direction` type values and makes import/usage clear in components. Alternative approaches (e.g., a `MAX_ZOOM_BY_DIRECTION` map) add indirection without benefit. |
|
||||
| Should `zoomAtPoint()` accept direction as a parameter or should callers pre-clamp? | inferable | Spec author | `zoomAtPoint()` internally calls `clampZoom()` at line 45. If direction-aware clamping is needed, threading direction through `zoomAtPoint()` avoids forcing every caller to manually clamp before calling. This centralizes the clamping logic and matches the existing function's responsibility. Pre-clamping at call sites would scatter the logic and risk inconsistency. |
|
||||
| What happens to the playground canvas zoom (mentioned in graph-viewport.ts comments)? | inferable | Spec author | The comment at line 5-7 of `graph-viewport.ts` notes the playground canvas has its own pan/zoom with discrete steps and could import this module for cursor-anchored zoom. The playground is not mentioned in the user request. The change should not affect the playground unless it explicitly imports and uses the new direction-aware `clampZoom()`. Since it currently uses discrete steps (not the percentage-based system), it remains unaffected. |
|
||||
|
||||
---
|
||||
|
||||
## Cross-Artifact Consistency Gate
|
||||
|
||||
- [ ] Intent is unambiguous — two developers would interpret it the same way.
|
||||
- [ ] Every behavior/goal in the intent maps to at least one acceptance criterion.
|
||||
- [ ] Architecture constrains implementation without over-engineering.
|
||||
- [ ] Same concepts named consistently across all three artifacts.
|
||||
- [ ] No artifact contradicts another.
|
||||
- [ ] Every gap/ambiguity finding is logged — inferable with rationale, or resolved by the human.
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
---
|
||||
date: 2026-04-02
|
||||
topic: slatedb-consolidation
|
||||
focus: Consolidate SlateDB from one-per-run to single instance owned by fabro server, all access via HTTP/Unix socket
|
||||
---
|
||||
|
||||
# Ideation: SlateDB Consolidation Behind Server
|
||||
|
||||
## Codebase Context
|
||||
|
||||
**Project shape:** Rust workspace (30 crates) + React 19 frontend. AI-powered workflow orchestration platform.
|
||||
|
||||
**Current storage architecture:**
|
||||
- `fabro-store` crate defines `Store` and `RunStore` async traits with `SlateStore` and `InMemoryStore` impls
|
||||
- Each workflow run gets its own SlateDB database (unique `db_prefix` per run)
|
||||
- `SlateRunDb` enum distinguishes Writer (`slatedb::Db`) and Reader (`DbReader`)
|
||||
- CLI opens SlateDB directly via `build_store()` (~25 call sites)
|
||||
- Server also opens SlateDB directly
|
||||
- Unix socket binding and server daemon management already implemented
|
||||
|
||||
**Key constraints:**
|
||||
- SlateDB chosen for "bottomless" S3 storage path — not replaceable with SQLite
|
||||
- Greenfield app, not yet deployed — no migration concerns
|
||||
- Events-as-source-of-truth migration actively in progress
|
||||
- Moving away from SQLite dependency, not toward it
|
||||
|
||||
## Ranked Ideas
|
||||
|
||||
### 1. Events-First Server Architecture
|
||||
**Description:** Make events the sole write path. CLI POSTs events to the server, server materializes all state (run record, node outcomes, checkpoints, etc.) from events via projection. SSE pushes events to subscribers instantly. The Writer/Reader distinction is eliminated. The API is coarser-grained REST shaped by domain needs (POST /runs/{id}/events, GET /runs/{id}/state, GET /runs/{id}/events?stream SSE) — not a 1:1 mirror of the 40-method RunStore trait.
|
||||
**Rationale:** Collapses 40 put methods to a single append endpoint. Converges with the events-as-source-of-truth work already in progress. Makes SSE push, Writer/Reader elimination, trait flattening, and in-memory projection all fall out as natural consequences. Both critics called this "the plan."
|
||||
**Downsides:** Requires events-as-source-of-truth to be complete enough that all RunStore state is derivable from events. The follow-ups doc lists gaps.
|
||||
**Confidence:** 90%
|
||||
**Complexity:** High
|
||||
**Status:** In Progress
|
||||
|
||||
### 2. Auto-Start Server Daemon
|
||||
**Description:** When a CLI command needs store access and `fabro.sock` is missing (or unreachable), automatically run `fabro server start` before proceeding. Uses existing daemon management and readiness probe.
|
||||
**Rationale:** Without this, every CLI command fails unless the user manually starts the server first. The daemon infrastructure already exists (start.rs has try_connect readiness probe, daemon spawning, flock locking). Auto-start is the difference between smooth DX and broken DX.
|
||||
**Downsides:** First command in a session pays ~1-2s startup cost. Edge cases around stale sockets and failed starts.
|
||||
**Confidence:** 95%
|
||||
**Complexity:** Low
|
||||
**Status:** Unexplored
|
||||
|
||||
### 3. Thin HTTP Client for CLI
|
||||
**Description:** An HTTP-backed `Store`/`RunStore` implementation that connects to the server over Unix socket. With events-first (#1), this is thin — mostly `POST /events`, SSE subscription, and a handful of read endpoints. Replaces the ~25 `build_store()` call sites.
|
||||
**Rationale:** The mechanical bridge between CLI and server. The trait boundary is the right seam. `InMemoryStore` tests are completely unaffected.
|
||||
**Downsides:** Error handling for server-down scenarios (mitigated by auto-start #2).
|
||||
**Confidence:** 95%
|
||||
**Complexity:** Medium
|
||||
**Status:** Unexplored
|
||||
|
||||
## Rejection Summary
|
||||
|
||||
| # | Idea | Reason Rejected |
|
||||
|---|------|-----------------|
|
||||
| 1 | Batch write API | Premature optimization — measure Unix socket latency first |
|
||||
| 2 | Run-prefixed key namespace | Implementation detail, falls out of engine design |
|
||||
| 3 | Streaming binary assets | YAGNI — no evidence of multi-MB blob problems |
|
||||
| 4 | Graceful fallback / offline mode | Fights the architecture — auto-start is the answer |
|
||||
| 5 | Connection pooling | Default HTTP client behavior, not a decision |
|
||||
| 6 | In-memory projection cache | Redundant with events-first — materialization IS the cache |
|
||||
| 7 | Eliminate SlateDB (BTreeMap + WAL) | Building a database; SlateDB provides S3 path |
|
||||
| 8 | Auto-generate HTTP client from trait | Contradicts coarser-grained API design |
|
||||
| 9 | Lazy-load sequence counters | Micro-optimization; events-first removes the problem |
|
||||
| 10 | Kill HTTP; shared SlateDB as IPC | Contradicts architecture; couples to storage internals |
|
||||
| 11 | Flip dependency (server in CLI) | Architecturally backwards from stated direction |
|
||||
| 12 | Event log as IPC (no HTTP) | Shared file append is fragile; HTTP serializes for free |
|
||||
| 13 | Consolidate catalog only | Half-measure creating a third topology |
|
||||
| 14 | CLI event-streaming client | Subsumed by events-first |
|
||||
| 15 | Time-travel / run replay | Not a consolidation decision; events-first makes it free later |
|
||||
| 16 | Multi-workspace fan-in | Feature creep; no current demand |
|
||||
| 17 | Reactive web UI via events | Orthogonal frontend concern |
|
||||
| 18 | Persistent run queue | Orthogonal scheduler feature |
|
||||
| 19 | MCP host for external agents | Orthogonal; fabro-mcp exists |
|
||||
| 20 | Tombstone soft delete | Implementation detail of engine |
|
||||
| 21 | Intent log for crash recovery | Redundant — event log IS the intent log |
|
||||
| 22 | Column families | SlateDB doesn't support them; premature |
|
||||
| 23 | Optimistic concurrency control | Single server owns writes — no concurrent writer problem |
|
||||
| 24 | Backpressure / write batching | Premature; no write pressure evidence |
|
||||
| 25 | SQLite catalog + cross-run queries | Moving away from SQLite dependency; use SlateDB-based index |
|
||||
| 26 | Migration command | Greenfield app, not yet deployed |
|
||||
| 27 | Consolidate to SQLite | SlateDB provides bottomless S3 storage |
|
||||
|
||||
## Session Log
|
||||
- 2026-04-02: Initial ideation — 35 candidates generated (6 agents), 6 survived critique, 3 accepted by user (rejected: SQLite catalog, migration command, SQLite as engine)
|
||||
|
|
@ -1,134 +0,0 @@
|
|||
---
|
||||
date: 2026-04-08
|
||||
topic: fabro-event-schema
|
||||
focus: greenfield redesign of Fabro's event schemas and streaming contract
|
||||
---
|
||||
|
||||
# Ideation: Fabro Event Schema Redesign
|
||||
|
||||
Assumption: greenfield reset. No production deployments, no backward-compatibility constraints, optimize for the best long-term event model rather than incremental migration cost.
|
||||
|
||||
These are not ten unrelated features. They are the ten strongest changes to make as one coherent event-platform redesign.
|
||||
|
||||
## Codebase Context
|
||||
|
||||
- Fabro already has the strongest core envelope in the comparison set: `id`, `ts`, `run_id`, `event`, optional `session_id`, `parent_session_id`, `node_id`, `node_label`, plus `properties`
|
||||
- `docs-internal/events-strategy.md` already treats events as the durable audit trail that powers storage, SSE, CLI progress, retro analysis, and JSONL sinks
|
||||
- `RunEvent` and `EventBody` already give Fabro a typed internal model, but the public contract is still more convention-driven than schema-first
|
||||
- Recent internal plans already push Fabro toward events as source of truth, checkpoint derivation, and simplified `RunEvent`, so the repo is directionally aligned with a stronger event platform
|
||||
- The biggest remaining gaps are cross-cutting ones: replay, correlation depth, public schema generation, live-stream semantics, and structured status/error/approval states
|
||||
|
||||
## Ranked Ideas
|
||||
|
||||
### 1. Split Fabro into two event products: a durable event log and a live UI stream
|
||||
**Description:** Define two first-class streams instead of one overloaded one. The durable log contains immutable domain facts suitable for audit, replay, storage, and projections. The live stream contains UI-oriented deltas, snapshots, keep-alives, and fast-changing progress. They share IDs and correlation fields, but they are different contracts.
|
||||
**Rationale:** This is the highest-leverage fix. Most competitors get into trouble by mixing audit events, high-frequency streaming deltas, control frames, and reconnect machinery into one schema. Fabro should not. Durable events should be boring and trustworthy. Live events should be optimized for interactivity.
|
||||
**Downsides:** Two contracts are more work than one. Emitters must decide whether an event is durable, live-only, or both.
|
||||
**Confidence:** 98%
|
||||
**Complexity:** High
|
||||
**Status:** Recommended
|
||||
|
||||
### 2. Add a formal replay and resume contract with ordered cursors and snapshot handshakes
|
||||
**Description:** Every run and session stream gets a monotonic `seq` plus a documented resume protocol: subscribe from cursor, receive the latest snapshot if needed, then apply deltas after `seq > cursor`. Define SSE `id` semantics, dedupe rules, replay buffer guarantees, and failure behavior when a client falls too far behind.
|
||||
**Rationale:** Goose is the clearest proof that reconnect semantics need to be part of the design, not a side effect. Greenfield Fabro should make "reattach to a long-running workflow" a first-class use case.
|
||||
**Downsides:** The server needs replay buffers or snapshot storage, and clients need to implement cursor logic correctly.
|
||||
**Confidence:** 96%
|
||||
**Complexity:** High
|
||||
**Status:** Recommended
|
||||
|
||||
### 3. Expand the envelope into a real correlation graph
|
||||
**Description:** Keep the existing strong envelope and add the IDs Fabro will actually want long term: `workflow_id`, `branch_id`, `checkpoint_id`, `turn_id`, `message_id`, `tool_call_id`, `request_id`, `causation_id`, and `correlation_id`. Not every event sets every field, but the contract makes those slots explicit.
|
||||
**Rationale:** Current Fabro is strong at run/session/node identity, but still thin below that. The next generation of debugging, UI, projection, and analytics work will want to join events by turn, message, tool call, branch, checkpoint, and request without reconstructing those edges from payloads.
|
||||
**Downsides:** Emitters and handlers must be stricter about ID ownership and propagation.
|
||||
**Confidence:** 95%
|
||||
**Complexity:** Medium
|
||||
**Status:** Recommended
|
||||
|
||||
### 4. Make the public event contract schema-first and generated from one registry
|
||||
**Description:** Keep Fabro's `event` + event-specific payload shape, but stop treating the public wire contract as implicit. Generate JSON Schema, TypeScript types, Rust validators, docs, and streaming examples from one source of truth. Every public event family gets an explicit schema version from day one.
|
||||
**Rationale:** This is the cleanest fix for drift. Claude Sessions benefits from having a clear public union. OpenCode shows how useful generated event types are. Fabro should combine both while preserving its stronger envelope.
|
||||
**Downsides:** Codegen and schema governance add process overhead. Some engineers will fight the discipline.
|
||||
**Confidence:** 94%
|
||||
**Complexity:** High
|
||||
**Status:** Recommended
|
||||
|
||||
### 5. Normalize lifecycle grammar across all streamable entities
|
||||
**Description:** Standardize event families around a small lifecycle vocabulary: `.started`, `.delta`, `.snapshot`, `.completed`, `.failed`, `.cancelled`, `.interrupted`. Apply it consistently to runs, stages, sessions, turns, messages, tool calls, commands, checkpoints, parallel branches, and retro work where relevant.
|
||||
**Rationale:** pi-mono is strongest here. Clients get dramatically simpler when every streamable thing follows the same lifecycle rules instead of bespoke one-off semantics.
|
||||
**Downsides:** Some event families will feel slightly unnatural if forced into the same lifecycle vocabulary. Discipline matters.
|
||||
**Confidence:** 93%
|
||||
**Complexity:** Medium
|
||||
**Status:** Recommended
|
||||
|
||||
### 6. Replace stringly status and failure fields with explicit tagged unions
|
||||
**Description:** Stop representing terminal and waiting states as loosely-typed strings where possible. Add typed unions for `stop_reason`, `retry_status`, `approval_status`, `wait_reason`, `error_kind`, `failure_class`, and `interrupt_reason`. Preserve display strings separately when useful.
|
||||
**Rationale:** Claude Sessions gets this exactly right. This is a major quality jump for policy engines, UIs, analytics, and test fixtures. It also reduces accidental schema drift where one code path emits `"timed_out"` and another emits `"timeout"`.
|
||||
**Downsides:** More up-front schema design. Adding new states later requires more care.
|
||||
**Confidence:** 96%
|
||||
**Complexity:** Medium
|
||||
**Status:** Recommended
|
||||
|
||||
### 7. Introduce typed content blocks and block-level deltas for agent output
|
||||
**Description:** Model agent-facing content as typed blocks instead of mostly strings: `text`, `reasoning`, `tool_call`, `tool_result`, `patch`, `file_ref`, `artifact_ref`, `plan`, `todo`, `command_output`, and `summary`. Live deltas target block IDs rather than appending ambiguous raw text.
|
||||
**Rationale:** This is the difference between a transcript that only humans can read and one that both humans and tools can reason over. It unlocks richer UIs, selective re-rendering, better retro analysis, and much cleaner summarization and compaction.
|
||||
**Downsides:** The model is more complex than "event name plus string payload." Poorly chosen block boundaries can make clients awkward.
|
||||
**Confidence:** 92%
|
||||
**Complexity:** High
|
||||
**Status:** Recommended
|
||||
|
||||
### 8. Make human-in-the-loop and control-plane semantics first-class events
|
||||
**Description:** Promote approvals, questions, interrupts, resumes, compactions, and operator interventions into explicit event families: `approval.requested`, `approval.responded`, `question.asked`, `question.answered`, `interrupt.requested`, `interrupt.applied`, `resume.required`, `compaction.started`, `compaction.completed`, `compaction.failed`.
|
||||
**Rationale:** This is one of the clearest wins from Claude Sessions and OpenCode. Human-in-loop behavior is not edge-case control traffic. It is core workflow state and deserves durable, typed representation.
|
||||
**Downsides:** It increases surface area. Some flows that are currently implicit must become explicit state machines.
|
||||
**Confidence:** 94%
|
||||
**Complexity:** Medium
|
||||
**Status:** Recommended
|
||||
|
||||
### 9. Add first-class snapshot events for fast attach and projection repair
|
||||
**Description:** Introduce self-contained snapshot events such as `run.snapshot`, `session.snapshot`, and `checkpoint.saved` that intentionally duplicate enough state to let clients and projectors reattach without replaying the full history. Treat these as part of the contract, not ad hoc recovery hacks.
|
||||
**Rationale:** This complements replay. Durable facts remain append-only, but long-running workflows need efficient recovery points. Greenfield Fabro can design snapshots deliberately instead of letting checkpoint semantics and UI recovery drift apart.
|
||||
**Downsides:** Snapshot compaction and retention rules must be explicit or the event system becomes harder to reason about.
|
||||
**Confidence:** 90%
|
||||
**Complexity:** High
|
||||
**Status:** Recommended
|
||||
|
||||
### 10. Promote model, tool, and command work into first-class span-style event families
|
||||
**Description:** Treat model requests, tool execution, MCP calls, shell commands, and patch application as first-class event families with started/completed/error plus usage, latency, retries, provider, model, routing, approval outcome, and output references. Do not hide these behind generic stage completion summaries.
|
||||
**Rationale:** Fabro is an AI workflow product. The event model should expose the actual unit economics and failure surfaces of AI work. This gives better debugging, cost analysis, policy enforcement, and product telemetry than aggregating everything back into stage summaries.
|
||||
**Downsides:** More event volume. Care is needed to keep live deltas separate from durable summaries.
|
||||
**Confidence:** 93%
|
||||
**Complexity:** Medium
|
||||
**Status:** Recommended
|
||||
|
||||
## What This Adds Up To
|
||||
|
||||
If Fabro adopted all ten, the resulting idealized model would look like this:
|
||||
|
||||
- one durable event log for facts
|
||||
- one live stream for interactive state
|
||||
- one shared envelope with strong correlation IDs
|
||||
- one generated public schema registry
|
||||
- one consistent lifecycle grammar
|
||||
- one explicit replay/snapshot story
|
||||
- typed blocks and typed states instead of strings and ad hoc payloads
|
||||
|
||||
That is materially better than any single comparator repo.
|
||||
|
||||
## Rejection Summary
|
||||
|
||||
| # | Idea | Reason Rejected |
|
||||
|---|------|-----------------|
|
||||
| 1 | Keep one stream and just document it better | Not enough — durable and live concerns have different optimization goals |
|
||||
| 2 | Flatten all event-specific fields into the top level | Root churn would make the schema worse, not better |
|
||||
| 3 | Switch to JSON-RPC-style `method`/`params` notifications | Too transport-shaped for Fabro's broader event-log use case |
|
||||
| 4 | Use timestamps alone for replay ordering | Weak contract; reconnect needs explicit sequence semantics |
|
||||
| 5 | Eventize binary artifacts and all large blobs directly | Expensive and noisy; use refs/metadata instead |
|
||||
| 6 | Keep string errors but standardize message text | Still not machine-readable enough |
|
||||
| 7 | Make snapshots the only source of truth | Loses auditability and event-sourced advantages |
|
||||
| 8 | Encode every UI concern in the durable log | Durable logs should stay trustworthy and projection-friendly |
|
||||
| 9 | Preserve current schema and only add more event names | Misses the deeper contract problems |
|
||||
| 10 | Treat approvals and questions as transport-level control traffic | These are product-level workflow semantics and belong in the event model |
|
||||
|
||||
## Session Log
|
||||
|
||||
- 2026-04-08: Grounded ideation from current Fabro event docs and code, plus comparison against Claude Sessions, Claude Code, Goose, OpenAI Codex, OpenCode, and pi-mono. Survivors intentionally optimized for greenfield quality rather than migration ease.
|
||||
|
|
@ -1,82 +0,0 @@
|
|||
---
|
||||
date: 2026-04-08
|
||||
topic: fabro-uninstall
|
||||
focus: add `fabro uninstall` command — the opposite of install
|
||||
---
|
||||
|
||||
# Ideation: `fabro uninstall` Command
|
||||
|
||||
## Codebase Context
|
||||
|
||||
- `fabro install` creates `~/.fabro/` with settings.toml, certs/, storage/ (secrets, server state, logs, scratch, store, artifacts), skills/, workflows/, logs/, tmp/
|
||||
- `install.sh` modifies shell configs (.zshrc/.bashrc/.config/fish) adding PATH entries with `# fabro` sentinel comment
|
||||
- `Home` (fabro-util) and `Storage` (fabro-config) structs are canonical path registries
|
||||
- `system prune` provides the established dry-run/--yes/size-reporting UX pattern
|
||||
- `server stop` handles graceful SIGTERM→SIGKILL with socket cleanup
|
||||
- Binary installed to `~/.fabro/bin/fabro` by install.sh; brew/cargo installs go elsewhere
|
||||
|
||||
## Ranked Ideas
|
||||
|
||||
### 1. Core Mirror Uninstall
|
||||
**Description:** `fabro uninstall` removes `~/.fabro/` entirely, using `Home` and `Storage` structs as the canonical path registry. Compose existing deletion logic rather than writing new teardown code.
|
||||
**Rationale:** Home/Storage structs enumerate every path, so future paths added to install automatically appear in uninstall — zero maintenance drift.
|
||||
**Downsides:** None significant — table stakes.
|
||||
**Confidence:** 95%
|
||||
**Complexity:** Low
|
||||
**Status:** Unexplored
|
||||
|
||||
### 2. Server Shutdown First
|
||||
**Description:** Before removing any files, detect a running server and gracefully stop it, reusing `server stop` logic (SIGTERM→SIGKILL). Only then proceed with file deletion.
|
||||
**Rationale:** Deleting files under a running server creates orphaned processes, dangling sockets, and corrupt state.
|
||||
**Downsides:** None — correctness requirement.
|
||||
**Confidence:** 95%
|
||||
**Complexity:** Low
|
||||
**Status:** Unexplored
|
||||
|
||||
### 3. Shell Config Cleanup
|
||||
**Description:** Remove PATH lines from `.zshrc`/`.bashrc`/`.config/fish` that `install.sh` added, using the `# fabro` sentinel comment as grep target.
|
||||
**Rationale:** Stale PATH entries are the #1 complaint after CLI uninstalls. Sentinel comment makes surgical removal safe.
|
||||
**Downsides:** Shell config surgery requires careful testing across shells.
|
||||
**Confidence:** 85%
|
||||
**Complexity:** Medium
|
||||
**Status:** Unexplored
|
||||
|
||||
### 4. Dry-Run by Default
|
||||
**Description:** Follow `system prune` pattern: list everything that would be removed with sizes, require `--yes` to confirm. Support `--json`.
|
||||
**Rationale:** Already proven UX in the codebase. Prevents "oops" moments.
|
||||
**Downsides:** None.
|
||||
**Confidence:** 95%
|
||||
**Complexity:** Low
|
||||
**Status:** Unexplored
|
||||
|
||||
### 5. Binary Self-Removal
|
||||
**Description:** If binary lives inside `~/.fabro/bin/` (install.sh path), delete it as final step. For brew/cargo, print a hint instead.
|
||||
**Rationale:** Users expect "uninstall" to mean "gone." Simple conditional based on `current_exe()` path.
|
||||
**Downsides:** Self-deleting binary must be last step. Detection heuristic could be wrong if user moved the binary.
|
||||
**Confidence:** 75%
|
||||
**Complexity:** Low
|
||||
**Status:** Unexplored
|
||||
|
||||
## Rejection Summary
|
||||
|
||||
| # | Idea | Reason Rejected |
|
||||
|---|------|-----------------|
|
||||
| 1 | Selective component uninstall | YAGNI — users can back up manually |
|
||||
| 2 | GitHub App deregistration | Scope creep — remote API during teardown is fragile |
|
||||
| 3 | Export before destroy | Gold-plating — `cp -r ~/.fabro` suffices |
|
||||
| 4 | Telemetry farewell event | Marginal value, unwelcome phoning home |
|
||||
| 5 | Install manifest | Over-engineering for small deterministic footprint |
|
||||
| 6 | Per-repo cascade cleanup | Filesystem scanning is slow and presumptuous |
|
||||
| 7 | Secure secrets shredding | Security theater on modern SSDs |
|
||||
| 8 | Reframe as `system reset` | Poor discoverability |
|
||||
| 9 | Doctor extension | Mixing diagnostic and destructive ops |
|
||||
| 10 | Install --undo flag | Terrible discoverability |
|
||||
| 11 | Teardown facet trait | Premature abstraction for ~5 steps |
|
||||
| 12 | Event-sourced uninstall | Requires rewriting install first |
|
||||
| 13 | Restoration script | Worse version of export (already cut) |
|
||||
| 14 | Server-mediated uninstall | Circular dependency |
|
||||
| 15 | Manifest + Selective | Both halves cut |
|
||||
| 16 | Doctor-informed uninstall | Coupling for no benefit |
|
||||
|
||||
## Session Log
|
||||
- 2026-04-08: Initial ideation — ~40 generated across 5 agents, deduped to 22, 5 survived. All 5 accepted as facets of one command. Proceeding to plan.
|
||||
|
|
@ -1,280 +0,0 @@
|
|||
# Reduce Cargo Target APFS Churn Plan
|
||||
|
||||
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
||||
|
||||
**Goal:** Make day-to-day Cargo builds and cleanup less painful on macOS/APFS by reducing the number and size of debug artifacts written under `target/`.
|
||||
|
||||
**Architecture:** Keep the change local to Cargo profile configuration first, because the observed slow path was filesystem metadata deletion in `target/debug/deps`, not Rust compilation logic. Prefer reversible profile tuning over moving build output or disabling incremental compilation until measurements prove those stronger options are needed.
|
||||
|
||||
**Tech Stack:** Rust Cargo profiles, macOS/APFS, `cargo clean`, `cargo nextest`, pinned nightly formatting/lint commands.
|
||||
|
||||
---
|
||||
|
||||
## Background
|
||||
|
||||
On 2026-04-28, `cargo clean` in this repo spent several minutes deleting `target/debug/deps`. A process sample showed the active work was mostly `unlink(2)`, with smaller time in `lstat` and directory traversal. Activity Monitor reported very low write throughput because this workload is metadata-bound: many small file deletions and APFS journal updates, not large sequential writes.
|
||||
|
||||
The repo already has:
|
||||
|
||||
```toml
|
||||
[profile.dev.package."*"]
|
||||
debug = false # Disable debug info for all dependencies
|
||||
opt-level = 1 # Shrinks monomorphized generics, reducing test binary size
|
||||
```
|
||||
|
||||
That reduces dependency debug info, but workspace crates can still emit full debug info. The sampled clippy command included `-C debuginfo=2 -C split-debuginfo=unpacked` for a Fabro crate, which can create more debug artifacts and cleanup work on macOS.
|
||||
|
||||
## Proposed First Change
|
||||
|
||||
Add lower-debug Cargo profile settings for local dev and tests:
|
||||
|
||||
```toml
|
||||
[profile.dev]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
|
||||
[profile.test]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
```
|
||||
|
||||
Expected impact:
|
||||
|
||||
- Keeps source file and line information for backtraces.
|
||||
- Usually keeps breakpoints and source stepping usable.
|
||||
- Reduces or removes rich local-variable inspection in `lldb` and IDE debuggers.
|
||||
- Reduces debug metadata and split-debug filesystem artifacts.
|
||||
- Does not change debug assertions, overflow checks, runtime behavior, or optimization level.
|
||||
- Causes one rebuild after the profile settings change.
|
||||
|
||||
## Task 1: Baseline Current Target Cost
|
||||
|
||||
**Files:**
|
||||
- Read: `Cargo.toml`
|
||||
- No code changes
|
||||
|
||||
- [ ] **Step 1: Confirm no `cargo clean` is running**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
ps -axo pid,ppid,stat,etime,pcpu,command | rg -i 'cargo clean' || true
|
||||
```
|
||||
|
||||
Expected: no active `cargo clean` process, or wait for the existing cleanup to finish.
|
||||
|
||||
- [ ] **Step 2: Build the workspace using current settings**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo build --workspace
|
||||
```
|
||||
|
||||
Expected: build succeeds.
|
||||
|
||||
- [ ] **Step 3: Record current target size**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
du -sh target target/debug target/debug/deps 2>/dev/null
|
||||
```
|
||||
|
||||
Expected: record the three size values in this file under "Results".
|
||||
|
||||
- [ ] **Step 4: Record current entry pressure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
find target/debug/deps -maxdepth 1 -mindepth 1 | wc -l
|
||||
```
|
||||
|
||||
Expected: record the entry count in this file under "Results".
|
||||
|
||||
## Task 2: Apply Lower-Debug Profile Settings
|
||||
|
||||
**Files:**
|
||||
- Modify: `Cargo.toml`
|
||||
|
||||
- [ ] **Step 1: Add profile settings**
|
||||
|
||||
Edit `Cargo.toml` so the release profile section is followed by:
|
||||
|
||||
```toml
|
||||
[profile.dev]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
|
||||
[profile.test]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
```
|
||||
|
||||
Keep the existing dependency-specific dev profile below it:
|
||||
|
||||
```toml
|
||||
[profile.dev.package."*"]
|
||||
debug = false # Disable debug info for all dependencies
|
||||
opt-level = 1 # Shrinks monomorphized generics, reducing test binary size
|
||||
```
|
||||
|
||||
- [ ] **Step 2: Format if Cargo.toml style changes**
|
||||
|
||||
No formatter is required for this simple TOML change. Keep comments and spacing consistent with the surrounding file.
|
||||
|
||||
## Task 3: Verify Builds and Tests Still Work
|
||||
|
||||
**Files:**
|
||||
- Read: `Cargo.toml`
|
||||
- No additional code changes
|
||||
|
||||
- [ ] **Step 1: Build the workspace**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo build --workspace
|
||||
```
|
||||
|
||||
Expected: build succeeds. The first build after changing profile settings may rebuild many crates.
|
||||
|
||||
- [ ] **Step 2: Run the core test suite**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo nextest run --workspace
|
||||
```
|
||||
|
||||
Expected: tests pass. If macOS reports `Too many open files (os error 24)`, rerun with:
|
||||
|
||||
```bash
|
||||
ulimit -n 4096 && cargo nextest run --workspace
|
||||
```
|
||||
|
||||
- [ ] **Step 3: Run clippy with the pinned nightly toolchain**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings
|
||||
```
|
||||
|
||||
Expected: clippy passes.
|
||||
|
||||
## Task 4: Measure Impact
|
||||
|
||||
**Files:**
|
||||
- Read: `Cargo.toml`
|
||||
- Update: this plan's "Results" section
|
||||
|
||||
- [ ] **Step 1: Record new target size**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
du -sh target target/debug target/debug/deps 2>/dev/null
|
||||
```
|
||||
|
||||
Expected: compare against Task 1.
|
||||
|
||||
- [ ] **Step 2: Record new entry pressure**
|
||||
|
||||
Run:
|
||||
|
||||
```bash
|
||||
find target/debug/deps -maxdepth 1 -mindepth 1 | wc -l
|
||||
```
|
||||
|
||||
Expected: compare against Task 1. The size reduction may be more meaningful than entry-count reduction, depending on how much split debug info was previously generated.
|
||||
|
||||
- [ ] **Step 3: Time a clean operation when convenient**
|
||||
|
||||
Run only when a full cleanup is acceptable:
|
||||
|
||||
```bash
|
||||
time cargo clean
|
||||
```
|
||||
|
||||
Expected: compare wall-clock time against the prior observed multi-minute cleanup. Activity Monitor may still show low MB/s because deletion remains metadata-bound.
|
||||
|
||||
## Task 5: Decide Whether to Stop or Tune Further
|
||||
|
||||
**Files:**
|
||||
- Modify only if needed: `Cargo.toml`
|
||||
- Optional local-only config: `.cargo/config.toml`
|
||||
|
||||
- [ ] **Step 1: Stop if the result is acceptable**
|
||||
|
||||
If `target/` size and cleanup time are acceptable, keep the lower-debug profile settings and do not add more tuning.
|
||||
|
||||
- [ ] **Step 2: Consider disabling incremental only if cleanup is still too costly**
|
||||
|
||||
Use this stronger setting only if the cleanup pain still outweighs slower edit-compile cycles:
|
||||
|
||||
```toml
|
||||
[profile.dev]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
incremental = false
|
||||
|
||||
[profile.test]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
incremental = false
|
||||
```
|
||||
|
||||
Expected tradeoff: fewer incremental artifacts, but slower repeated local builds.
|
||||
|
||||
- [ ] **Step 3: Consider a local target directory only if repo-local `target/` remains disruptive**
|
||||
|
||||
For a personal-only setup, use `.cargo/config.toml` if it is intentionally untracked, or a global Cargo config outside the repo:
|
||||
|
||||
```toml
|
||||
[build]
|
||||
target-dir = "/Users/bhelmkamp/.cache/cargo-targets/fabro"
|
||||
```
|
||||
|
||||
Expected tradeoff: build output is isolated from the repo and easier to exclude from Spotlight/backups, but all developers do not automatically share the same behavior unless the config is committed.
|
||||
|
||||
## Rollback
|
||||
|
||||
To restore full debug info for normal dev/test builds, remove these settings:
|
||||
|
||||
```toml
|
||||
[profile.dev]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
|
||||
[profile.test]
|
||||
debug = "line-tables-only"
|
||||
split-debuginfo = "off"
|
||||
```
|
||||
|
||||
For a one-off debugger session without changing `Cargo.toml`, run:
|
||||
|
||||
```bash
|
||||
CARGO_PROFILE_DEV_DEBUG=2 CARGO_PROFILE_DEV_SPLIT_DEBUGINFO=unpacked cargo build
|
||||
```
|
||||
|
||||
## Results
|
||||
|
||||
Fill this in when the plan is executed:
|
||||
|
||||
```text
|
||||
Before:
|
||||
- target size:
|
||||
- target/debug size:
|
||||
- target/debug/deps size:
|
||||
- target/debug/deps entries:
|
||||
- cargo clean wall-clock time:
|
||||
|
||||
After:
|
||||
- target size:
|
||||
- target/debug size:
|
||||
- target/debug/deps size:
|
||||
- target/debug/deps entries:
|
||||
- cargo clean wall-clock time:
|
||||
```
|
||||
|
|
@ -1,49 +0,0 @@
|
|||
# CLI Workflow Coupling Audit
|
||||
|
||||
## Scope
|
||||
|
||||
- Production imports under `lib/apps/fabro-cli/src/**` that still reference `fabro_workflow::*` after the server-owned selector/export refactor.
|
||||
- Test-only imports are listed separately so the remaining architectural debt is explicit.
|
||||
|
||||
## Completed In This Change
|
||||
|
||||
- Removed the production CLI dependency on `fabro_workflow::run_lookup`.
|
||||
- Removed the production CLI dependency on `fabro_workflow::run_dump`.
|
||||
- Added server-owned selector resolution via `GET /api/v1/runs/resolve` and migrated single-run selector flows to it.
|
||||
- Migrated user-facing fork/rewind timeline inspection and execution to server APIs.
|
||||
|
||||
## Remaining Production Couplings
|
||||
|
||||
| Path | Direct dependency | Why it still exists | Required remediation track |
|
||||
| --- | --- | --- | --- |
|
||||
| `lib/apps/fabro-cli/src/commands/pr/create.rs` | `StageOutcome`, `pull_request::maybe_open_pull_request` | CLI still reconstructs store state and runs PR creation logic from the workflow pipeline directly. | Replace with a server API, or extract PR orchestration into a non-engine shared service crate plus API. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/runner.rs` | `artifact_snapshot::CapturedArtifactInfo`, `artifact_upload::{ArtifactSink, StageArtifactUploader}`, `event::{Emitter, RunEventSink}`, `operations::{self, StartServices}`, `run_control::RunControlState`, `runtime_store::{RunStoreBackend, RunStoreHandle}` | Hidden worker subprocess path still lives inside the CLI crate and embeds the workflow engine directly. | Re-home worker/runtime code outside the user CLI surface, ideally into a dedicated worker crate or binary. |
|
||||
| `lib/apps/fabro-cli/src/manifest_builder.rs` | `git::{GitSyncStatus, head_sha, sync_status}` | Manifest submission still relies on git helper logic that happens to live in `fabro_workflow`. | Extract git-sync inspection helpers into a non-workflow shared crate/module. |
|
||||
| `lib/apps/fabro-cli/src/server_client.rs` | `artifact_snapshot::CapturedArtifactInfo` | The upload client reuses a workflow-owned artifact snapshot DTO. | Extract shared artifact snapshot DTOs into `fabro-store`, `fabro-types`, or a dedicated shared crate. |
|
||||
| `lib/apps/fabro-cli/src/commands/runs/inspect.rs` | `run_status::RunStatus` | CLI output types still depend on engine-owned run status enums. | Extract shared status types into `fabro-types` or switch to API-generated/public store types. |
|
||||
| `lib/apps/fabro-cli/src/commands/runs/list.rs` | `run_status::RunStatus` | List rendering still depends on engine-owned run status enums. | Extract shared status types into `fabro-types` or switch to API-generated/public store types. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/attach.rs` | `StageOutcome`, `run_status::RunStatus` | Attach/replay logic still formats engine-owned terminal status types directly. | Extract shared run/conclusion status types into `fabro-types`. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/output.rs` | `StageOutcome`, `records::Conclusion` | Human-readable completion output still consumes workflow-owned conclusion/status records. | Extract shared conclusion/status DTOs into `fabro-types` or `fabro-store`. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/wait.rs` | `records::Conclusion`, `run_status::RunStatus` | Wait output still depends on workflow-owned status/conclusion records. | Extract shared conclusion/status DTOs into `fabro-types` or `fabro-store`. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/run_progress/stage_display.rs` | `StageOutcome`, `format_cost` | Progress UI still depends on shared stage outcome and workflow-owned cost-formatting helper code. | Move formatting helpers into `fabro-util`. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/run_progress/info_display.rs` | `event::RunNoticeLevel` | Progress UI still formats workflow-owned notice levels directly. | Extract shared notice/event enums into `fabro-types`. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/run_progress/event.rs` | `event::RunNoticeLevel` | Progress event translation still depends on workflow-owned notice levels. | Extract shared notice/event enums into `fabro-types`. |
|
||||
|
||||
## Test-Only Couplings
|
||||
|
||||
| Path | Direct dependency | Why it still exists | Suggested handling |
|
||||
| --- | --- | --- | --- |
|
||||
| `lib/apps/fabro-cli/src/commands/dump.rs` test module | `event::{Event, append_event}` | Unit tests synthesize workflow events directly. | Low priority; keep until a lighter-weight event fixture helper exists. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/wait.rs` test module | `StageOutcome`, `records::Conclusion`, `run_status::RunStatusRecord` | Output tests construct workflow-owned records directly. | Replace with shared fixture builders once conclusion DTOs move out. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/run_progress/mod.rs` test module | `event::{Event, RunNoticeLevel, to_run_event, to_run_event_at}`, `outcome::billed_model_usage_from_llm` | Progress tests build engine events directly. | Replace with shared event fixture helpers after event DTO extraction. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/run_progress/event.rs` test module | `event::{Event, to_run_event}` | Event rendering tests depend on engine event constructors. | Replace with shared event fixture helpers after event DTO extraction. |
|
||||
| `lib/apps/fabro-cli/src/commands/run/runner.rs` test module | `artifact_upload::StageArtifactUploader` | Worker tests still reach into workflow upload internals. | Keep with worker re-home work; not worth separating first. |
|
||||
| `lib/apps/fabro-cli/tests/it/workflow/real_cli.rs` | `context::Context`, `event::Emitter`, `handler::agent::{CodergenBackend, CodergenResult}`, `handler::llm::cli::AgentCliBackend` | Integration test exercises the real workflow engine directly through CLI harnesses. | Accept as engine integration coverage or move under workflow-owned test support later. |
|
||||
| `lib/apps/fabro-cli/tests/it/scenario/recovery.rs` | `operations::{RunTimeline, build_timeline}` | Scenario test inspects rewind timeline internals directly. | Replace after server-owned rewind/timeline APIs exist. |
|
||||
|
||||
## Follow-Up Order
|
||||
|
||||
1. Design a server API for PR creation so user-facing CLI commands stop importing workflow PR operations directly.
|
||||
2. Decide whether the hidden worker path should move to a dedicated worker crate/binary or remain a CLI-internal implementation detail with a stricter boundary.
|
||||
3. Extract shared status, conclusion, notice, and artifact snapshot types/helpers out of `fabro_workflow`.
|
||||
4. Extract git sync helpers from `fabro_workflow` so manifest building no longer depends on engine code.
|
||||
|
|
@ -1,376 +0,0 @@
|
|||
# Event Schema Competitive Analysis
|
||||
|
||||
Date: 2026-04-08
|
||||
|
||||
This report compares the event schemas used by:
|
||||
|
||||
- Claude Sessions API
|
||||
- Claude Code
|
||||
- Goose
|
||||
- OpenAI Codex
|
||||
- OpenCode
|
||||
- pi-mono
|
||||
|
||||
Goal: identify patterns Fabro should copy, avoid, or formalize more clearly.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Fabro's current event model is already ahead of most of the field on one important point: it has a canonical envelope with stable metadata (`id`, `ts`, `run_id`, `event`, optional `session_id`, `parent_session_id`, `node_id`, `node_label`) and a typed internal-to-external mapping.
|
||||
|
||||
The biggest improvement opportunities are not "more events." They are:
|
||||
|
||||
1. Keep transport concerns separate from domain events, but document them as part of the contract.
|
||||
2. Make every streamed event part of one explicit public schema. Avoid opaque blobs and server-injected fields that the schema does not admit.
|
||||
3. Add more first-class correlation fields where the UI or downstream systems need them, especially `turn_id`, `message_id`, `tool_call_id`, `request_id`, and retry/attempt IDs.
|
||||
4. Make retry, stop, idle, and requires-action states machine-readable unions instead of loose strings.
|
||||
5. Be explicit about delta vs snapshot semantics and replay behavior.
|
||||
|
||||
## Fabro Baseline
|
||||
|
||||
Fabro's current strategy is documented in `docs-internal/events-strategy.md`. The canonical external shape is:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "uuidv7",
|
||||
"ts": "2026-03-30T12:00:01.000Z",
|
||||
"run_id": "01JQ...",
|
||||
"event": "agent.tool.started",
|
||||
"session_id": "ses_child",
|
||||
"parent_session_id": "ses_parent",
|
||||
"node_id": "code",
|
||||
"node_label": "Code",
|
||||
"properties": { "...": "..." }
|
||||
}
|
||||
```
|
||||
|
||||
That envelope is stronger than most comparator systems. It gives Fabro stable top-level metadata, keeps event-specific data inside `properties`, and avoids flattening arbitrary fields into the root.
|
||||
|
||||
Relevant current Fabro sources:
|
||||
|
||||
- `docs-internal/events-strategy.md`
|
||||
- `lib/components/fabro-workflow/src/event.rs`
|
||||
- `lib/foundation/fabro-types/src/run_event/mod.rs`
|
||||
- pebble's `CodingEvent` (`pebble-coding-agent`, re-exported from `fabro_types`)
|
||||
|
||||
## Comparison Matrix
|
||||
|
||||
| System | Public event surface | Discriminator | Universal envelope fields on every event | Replay / ordering story | Main strength | Main weakness |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| Claude Sessions | 20-event public union | `type` | `id`, `processed_at` | Event IDs exist; replay semantics are not part of the event payload | Very explicit, stable union with typed nested states | Less transport detail and fewer workflow-specific events |
|
||||
| Claude Code | 24 core SDK messages, 31 stdout/control variants | `type`, often `subtype` | Usually `uuid`, `session_id`; no universal timestamp | Streaming is batched/coalesced; control and domain share the same channel | Rich task, hook, status, and tool progress | Nested stream payload is opaque at runtime; control and data are mixed |
|
||||
| Goose | 7 `MessageEvent` variants | `type` | None in JSON payload; SSE `id` is outside payload | Strong SSE replay via monotonic seq + `Last-Event-ID` + replay buffer | Reattach/replay semantics are clear | Transport fields are injected outside schema; payload typing is shallow |
|
||||
| Codex SDK | 8 thread events | `type` | No universal ID/timestamp | Ordered stream, no replay contract in payload | Very simple client model | Too minimal for rich UIs and analytics |
|
||||
| Codex app-server | 49 notification methods | `method` + `params` | No universal ID/timestamp in params | Ordered notifications, no seq/replay field | Richest low-level protocol in the set | Fragmented event story; transport shape leaks into the schema |
|
||||
| OpenCode | 45 generated event variants | `type` + `properties` | No universal ID/timestamp | Plain SSE; client supports SSE IDs but server does not emit them | Broadest app/runtime event coverage | Wire/schema drift and no universal envelope |
|
||||
| pi-mono | 12 assistant stream events, 10 agent events, 14 session events | `type` | Session header only; not per event | JSONL stream, no replay contract | Excellent streaming lifecycle grammar | No durable universal envelope for downstream consumers |
|
||||
|
||||
## System Notes
|
||||
|
||||
### Claude Sessions
|
||||
|
||||
What it does well:
|
||||
|
||||
- One explicit public union.
|
||||
- Every event has `id`, `type`, and `processed_at`.
|
||||
- Tool confirmation, custom tool results, MCP tool use, session errors, session status, and model-span events are all first-class.
|
||||
- Terminal and waiting states are structured. `session.status_idle.stop_reason` is not a loose string; it is a small union.
|
||||
- Error reporting is structured. `session.error.error` is a tagged union, not just a message.
|
||||
|
||||
Why it matters for Fabro:
|
||||
|
||||
- This is the cleanest example of a public agent-session event API that is still small enough to understand.
|
||||
- The main idea to copy is not the exact event list. It is the discipline: explicit tagged unions for stop reasons, errors, and status transitions.
|
||||
|
||||
Sources:
|
||||
|
||||
- `https://platform.claude.com/docs/en/api/beta/sessions/events/stream`
|
||||
- `https://platform.claude.com/docs/specs/merged.53db30dfcc06f431.json.gz`
|
||||
|
||||
### Claude Code
|
||||
|
||||
Schema shape:
|
||||
|
||||
- `SDKMessageSchema` contains 24 core message variants.
|
||||
- `StdoutMessageSchema` expands the stdout protocol to 31 variants once control messages and keep-alives are included.
|
||||
- Many events use `type: "system"` plus a `subtype`, for example `init`, `status`, `api_retry`, `hook_started`, `task_progress`, and `session_state_changed`.
|
||||
- Streaming assistant output is wrapped as `type: "stream_event"`.
|
||||
|
||||
What it does well:
|
||||
|
||||
- It covers more than just model output: task lifecycle, hook lifecycle, compaction boundaries, retries, authentication state, file persistence, tool progress, prompt suggestions.
|
||||
- It carries `uuid` and `session_id` widely, which is useful for correlation.
|
||||
- It includes explicit session-state transitions (`idle`, `running`, `requires_action`).
|
||||
|
||||
What is weak:
|
||||
|
||||
- The nested streaming payload is not explicitly validated at runtime. `RawMessageStreamEventPlaceholder` is `z.unknown()`.
|
||||
- Control protocol messages live in the same stream as domain messages.
|
||||
- `type: "system"` plus `subtype` is workable, but less ergonomic than a flatter public union.
|
||||
- There is no universal top-level timestamp on every event.
|
||||
|
||||
Why it matters for Fabro:
|
||||
|
||||
- Copy the breadth, not the shape.
|
||||
- Avoid opaque inner payloads in public schemas.
|
||||
- Avoid mixing keep-alive/control/config traffic into the same schema that product consumers use for analytics and UI rendering.
|
||||
|
||||
Sources:
|
||||
|
||||
- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/entrypoints/sdk/coreSchemas.ts`
|
||||
- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/entrypoints/sdk/controlSchemas.ts`
|
||||
- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/remote/sdkMessageAdapter.ts`
|
||||
- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/cli/transports/ccrClient.ts`
|
||||
- `/Users/bhelmkamp/p/AnkanMisra/claude-code/src/utils/sdkEventQueue.ts`
|
||||
|
||||
### Goose
|
||||
|
||||
Schema shape:
|
||||
|
||||
- One small SSE payload union: `Message`, `Error`, `Finish`, `Notification`, `UpdateConversation`, `ActiveRequests`, `Ping`.
|
||||
- SSE `id:` carries a monotonic sequence number.
|
||||
- Session replay uses `Last-Event-ID` plus a replay buffer.
|
||||
- `request_id` and `chat_request_id` are injected at the SSE framing layer, not modeled in the payload type.
|
||||
|
||||
What it does well:
|
||||
|
||||
- Clear reattach story.
|
||||
- Monotonic sequence numbers are transport-level, not payload-level.
|
||||
- `ActiveRequests` lets the client discover in-flight work when reconnecting.
|
||||
|
||||
What is weak:
|
||||
|
||||
- The public event payload omits fields the client actually consumes.
|
||||
- `Notification.message` is effectively an untyped object.
|
||||
- The session stream also emits comment heartbeats outside the schema, and there is a separate `Ping` payload variant in the shared enum. That split is easy to drift.
|
||||
|
||||
Why it matters for Fabro:
|
||||
|
||||
- Goose is the best example here for replay and reconnect semantics.
|
||||
- The lesson is not "put sequence numbers in the payload." The lesson is "formalize replay outside the payload, and do not rely on undocumented injected fields."
|
||||
|
||||
Sources:
|
||||
|
||||
- `/Users/bhelmkamp/p/block/goose/crates/goose-server/src/routes/reply.rs`
|
||||
- `/Users/bhelmkamp/p/block/goose/crates/goose-server/src/routes/session_events.rs`
|
||||
- `/Users/bhelmkamp/p/block/goose/crates/goose-server/src/session_event_bus.rs`
|
||||
- `/Users/bhelmkamp/p/block/goose/ui/desktop/openapi.json`
|
||||
- `/Users/bhelmkamp/p/block/goose/ui/desktop/src/hooks/useSessionEvents.ts`
|
||||
|
||||
### OpenAI Codex
|
||||
|
||||
There are really two event systems:
|
||||
|
||||
1. The TypeScript SDK `ThreadEvent` surface.
|
||||
2. The app-server `ServerNotification` protocol.
|
||||
|
||||
SDK shape:
|
||||
|
||||
- 8 high-level events: thread started, turn started/completed/failed, item started/updated/completed, fatal stream error.
|
||||
- Rich detail is pushed down into `ThreadItem`, which includes `agent_message`, `reasoning`, `command_execution`, `file_change`, `mcp_tool_call`, `web_search`, `todo_list`, and `error`.
|
||||
|
||||
App-server shape:
|
||||
|
||||
- 49 server notification methods.
|
||||
- Notifications are discriminated by `method`, with a typed `params` object.
|
||||
- Coverage includes thread lifecycle, turn lifecycle, item lifecycle, deltas, token usage, command output, MCP progress, model reroutes, config warnings, and experimental realtime notifications.
|
||||
|
||||
What it does well:
|
||||
|
||||
- Good separation of a simple developer-facing SDK from a richer system protocol.
|
||||
- The low-level protocol is broad and explicit.
|
||||
- Experimental notifications are clearly labeled as experimental.
|
||||
|
||||
What is weak:
|
||||
|
||||
- The event story is fragmented. "Which schema should I build against?" depends on which integration layer you pick.
|
||||
- There is no universal timestamp or universal event ID in the event bodies.
|
||||
- `method` + `params` is transport-shaped. It works well for JSON-RPC, but it is not as clean as a transport-agnostic event envelope.
|
||||
|
||||
Why it matters for Fabro:
|
||||
|
||||
- If Fabro needs both a high-level SDK and a low-level protocol, document the layering explicitly.
|
||||
- If Fabro only needs one event stream, a single canonical envelope is simpler than method-shaped notifications.
|
||||
|
||||
Sources:
|
||||
|
||||
- `/Users/bhelmkamp/p/openai/codex/sdk/typescript/src/events.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/sdk/typescript/src/items.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/sdk/typescript/src/thread.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/ServerNotification.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/src/protocol/common.rs`
|
||||
- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/TurnStartedNotification.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/TurnCompletedNotification.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/AgentMessageDeltaNotification.ts`
|
||||
- `/Users/bhelmkamp/p/openai/codex/codex-rs/app-server-protocol/schema/typescript/v2/CommandExecOutputDeltaNotification.ts`
|
||||
|
||||
### OpenCode
|
||||
|
||||
Schema shape:
|
||||
|
||||
- One generated `Event` union with 45 variants.
|
||||
- `GlobalEvent` adds `directory` plus `payload: Event`.
|
||||
- Events use `type` plus a `properties` object.
|
||||
- Coverage includes questions, permissions, messages, message parts, session status/idle/compacted/error/diff, workspace readiness, PTYs, worktrees, VCS, file edits, MCP, TUI commands, and more.
|
||||
|
||||
What it does well:
|
||||
|
||||
- Broad coverage.
|
||||
- Generated API types from the server surface.
|
||||
- Clear split between session-scoped events and global events.
|
||||
- Status is partly structured. `SessionStatus` is a union of `idle`, `retry`, and `busy`.
|
||||
|
||||
What is weak:
|
||||
|
||||
- No universal event ID.
|
||||
- No universal timestamp.
|
||||
- No replay cursor or sequence field.
|
||||
- The wire stream emits `server.heartbeat`, but the generated `Event` union does not include it.
|
||||
- The global event schema says `directory` is present, but the initial global `server.connected` and heartbeat frames omit it.
|
||||
|
||||
Why it matters for Fabro:
|
||||
|
||||
- OpenCode shows how far a generated event surface can go.
|
||||
- It also shows the cost of not having a canonical envelope: clients must reconstruct correlation from nested `sessionID`, `messageID`, `partID`, and route-specific wrappers.
|
||||
|
||||
Sources:
|
||||
|
||||
- `/Users/bhelmkamp/p/anomalyco/opencode/packages/sdk/js/src/v2/gen/types.gen.ts`
|
||||
- `/Users/bhelmkamp/p/anomalyco/opencode/packages/sdk/js/src/v2/gen/core/serverSentEvents.gen.ts`
|
||||
- `/Users/bhelmkamp/p/anomalyco/opencode/packages/opencode/src/server/server.ts`
|
||||
- `/Users/bhelmkamp/p/anomalyco/opencode/packages/opencode/src/server/routes/global.ts`
|
||||
- `/Users/bhelmkamp/p/anomalyco/opencode/packages/opencode/src/server/event.ts`
|
||||
- `/Users/bhelmkamp/p/anomalyco/opencode/packages/web/src/content/docs/server.mdx`
|
||||
|
||||
### pi-mono
|
||||
|
||||
Schema shape:
|
||||
|
||||
- `AssistantMessageEvent` has 12 streaming variants: `start`, block start/delta/end for text, thinking, and tool calls, then `done` or `error`.
|
||||
- `AgentEvent` has 10 lifecycle variants across agent, turn, message, and tool execution.
|
||||
- `AgentSessionEvent` extends `AgentEvent` with 4 session-only retry/compaction events.
|
||||
- JSON mode starts with a session header, then emits JSONL events.
|
||||
|
||||
What it does well:
|
||||
|
||||
- Excellent streaming lifecycle grammar.
|
||||
- Strong layering:
|
||||
- low-level assistant stream events
|
||||
- mid-level agent lifecycle events
|
||||
- high-level session events
|
||||
- The proxy mode has a bandwidth-optimized streaming shape that intentionally strips partial message snapshots and reconstructs them client-side.
|
||||
|
||||
What is weak:
|
||||
|
||||
- There is no universal per-event envelope.
|
||||
- There are no event IDs or replay semantics.
|
||||
- Timestamping is inconsistent. The session header has a timestamp, and some embedded message objects have timestamps, but not every event line does.
|
||||
|
||||
Why it matters for Fabro:
|
||||
|
||||
- pi-mono is the best example here for event layering and start/delta/end/done grammar.
|
||||
- Fabro should borrow that lifecycle discipline if it expands live agent streaming, but keep Fabro's stronger envelope.
|
||||
|
||||
Sources:
|
||||
|
||||
- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/ai/src/types.ts`
|
||||
- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/agent/src/types.ts`
|
||||
- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/agent/src/proxy.ts`
|
||||
- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/coding-agent/src/core/agent-session.ts`
|
||||
- `/Users/bhelmkamp/p/badlogic/pi-mono/packages/coding-agent/docs/json.md`
|
||||
|
||||
## Cross-System Patterns
|
||||
|
||||
### Patterns worth copying
|
||||
|
||||
- One obvious discriminator per public event.
|
||||
- Explicit unions for error state, stop reason, retry state, and requires-action state.
|
||||
- Stable correlation IDs for session/thread/turn/message/tool levels.
|
||||
- A documented replay story for long-running streams.
|
||||
- Generated public schemas from one source of truth.
|
||||
- A clear distinction between snapshot events and delta events.
|
||||
|
||||
### Patterns worth avoiding
|
||||
|
||||
- Opaque `unknown` payloads inside otherwise typed events.
|
||||
- Server-injected fields that the public schema does not model.
|
||||
- Mixing keep-alives, control RPCs, and domain events in one event contract.
|
||||
- Event systems that only make sense in the context of one transport, for example JSON-RPC `method`/`params`, when the real need is a transport-agnostic event log.
|
||||
- No universal ID or timestamp on durable events.
|
||||
|
||||
## Recommendations For Fabro
|
||||
|
||||
### 1. Keep the canonical envelope
|
||||
|
||||
Fabro should keep `id`, `ts`, `run_id`, `event`, `session_id`, `parent_session_id`, `node_id`, and `node_label` exactly as the backbone of the public schema. That is already better than every comparator except Claude Sessions on consistency.
|
||||
|
||||
### 2. Do not let transport metadata leak informally
|
||||
|
||||
If Fabro supports SSE replay or live reattach, define transport rules explicitly:
|
||||
|
||||
- SSE `id`
|
||||
- replay cursor semantics
|
||||
- comment heartbeat vs payload heartbeat
|
||||
- reconnect guarantees
|
||||
|
||||
Do not make clients depend on extra fields injected by one server path that are absent from the formal schema.
|
||||
|
||||
### 3. Add deeper correlation IDs where the product needs them
|
||||
|
||||
Fabro already has run/session/node metadata. The next likely additions are:
|
||||
|
||||
- `turn_id`
|
||||
- `message_id`
|
||||
- `tool_call_id`
|
||||
- `request_id`
|
||||
- `attempt`
|
||||
|
||||
Those should be explicit schema fields, not encoded into ad hoc strings.
|
||||
|
||||
### 4. Prefer unions over stringly terminal state
|
||||
|
||||
If Fabro expands live session or agent events, model terminal and waiting states like Claude Sessions does:
|
||||
|
||||
- `stop_reason`
|
||||
- `retry_status`
|
||||
- `requires_action`
|
||||
- `error_kind`
|
||||
|
||||
Avoid free-form strings when a small tagged union will do.
|
||||
|
||||
### 5. Standardize lifecycle families
|
||||
|
||||
If Fabro emits live agent output, choose one lifecycle grammar and document it:
|
||||
|
||||
- `.started`
|
||||
- `.delta`
|
||||
- `.completed`
|
||||
- `.failed`
|
||||
|
||||
If snapshot replacement events also exist, mark them clearly and document when clients should treat them as authoritative replacement vs append-only updates.
|
||||
|
||||
### 6. Keep domain events separate from control and keep-alive traffic
|
||||
|
||||
Claude Code shows the downside of multiplexing control requests, control responses, keep-alives, and domain messages in one stream contract. Fabro's durable run events should stay product-facing and analyzable.
|
||||
|
||||
### 7. Add schema-drift tests for streamed events
|
||||
|
||||
OpenCode and Goose both show how easy it is for the wire stream to diverge from the published schema. Fabro should keep tests that validate:
|
||||
|
||||
- every emitted streamed payload is representable by the public schema
|
||||
- no consumer-visible fields are injected outside the schema
|
||||
- replay/heartbeat frames are documented and tested separately
|
||||
|
||||
## Bottom Line
|
||||
|
||||
Fabro does not need to copy any one competitor's schema wholesale.
|
||||
|
||||
The best composite design is:
|
||||
|
||||
- Claude Sessions' explicit unions for status and errors
|
||||
- Goose's replay semantics
|
||||
- Codex's separation between a simple high-level client view and a richer low-level view, if Fabro ever needs both
|
||||
- OpenCode's breadth of runtime events
|
||||
- pi-mono's streaming lifecycle grammar
|
||||
- Fabro's existing canonical envelope as the foundation
|
||||
|
||||
That combination would produce an event model that is both durable and ergonomic: good for live UI streaming, replay, analytics, tests, and long-term compatibility.
|
||||
|
|
@ -1,632 +0,0 @@
|
|||
# Fabro Event Schema V2 Proposal
|
||||
|
||||
Date: 2026-04-08
|
||||
|
||||
Status: proposal
|
||||
|
||||
Assumptions:
|
||||
|
||||
- greenfield redesign
|
||||
- no production deployments
|
||||
- no backward-compatibility constraints
|
||||
- optimize for the best long-term public event contract
|
||||
|
||||
This proposal turns the earlier ideation into concrete schema changes.
|
||||
|
||||
## Design Goal
|
||||
|
||||
Fabro should expose:
|
||||
|
||||
1. a durable, append-only event log for audit, storage, replay, and projections
|
||||
2. a separate live stream for UI-oriented snapshots, deltas, and fast progress
|
||||
|
||||
They should share IDs and correlation fields, but they should not be the same contract.
|
||||
|
||||
## Top 10 Concrete Improvements
|
||||
|
||||
### 1. Split the single event story into two concrete public APIs
|
||||
|
||||
#### Proposal
|
||||
|
||||
Introduce two top-level event contracts:
|
||||
|
||||
- `DurableEvent`
|
||||
- `LiveEvent`
|
||||
|
||||
Endpoints:
|
||||
|
||||
- `GET /runs/:run_id/events`
|
||||
- append-only durable events
|
||||
- replayable
|
||||
- no keep-alive payload events
|
||||
- `GET /runs/:run_id/live`
|
||||
- live UI stream
|
||||
- snapshots + deltas + keep-alives
|
||||
- resumable with cursor
|
||||
|
||||
#### Durable event shape
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "durable",
|
||||
"id": "evt_01960d0c...",
|
||||
"seq": 182,
|
||||
"ts": "2026-04-08T15:01:02.123Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"event": "agent.tool.started",
|
||||
"session_id": "ses_123",
|
||||
"node_id": "code",
|
||||
"properties": {
|
||||
"tool_call_id": "tool_abc",
|
||||
"tool_name": "read_file",
|
||||
"arguments": { "path": "src/main.rs" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Live event shape
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "live",
|
||||
"id": "levt_01960d0d...",
|
||||
"seq": 991,
|
||||
"ts": "2026-04-08T15:01:03.000Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"event": "message.delta",
|
||||
"session_id": "ses_123",
|
||||
"message_id": "msg_456",
|
||||
"part_id": "part_1",
|
||||
"properties": {
|
||||
"block_type": "text",
|
||||
"delta": "Let me check that file..."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Durable events stay stable and analyzable.
|
||||
- Live events can be noisy and UI-oriented without polluting projections.
|
||||
- Keeps Fabro from repeating the Claude Code / OpenCode problem of mixing control, transport, and product semantics.
|
||||
|
||||
### 2. Add explicit stream ordering, replay, and recovery semantics
|
||||
|
||||
#### Proposal
|
||||
|
||||
Every durable and live stream event gets:
|
||||
|
||||
- `seq: u64`
|
||||
- SSE `id:` = `seq`
|
||||
- replay semantics based on `Last-Event-ID`
|
||||
|
||||
Server rules:
|
||||
|
||||
- if `Last-Event-ID` is present and still buffered, replay `seq > cursor`
|
||||
- if cursor is too old, return a structured reset event in live streams and `409 replay_reset_required` in durable streams
|
||||
- durable streams never emit synthetic snapshots
|
||||
- live streams may start with a `*.snapshot` event after reconnect
|
||||
|
||||
#### New live-only events
|
||||
|
||||
- `stream.heartbeat`
|
||||
- `run.snapshot`
|
||||
- `session.snapshot`
|
||||
- `node.snapshot`
|
||||
- `stream.reset_required`
|
||||
|
||||
#### Example `stream.reset_required`
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "live",
|
||||
"id": "levt_01960d0e...",
|
||||
"seq": 1200,
|
||||
"ts": "2026-04-08T15:02:00.000Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"event": "stream.reset_required",
|
||||
"properties": {
|
||||
"reason": "cursor_too_old",
|
||||
"expected_from_seq": 1170
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Reattach behavior becomes deterministic.
|
||||
- Clients no longer guess whether they missed data.
|
||||
- Replay is part of the contract, not an implementation detail.
|
||||
|
||||
### 3. Expand the envelope into a first-class correlation model
|
||||
|
||||
#### Proposal
|
||||
|
||||
Extend the shared envelope with these optional fields:
|
||||
|
||||
- `workflow_id`
|
||||
- `stage_id`
|
||||
- `branch_id`
|
||||
- `checkpoint_id`
|
||||
- `session_id`
|
||||
- `parent_session_id`
|
||||
- `turn_id`
|
||||
- `message_id`
|
||||
- `part_id`
|
||||
- `tool_call_id`
|
||||
- `request_id`
|
||||
- `causation_id`
|
||||
- `correlation_id`
|
||||
|
||||
Rules:
|
||||
|
||||
- `id` is the event's own identity
|
||||
- `causation_id` points to the immediate triggering event, if any
|
||||
- `correlation_id` groups a whole logical operation, for example one user request or one retry attempt tree
|
||||
- `request_id` is transport/API request scoped, not workflow scoped
|
||||
|
||||
#### Concrete change
|
||||
|
||||
Move these IDs out of ad hoc `properties` payloads when they are structural identifiers.
|
||||
|
||||
Good:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "agent.tool.completed",
|
||||
"tool_call_id": "tool_abc",
|
||||
"message_id": "msg_456",
|
||||
"properties": {
|
||||
"tool_name": "read_file",
|
||||
"is_error": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Bad:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "agent.tool.completed",
|
||||
"properties": {
|
||||
"tool_call_id": "tool_abc",
|
||||
"message_id": "msg_456",
|
||||
"tool_name": "read_file"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Correlation becomes universal instead of event-family-specific.
|
||||
- UI and analytics consumers can join without parsing `properties`.
|
||||
- Parent/child agent and retry trees become much easier to reason about.
|
||||
|
||||
### 4. Replace stringly state with concrete tagged unions
|
||||
|
||||
#### Proposal
|
||||
|
||||
Define explicit union types for stateful fields.
|
||||
|
||||
Examples:
|
||||
|
||||
```ts
|
||||
type StopReason =
|
||||
| { type: "completed" }
|
||||
| { type: "requires_input"; request_id: string }
|
||||
| { type: "interrupted"; interrupt_reason: InterruptReason }
|
||||
| { type: "failed"; error_kind: ErrorKind }
|
||||
| { type: "retries_exhausted"; attempts: number };
|
||||
|
||||
type RetryStatus =
|
||||
| { type: "not_retrying" }
|
||||
| { type: "retry_scheduled"; attempt: number; next_retry_at: string }
|
||||
| { type: "retrying"; attempt: number }
|
||||
| { type: "retries_exhausted"; attempts: number };
|
||||
|
||||
type ApprovalStatus =
|
||||
| { type: "not_required" }
|
||||
| { type: "requested"; approval_id: string }
|
||||
| { type: "approved"; approval_id: string; actor: string }
|
||||
| { type: "denied"; approval_id: string; actor: string; reason?: string };
|
||||
```
|
||||
|
||||
#### Concrete fields to replace
|
||||
|
||||
- `status`
|
||||
- `reason`
|
||||
- `failure_class`
|
||||
- `interrupt_reason`
|
||||
- `stop_reason`
|
||||
- `approval_status`
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Eliminates string drift.
|
||||
- Makes reducers and policy engines much safer.
|
||||
- Makes test fixtures much more stable.
|
||||
|
||||
### 5. Standardize event family grammar across the entire product
|
||||
|
||||
#### Proposal
|
||||
|
||||
Use one lifecycle vocabulary:
|
||||
|
||||
- `.created`
|
||||
- `.started`
|
||||
- `.snapshot`
|
||||
- `.delta`
|
||||
- `.updated`
|
||||
- `.completed`
|
||||
- `.failed`
|
||||
- `.cancelled`
|
||||
- `.interrupted`
|
||||
- `.deleted`
|
||||
|
||||
Apply it consistently to the same kinds of things:
|
||||
|
||||
- `run.*`
|
||||
- `stage.*`
|
||||
- `session.*`
|
||||
- `turn.*`
|
||||
- `message.*`
|
||||
- `message.part.*`
|
||||
- `tool.*`
|
||||
- `command.*`
|
||||
- `checkpoint.*`
|
||||
- `parallel.branch.*`
|
||||
- `retro.*`
|
||||
|
||||
#### Concrete renames
|
||||
|
||||
Current style is already decent, but V2 should be stricter.
|
||||
|
||||
Examples:
|
||||
|
||||
- `agent.text.delta` -> `message.part.delta`
|
||||
- `agent.tool.output.delta` -> `tool.output.delta`
|
||||
- `agent.processing.end` -> `turn.completed` or `session.idle`, depending on actual semantics
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Consumers can infer behavior from naming alone.
|
||||
- Reduces one-off event families that encode bespoke lifecycle semantics.
|
||||
|
||||
### 6. Introduce typed content blocks and block-level deltas
|
||||
|
||||
#### Proposal
|
||||
|
||||
Represent streamable content as typed message parts.
|
||||
|
||||
Base union:
|
||||
|
||||
```ts
|
||||
type MessagePart =
|
||||
| { type: "text"; part_id: string; text: string }
|
||||
| { type: "reasoning"; part_id: string; text: string }
|
||||
| { type: "tool_call"; part_id: string; tool_call_id: string; tool_name: string; input: unknown }
|
||||
| { type: "tool_result"; part_id: string; tool_call_id: string; output: unknown; is_error: boolean }
|
||||
| { type: "patch"; part_id: string; patch_ref: string }
|
||||
| { type: "file_ref"; part_id: string; file_id: string; path: string }
|
||||
| { type: "artifact_ref"; part_id: string; artifact_id: string; label: string }
|
||||
| { type: "plan"; part_id: string; items: PlanItem[] }
|
||||
| { type: "todo"; part_id: string; items: TodoItem[] }
|
||||
| { type: "command_output"; part_id: string; command_id: string; stream: "stdout" | "stderr"; text: string };
|
||||
```
|
||||
|
||||
Live delta event:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "message.part.delta",
|
||||
"message_id": "msg_456",
|
||||
"part_id": "part_1",
|
||||
"properties": {
|
||||
"part_type": "text",
|
||||
"delta": "checking src/main.rs"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Durable completion event:
|
||||
|
||||
```json
|
||||
{
|
||||
"event": "message.completed",
|
||||
"message_id": "msg_456",
|
||||
"properties": {
|
||||
"parts": [
|
||||
{ "type": "text", "part_id": "part_1", "text": "checking src/main.rs" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Supports rich UI without reparsing free-form text.
|
||||
- Supports structured summarization, compaction, and retro generation.
|
||||
- Aligns Fabro with the best parts of Claude Sessions and pi-mono.
|
||||
|
||||
### 7. Make approvals, questions, and operator interventions first-class durable events
|
||||
|
||||
#### Proposal
|
||||
|
||||
Add explicit event families:
|
||||
|
||||
- `approval.requested`
|
||||
- `approval.responded`
|
||||
- `question.asked`
|
||||
- `question.answered`
|
||||
- `interrupt.requested`
|
||||
- `interrupt.applied`
|
||||
- `resume.required`
|
||||
- `resume.applied`
|
||||
|
||||
#### Example `approval.requested`
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "durable",
|
||||
"id": "evt_01960d0f...",
|
||||
"seq": 201,
|
||||
"ts": "2026-04-08T15:03:00.000Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"session_id": "ses_123",
|
||||
"tool_call_id": "tool_abc",
|
||||
"event": "approval.requested",
|
||||
"properties": {
|
||||
"approval_id": "apr_1",
|
||||
"scope": "tool_call",
|
||||
"tool_name": "exec_command",
|
||||
"request": {
|
||||
"cmd": "git push origin branch"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example `approval.responded`
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "durable",
|
||||
"id": "evt_01960d10...",
|
||||
"seq": 202,
|
||||
"ts": "2026-04-08T15:03:10.000Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"event": "approval.responded",
|
||||
"properties": {
|
||||
"approval_id": "apr_1",
|
||||
"result": {
|
||||
"type": "approved",
|
||||
"actor": "user"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Human-in-loop behavior becomes queryable and replayable.
|
||||
- Workflow interruption is no longer hidden in transport or UI state.
|
||||
|
||||
### 8. Add real snapshot events instead of relying on ad hoc reconstruction
|
||||
|
||||
#### Proposal
|
||||
|
||||
Define explicit snapshot events for live attach and projection recovery:
|
||||
|
||||
- `run.snapshot`
|
||||
- `session.snapshot`
|
||||
- `node.snapshot`
|
||||
- `checkpoint.saved`
|
||||
|
||||
#### Example `session.snapshot`
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "live",
|
||||
"id": "levt_01960d11...",
|
||||
"seq": 1500,
|
||||
"ts": "2026-04-08T15:04:00.000Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"session_id": "ses_123",
|
||||
"event": "session.snapshot",
|
||||
"properties": {
|
||||
"state": { "type": "running" },
|
||||
"turn_id": "turn_9",
|
||||
"messages": [
|
||||
{
|
||||
"message_id": "msg_456",
|
||||
"role": "assistant",
|
||||
"parts": [
|
||||
{ "type": "text", "part_id": "part_1", "text": "checking src/main.rs" }
|
||||
]
|
||||
}
|
||||
],
|
||||
"active_tool_calls": [
|
||||
{
|
||||
"tool_call_id": "tool_abc",
|
||||
"tool_name": "read_file",
|
||||
"status": "running"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Concrete rule
|
||||
|
||||
- snapshots are authoritative replacement state for live consumers
|
||||
- snapshots are optional in durable streams
|
||||
- checkpoints are durable domain snapshots, not just UI snapshots
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Fast attach becomes trivial.
|
||||
- Projections can self-heal from snapshots.
|
||||
- Checkpoint semantics become explicit rather than emergent.
|
||||
|
||||
### 9. Make model, tool, command, and MCP work first-class span families
|
||||
|
||||
#### Proposal
|
||||
|
||||
Create event families with shared semantics:
|
||||
|
||||
- `model.request.started`
|
||||
- `model.request.completed`
|
||||
- `model.request.failed`
|
||||
- `tool.started`
|
||||
- `tool.output.delta`
|
||||
- `tool.completed`
|
||||
- `tool.failed`
|
||||
- `command.started`
|
||||
- `command.output.delta`
|
||||
- `command.completed`
|
||||
- `command.failed`
|
||||
- `mcp.call.started`
|
||||
- `mcp.call.progress`
|
||||
- `mcp.call.completed`
|
||||
- `mcp.call.failed`
|
||||
|
||||
#### Example `model.request.completed`
|
||||
|
||||
```json
|
||||
{
|
||||
"kind": "durable",
|
||||
"id": "evt_01960d12...",
|
||||
"seq": 220,
|
||||
"ts": "2026-04-08T15:05:00.000Z",
|
||||
"run_id": "run_01JQ...",
|
||||
"session_id": "ses_123",
|
||||
"turn_id": "turn_9",
|
||||
"request_id": "req_llm_1",
|
||||
"event": "model.request.completed",
|
||||
"properties": {
|
||||
"provider": "anthropic",
|
||||
"model": "claude-sonnet-4",
|
||||
"latency_ms": 1834,
|
||||
"usage": {
|
||||
"input_tokens": 1400,
|
||||
"output_tokens": 380,
|
||||
"reasoning_tokens": 120,
|
||||
"cache_read_tokens": 900,
|
||||
"cache_write_tokens": 0
|
||||
},
|
||||
"retry_status": { "type": "not_retrying" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Cost and latency analysis become first-class.
|
||||
- Policy engines can reason about real operations, not just stage summaries.
|
||||
- Cross-provider comparison gets much easier.
|
||||
|
||||
### 10. Generate and enforce the public schema, docs, and examples from one registry
|
||||
|
||||
#### Proposal
|
||||
|
||||
Build a single `event_schema_registry` source that defines:
|
||||
|
||||
- envelope fields
|
||||
- event families
|
||||
- payload types
|
||||
- union types
|
||||
- versioning
|
||||
- example payloads
|
||||
|
||||
Artifacts generated from it:
|
||||
|
||||
- Rust types
|
||||
- TypeScript types
|
||||
- JSON Schema
|
||||
- OpenAPI / SSE docs
|
||||
- sample event fixtures
|
||||
- validation tests
|
||||
|
||||
#### Concrete rules
|
||||
|
||||
- every public event must have:
|
||||
- one schema definition
|
||||
- one example payload
|
||||
- one validation test
|
||||
- no endpoint may inject extra consumer-visible fields outside the schema
|
||||
- keep-alive frames are documented separately from payload events
|
||||
|
||||
#### Why this is better
|
||||
|
||||
- Prevents the OpenCode and Goose class of drift.
|
||||
- Makes Fabro's event API publishable and stable from day one.
|
||||
|
||||
## Recommended V2 Event Families
|
||||
|
||||
If Fabro were starting from scratch, I would structure the public families like this:
|
||||
|
||||
- `run.*`
|
||||
- `stage.*`
|
||||
- `checkpoint.*`
|
||||
- `parallel.branch.*`
|
||||
- `session.*`
|
||||
- `turn.*`
|
||||
- `message.*`
|
||||
- `message.part.*`
|
||||
- `model.request.*`
|
||||
- `tool.*`
|
||||
- `command.*`
|
||||
- `mcp.call.*`
|
||||
- `approval.*`
|
||||
- `question.*`
|
||||
- `interrupt.*`
|
||||
- `resume.*`
|
||||
- `compaction.*`
|
||||
- `retro.*`
|
||||
- `artifact.*`
|
||||
- `stream.*` (live only)
|
||||
|
||||
## Recommended Field Placement Rules
|
||||
|
||||
Top-level envelope:
|
||||
|
||||
- identity and correlation
|
||||
- ordering
|
||||
- timestamps
|
||||
- scope
|
||||
|
||||
`properties`:
|
||||
|
||||
- event-family-specific payload
|
||||
- business data
|
||||
- structured state payloads
|
||||
|
||||
Never in `properties` if they are structural:
|
||||
|
||||
- `run_id`
|
||||
- `seq`
|
||||
- `event`
|
||||
- `session_id`
|
||||
- `message_id`
|
||||
- `tool_call_id`
|
||||
- `request_id`
|
||||
- `causation_id`
|
||||
- `correlation_id`
|
||||
|
||||
## Bottom Line
|
||||
|
||||
The best greenfield version of Fabro is not "the current schema plus more events."
|
||||
|
||||
It is:
|
||||
|
||||
- separate durable and live contracts
|
||||
- replayable ordered streams
|
||||
- a richer envelope
|
||||
- typed state unions
|
||||
- typed content blocks
|
||||
- explicit snapshots
|
||||
- first-class HITL events
|
||||
- first-class span families
|
||||
- generated schema/docs/tests from one registry
|
||||
|
||||
That would give Fabro a better event platform than any of the compared systems.
|
||||
|
|
@ -1,254 +0,0 @@
|
|||
# Fabro MCP Server — QA Test Plan
|
||||
|
||||
> Historical manual QA results. The run-create source selectors and flat settings
|
||||
> below predate the registered-version contract. Current calls register file contents
|
||||
> with `fabro_workflow_version_create`, then pass `workflow_version_id`, an explicit
|
||||
> standalone `target`, and nested `args` to `fabro_run_create`. See
|
||||
> [the current MCP guide](../public/agents/mcp.mdx) for the supported contract.
|
||||
|
||||
One-time manual QA pass for the 5 tools exposed by `fabro-mcp-server`. Source of truth: `lib/apps/fabro-mcp-server/src/run_tools/`.
|
||||
|
||||
This plan is **not** a template for adding automated test coverage — it exists to drive a single hands-on sweep against a real running server. Tick boxes as scenarios pass; add notes inline for failures or surprising behavior. Open bugs/PRs for issues found; do not port these scenarios into the Rust test suite.
|
||||
|
||||
## Findings rollup
|
||||
|
||||
Live list of bugs and notable observations surfaced during the sweep. Each entry links back to the scenario where it was found.
|
||||
|
||||
### Bugs / mismatches
|
||||
None currently open.
|
||||
|
||||
### Rechecked / no longer open
|
||||
- **C18 — `fabro_run_create` shorthand schema/runtime mismatch**: fixed on 2026-05-22. `runs: ["sleeper"]` is now accepted as workflow-selector shorthand, object-form specs remain supported for create options, and `tools/list` advertises both item shapes. Covered by `fabro_run_create_tool_advertises_string_and_object_run_specs`, `stdio_server_initializes_and_lists_run_tools`, and `mcp_create_string_shorthand_deserializes_before_auth`.
|
||||
- **C4 — `inputs` schema/runtime mismatch**: fixed by narrowing MCP input values to scalar JSON (`string`, `boolean`, `integer`, `number`) and rejecting arrays/objects locally with scalar-only errors. Re-tested on 2026-05-11 against `127.0.0.1:32276`; `tools/list` now advertises scalar-only `inputs.additionalProperties`.
|
||||
- **C5 — Misleading null-input error message**: fixed. Re-tested on 2026-05-11; null now returns ``input `maybe` cannot be null; use a string, boolean, or number``.
|
||||
- **I7 / I9 — Misleading "Run not found." on terminal runs**: fixed on 2026-05-11 in the server API layer. `message`/steer against a durable terminal run that no longer has a live managed engine now returns `409` with `run_not_steerable`; `cancel` returns `409` with `Run is already terminal and cannot be cancelled.` True missing runs still return `404`.
|
||||
- **I10 — Archived runs not filtered from default search**: fixed on 2026-05-11 by aligning MCP search with the HTTP API. `fabro_run_search` now hides archived runs when `archived` is omitted, while `archived=true` still searches archived runs explicitly.
|
||||
- **I15 / I16 — yes/no answer flow**: re-tested on 2026-05-11 against `fabro server` `0.230.0-nightly.0` at `127.0.0.1:32276`. `answer=true` and `answer=false` both submit successfully for the bundled `interview` workflow's first `yes_no` question. `true` advanced the run to the next `confirmation` question.
|
||||
- **I22 — numeric answer local validation**: re-tested on 2026-05-11 against the same server. `answer=42` now returns `unsupported answer value: 42; expected boolean, string, or object` from the MCP layer before reaching the API.
|
||||
- **Section 2 side observation — Search payloads include full `goal` text**: fixed on 2026-05-11. `fabro_run_search` now returns bounded `goal_preview` plus `goal_truncated` instead of the full `goal`, keeping list responses compact while preserving full summaries on other run interactions.
|
||||
- **X6 — Cursor/filter ordering**: simplified on 2026-05-11 by applying search filters before sorting and applying the `after` cursor. This prevents unrelated runs outside the filtered result set from trimming the page. Pagination is explicitly not snapshot-isolated; a new matching run inserted before the cursor during traversal appears when the client starts a new search.
|
||||
|
||||
### UX / polish
|
||||
- **C12 — `cwd` errors don't distinguish "directory missing" from "workflow not in directory"**: both return `workflow not found: <slug>`.
|
||||
- **S9 (bonus) — Undocumented date format**: error message reveals `YYYY-MM-DD` is accepted alongside RFC3339, but the schema only says RFC3339.
|
||||
- **S17 — `run_ids` accepts more than IDs**: error message reveals it also matches ID prefixes and workflow names. Either rename the field or document.
|
||||
- **E4 — Events `search` is whole-envelope substring match**: search includes embedded payloads (workflow definitions, settings, sandbox dockerfile, etc.), so a search like `query="list_prs"` legitimately matches the `run.created` event because that event embeds the workflow JSON. Easy to misinterpret. Consider documenting or scoping search to event body only.
|
||||
|
||||
### Nice-to-haves
|
||||
- **C16 — Helpful error**: unknown workflow lists available workflows. Keep.
|
||||
|
||||
## Pre-flight (all tools)
|
||||
|
||||
- [ ] **P1** Server unreachable — stop `fabro server`, call any tool, expect a clear connection-error message (not a panic, not a hang).
|
||||
- [ ] **P2** Schema discovery — list tools through an MCP client; verify each tool has a complete JSON schema and the documented `anyOf` for `AnswerValue`.
|
||||
|
||||
---
|
||||
|
||||
## 1. `fabro_run_create`
|
||||
|
||||
Source: `run_tools/create.rs:124`
|
||||
|
||||
### Happy path
|
||||
- [x] **C1** Create one run from an existing workflow (e.g. `gh-list`); default `start=true` → expect `start_requested=true`, `status` in `{runnable, starting, running}`. — **PASS**. `status=runnable`.
|
||||
- [x] **C2** Create with `start=false` → expect `started=false`, `status=submitted`. — **PASS**. Run `01KRC4MP2NEQS9GJDE9FJ0EECH` kept as fixture for I3.
|
||||
- [x] **C3** Batch create 5 runs in one call → all return; result preserves array order. — **PASS**. ULIDs monotonically increasing.
|
||||
|
||||
### Inputs / manifest
|
||||
- [x] **C4** Pass `inputs` with string / number / boolean / nested object / array → **PASS** after 2026-05-11 recheck. Scalar values are accepted. Arrays and objects are rejected locally with scalar-only errors, and the MCP schema now advertises scalar-only `inputs` values.
|
||||
- [x] **C5** `inputs` containing `null` → **PASS** after 2026-05-11 recheck. Returns ``input `maybe` cannot be null; use a string, boolean, or number``.
|
||||
- [x] **C6** `labels={"team": "qa"}` round-trip via search. — **PASS**. All 5 C3 runs returned with labels intact.
|
||||
- [x] **C7** Optional flags: `goal`, `model+provider`, `sandbox`, `preserve_sandbox+auto_approve+dry_run`. — **PASS** all accepted; `goal` override round-tripped via search.
|
||||
- [x] **C8** Custom `run_id`: valid ULID accepted (`01KRC500000000C8TEST00000A`); wrong length → `invalid length`; invalid Crockford char (e.g. `U`) → `invalid character`. — **PASS**.
|
||||
|
||||
### `cwd`
|
||||
- [x] **C9** Omit `cwd` → uses base CWD. — **PASS** (covered by every prior scenario).
|
||||
- [x] **C10** `cwd` to repo root resolves workflow. — **PASS**.
|
||||
- [x] **C11** `cwd=/tmp` (no `.fabro/workflows`) → `workflow not found: gh-list`. — **PASS**.
|
||||
- [x] **C12** `cwd=/this/path/does/not/exist/xyz123` → same generic `workflow not found: gh-list`. — **PASS but note**: error doesn't distinguish "directory missing" from "workflow not in directory". Minor UX gap.
|
||||
|
||||
### Validation
|
||||
- [x] **C13** Empty `runs: []` → `runs must contain at least 1 item(s)`. — **PASS**.
|
||||
- [x] **C14** 51 entries → `runs must contain no more than 50 item(s)`. — **PASS**.
|
||||
- [x] **C15** Missing required `workflow` → MCP layer `-32602: missing field 'workflow'`. — **PASS**.
|
||||
- [x] **C16** Unknown workflow slug → `Unknown workflow 'X'\n\nAvailable workflows: ...`. — **PASS** (very helpful — lists available workflows).
|
||||
- [x] **C18** String shorthand `runs: ["gh-list"]` → accepted as the workflow selector. `tools/list` should show `runs.items.anyOf` with both a string branch and an object branch requiring `workflow`. — **COVERED by automated regression tests added 2026-05-22**.
|
||||
|
||||
### Failure semantics
|
||||
- [x] **C17** Invalid sandbox name → `failed to resolve manifest settings: run.sandbox.provider: invalid value - unknown sandbox provider: this-sandbox-does-not-exist`. — **PASS**. Error raised at manifest-resolve time before any run record is created (no orphaned submitted run).
|
||||
|
||||
---
|
||||
|
||||
## 2. `fabro_run_search`
|
||||
|
||||
Source: `run_tools/search.rs:75`
|
||||
|
||||
### Happy path
|
||||
- [x] **S1** No params → returns up to 20 runs, sorted by `started_at OR created_at` desc. — **PASS**. Mixed-timestamp ordering correct (succeeded run at pos 8 sorts by its `started_at` between two `created_at`-only runs).
|
||||
- [x] **S2** `first=5` → exactly 5; `next_cursor` is the last run's ID. — **PASS**.
|
||||
- [x] **S3** `first=100` → all 17 runs, `next_cursor=null`. — **PASS**.
|
||||
- [x] **S4** Cursor follow-through: page 1 IDs `[A, B]`, page 2 with `after=B` returns `[C, D]`. No overlap. — **PASS**. Note: cursors are run IDs, not opaque tokens.
|
||||
|
||||
### Filters
|
||||
- [x] **S5** `workflow="smoke"` (slug) and `workflow="Smoke"` (name) both match same run. — **PASS**.
|
||||
- [x] **S6** `status=["succeeded"]` → 4; `["failed","dead"]` → 1; `["submitted"]` → 5. — **PASS**.
|
||||
- [x] **S7** Labels round-trip. — **PASS** (verified via C6).
|
||||
- [x] **S8** `archived=false` → all unarchived runs; `archived=true` → `[]` (no archived runs yet). Re-verify after I10. — **PARTIAL** (no archived fixtures yet).
|
||||
- [x] **S9** `created_after`/`created_before` (RFC3339) bound results correctly; tight window `17:00–18:00` returns only old runs. — **PASS**. **Bonus**: error message reveals `YYYY-MM-DD` is also accepted — undocumented in the schema.
|
||||
- [x] **S10** `run_ids=[A,B,A]` → 2 deduped runs. — **PASS**.
|
||||
- [x] **S11** Combined `workflow + status + labels + archived` → returns exactly the 5 batch=c3 runs. — **PASS**.
|
||||
|
||||
### Validation
|
||||
- [x] **S12** `first=101` → `first must be <= 100`. — **PASS**.
|
||||
- [x] **S13** `run_ids=[]` → `run_ids must contain at least 1 item(s)`. — **PASS**.
|
||||
- [x] **S14** `run_ids` length 101 → `run_ids must contain no more than 100 item(s)`. — **PASS**.
|
||||
- [x] **S15** `status=["bogus"]` → `unknown run status 'bogus'`. — **PASS**.
|
||||
- [x] **S16** `created_after="not-a-date"` → `created_after must be RFC3339 or YYYY-MM-DD: input contains invalid characters`. — **PASS**.
|
||||
|
||||
### Edge cases
|
||||
- [x] **S17** Non-existent ID in `run_ids` → `No run found matching '<ID>' (tried run ID prefix and workflow name)`. — **PASS** + **finding**: `run_ids` also accepts ID prefixes and workflow names, which is broader than the field name suggests.
|
||||
- [x] **S18** No matches → `{"runs": [], "next_cursor": null}`. — **PASS**.
|
||||
- [x] **S19** Bogus `after=<unknown>` → returns full first page (skip never applies). — **PASS** as documented.
|
||||
|
||||
### Side observation
|
||||
Search responses include the full `goal` text per run; a single `ImplementPlan` run can add ~30 KB to every search payload. Consider truncating `goal` (or excluding it from list responses) the way events have `max_content_length`. **Logged in Findings.**
|
||||
|
||||
---
|
||||
|
||||
## 3. `fabro_run_gather`
|
||||
|
||||
Source: `run_tools/gather.rs:56`
|
||||
|
||||
### Happy path
|
||||
- [x] **G1** Gather 1 already-terminal run → instant return, `timed_out=false`, `elapsed_seconds=0`. — **PASS**.
|
||||
- [x] **G2** In-flight `gh-list` with `timeout=60, poll=5` → reaches `succeeded`, `timed_out=false`, `elapsed=30`. — **PASS**.
|
||||
- [x] **G3** In-flight `gh-list` with `timeout=5, poll=5` → `timed_out=true`, `elapsed=5`, run still `starting`. — **PASS**.
|
||||
- [x] **G4** Mix of 2 terminal + 1 in-flight, `timeout=90, poll=5` → all 3 succeeded, `timed_out=false`, `elapsed=40`. — **PASS**.
|
||||
|
||||
### Validation
|
||||
- [x] **G5** `run_ids=[]` → `run_ids must contain at least 1 item(s)`. — **PASS**.
|
||||
- [x] **G6** 51 IDs → `run_ids must contain no more than 50 item(s)`. — **PASS**.
|
||||
- [x] **G7** `timeout_seconds=601` → `timeout_seconds must be <= 600`. — **PASS**.
|
||||
- [x] **G8** `poll_interval_seconds=4` → `poll_interval_seconds must be >= 5`. — **PASS**.
|
||||
- [x] **G9** Omit both → call accepted; terminal run still returns instantly. Default values per source: `timeout=300, poll=15`. — **PASS**.
|
||||
|
||||
### Edge cases
|
||||
- [x] **G10** Non-existent run ID → `No run found matching '<ID>' (tried run ID prefix and workflow name)`. — **PASS** (same fuzzy match as search).
|
||||
- [x] **G11** Poll cadence: G3 confirms last sleep clamps to deadline (`elapsed=5` exactly with `timeout=5, poll=5`). — **PASS** (inferred from G2/G3 timing).
|
||||
- [ ] **G12** Run cancelled mid-gather → terminal `failed(status_reason=cancelled)` quickly. — **DEFERRED** to after I8 (cancel).
|
||||
- [ ] **G13** Run becomes `blocked` — verify gather still waits. — **DEFERRED** to after Section 5 (interview workflow).
|
||||
|
||||
---
|
||||
|
||||
## 4. `fabro_run_events`
|
||||
|
||||
Source: `run_tools/events.rs:115`
|
||||
|
||||
### Actions
|
||||
- [x] **E1** `list` no filters → 45 events (`gh-list` has full lifecycle: run.*, sandbox.*, git.*, stage.*, etc.), `next_cursor=46`. — **PASS**.
|
||||
- [x] **E2** `details` with 2 event_ids → returns exactly those 2 envelopes. — **PASS**.
|
||||
- [x] **E3** `details` with no `event_ids` → `event_ids is required for details action`. — **PASS**.
|
||||
- [x] **E4** `search query="list_prs"` → 14 events. Includes `run.created` because it embeds the full workflow definition (which contains the `list_prs` node ID). — **PASS** + **observation**: search ranges over the entire serialized envelope, so big embedded payloads (workflow defs, settings) can produce non-obvious hits.
|
||||
- [x] **E5** `search` with missing `query` → `query is required for search action`. — **PASS**.
|
||||
|
||||
### Filters
|
||||
- [x] **E6** `event_types=["stage.started"]` → exactly 4 events (start, list_prs, list_issues, exit). — **PASS**.
|
||||
- [x] **E7** `categories=["git","sandbox"]` → 12 events all with prefix `git.*` or `sandbox.*`. — **PASS**.
|
||||
- [x] **E8** `created_after=17:03:10Z` + `created_before=17:03:13Z` → 5 events all timestamped 17:03:12.89x. — **PASS**.
|
||||
- [x] **E9** Combined `event_types + offset + first` covered by E14.
|
||||
|
||||
### Pagination & direction
|
||||
- [x] **E10** Page 1 `first=10` → seqs 1–10, `next_cursor=11`. Page 2 `after=11, first=5` → seqs 11–15, `next_cursor=16`. No duplicates; contiguous. — **PASS**.
|
||||
- [x] **E11** `direction=desc, first=5` → seqs 45, 44, 43, 42, 41; `next_cursor=41` (last seq, no +1 — per the desc branch). — **PASS**.
|
||||
- [x] **E12** Default direction = asc (E10 confirms). — **PASS**.
|
||||
- [x] **E13** `direction="weird"` → `direction must be 'asc' or 'desc'`. — **PASS**.
|
||||
- [x] **E14** `event_types=["stage.started"], offset=2, first=5` → returned 2 events (seqs 29, 39) — correctly skipped the first 2 (15, 19) of the 4 matching. — **PASS**.
|
||||
- [x] **E15** `limit=3` → 3 events. — **PASS** (alias works).
|
||||
|
||||
### Truncation
|
||||
- [x] **E16** `stage.completed, first=1, max_content_length=200` → 1 event, `truncated=true`, `event` is a JSON string. — **PASS**.
|
||||
- [x] **E17** UTF-8 boundary — **VERIFIED via existing unit test** at `events.rs:269-312`. Can't easily reproduce through MCP surface (no multibyte event content in default fixtures).
|
||||
- [x] **E18** Default `max_content_length=20000` → all 5 events `truncated=false` (including the ~5 KB `run.created`). — **PASS**.
|
||||
|
||||
### Validation
|
||||
- [x] **E19** `run_id=" "` (whitespace) → `run_id is required`. — **PASS**.
|
||||
- [x] **E20** `first=201` → `first must be <= 200`. — **PASS**.
|
||||
- [x] **E21** Non-existent run ID → fuzzy-match error (same as search/gather). — **PASS**.
|
||||
|
||||
---
|
||||
|
||||
## 5. `fabro_run_interact`
|
||||
|
||||
Source: `run_tools/interact.rs:201`
|
||||
|
||||
### Actions
|
||||
|
||||
#### `get`
|
||||
- [x] **I1** Returns `{summary, projection}`; projection includes `spec`, `graph`, `status`, `checkpoints`, `pending_interviews`, `stages`, `sandbox`, `conclusion`, etc. — **PASS**.
|
||||
- [x] **I2** Non-existent run → fuzzy match error. — **PASS**.
|
||||
|
||||
#### `start`
|
||||
- [x] **I3** Non-started run (from C2) → `start` transitions to `runnable`. Second `start` → `start has already been requested for this run`. — **PASS**.
|
||||
|
||||
#### `message` (steer)
|
||||
- [ ] **I4** Steer a running LLM agent — **DEFERRED** (requires an active LLM agent stage; would burn LLM tokens; can be exercised manually once the answer bug below is resolved).
|
||||
- [ ] **I5** `interrupt=true` — **DEFERRED** along with I4.
|
||||
- [x] **I6** Missing `message` → `message is required for action message`. — **PASS**.
|
||||
- [x] **I7** Message a terminal run → initially returned `Run not found.`. — **FIXED**: durable terminal runs without a live managed engine now return `409 run_not_steerable`; true missing runs remain `404`.
|
||||
|
||||
#### `cancel`
|
||||
- [x] **I8** Cancel a `gh-list` run during `starting`. Returns summary at request time (status=`starting`). Subsequent `gather` returned terminal `failed` within 5s; `get` projection shows `status: {kind: "failed", reason: "cancelled"}` and `conclusion.failure_reason: "Pipeline cancelled"`. — **PASS** + **observation**: `cancel`'s returned summary is a snapshot at request time, not the eventual terminal status.
|
||||
- [x] **I9** Cancel an already-terminal run → initially returned `Run not found.`. — **FIXED**: durable terminal runs without a live managed engine now return `409` with `Run is already terminal and cannot be cancelled.`; true missing runs remain `404`.
|
||||
|
||||
#### `archive` / `unarchive`
|
||||
- [x] **I10** Archive terminal run → `archived=true` in summary; visible via `search archived=true`. — **FIXED**: default search now hides archived runs to match `/api/v1/runs`; `archived=true` still surfaces archived runs explicitly.
|
||||
- [x] **I11** Unarchive → reverses (`archived=false`). — **PASS**.
|
||||
- [x] **I12** Archive an active run → `run <id> must be terminal (succeeded, failed, or dead) to archive; current status is starting`. — **PASS** (excellent error).
|
||||
|
||||
#### `get_questions`
|
||||
- [x] **I13** Terminal run → `questions: []`. — **PASS**.
|
||||
- [x] **I14** Blocked interview run → returns full question record (id, text, options, question_type, stage, allow_freeform). — **PASS**.
|
||||
|
||||
#### `answer` — `AnswerValue` shapes
|
||||
|
||||
Re-check note: the earlier `yes_no` answer failure did not reproduce against `fabro server` `0.230.0-nightly.0` on `127.0.0.1:32276` (2026-05-11). Boolean answers are accepted for `yes_no` questions, and invalid question/type combinations are rejected by the API as expected.
|
||||
|
||||
- [x] **I15** `answer=true` on the first `yes_no` question → submitted successfully (`submitted=true`) and advanced to the `confirmation` question. — **PASS**. Run `01KRCAQ9AS14KFCW4CXBZQ0CW9`.
|
||||
- [x] **I16** `answer=false` on a fresh `yes_no` question → submitted successfully (`submitted=true`). — **PASS**. Run `01KRCATZ031CAPEPVB4CNFEE33`.
|
||||
- [ ] **I17** `answer="some text"` — **NOT RE-TESTED**. Should be tested against a `freeform` question or a question with `allow_freeform=true`; text is not valid for the bundled `yes_no` question.
|
||||
- [ ] **I18** `answer={"text":"hi"}` — **NOT RE-TESTED**. Same scope as I17.
|
||||
- [x] **I19** `answer={"option":"Y"}` against the first `yes_no` question → `Answer does not match question type.` — **PASS / expectation corrected**. The MCP layer maps this shape to `selected`, but `server.rs:2670-2710` only accepts `yes`/`no` for `yes_no` and `confirmation`; `selected` belongs to `multiple_choice`.
|
||||
- [ ] **I20** `answer={"options":[...]}` — **NOT RE-TESTED**. Should be tested against a `multi_select` question; `multi_selected` is not valid for `yes_no`.
|
||||
- [x] **I21** `answer={"value":"yes"}` → `answer object must contain one of: option, options, text` (local validation). — **PASS**.
|
||||
- [x] **I22** `answer=42` (number) → `unsupported answer value: 42; expected boolean, string, or object`. — **PASS** (local validation).
|
||||
- [x] **I23** `answer={"option": 5}` → `answer option must be a string: invalid type: integer '5', expected a string`. — **PASS**.
|
||||
- [x] **I24** `answer={"options": ["a", 2]}` → `answer options must be strings: invalid type: integer '2', expected a string`. — **PASS**.
|
||||
- [x] **I25** `action=answer` without `question_id` → `question_id is required for action answer`. — **PASS**.
|
||||
- [x] **I26** `action=answer` without `answer` → `answer is required for action answer`. — **PASS**.
|
||||
- [x] **I27** Already-answered question — observed indirectly: the same question_id returned `Question no longer exists or was already answered.` on retry. — **PASS**.
|
||||
|
||||
### Cross-cutting
|
||||
- [x] **I28** `run_id=" "` → `run_id is required`. — **PASS**.
|
||||
- [x] **I29** Action enum: `Get` and `get-questions` both rejected with `unknown variant 'X', expected one of: get, start, message, cancel, archive, unarchive, get_questions, answer`. — **PASS**.
|
||||
|
||||
---
|
||||
|
||||
## 6. End-to-end scenarios (multi-tool)
|
||||
|
||||
- [x] **X1 — Happy lifecycle** `gh-list` create → 35s gather → events filtered to `stage.started/completed` → 8 events for 4 stages (start, list_prs, list_issues, exit). Sequence matches workflow graph. — **PASS**.
|
||||
- [x] **X2 — Cancel mid-run** Covered by I8: `gh-list` cancel during `starting` → gather returned terminal `failed` in 5s; projection shows `status_reason=cancelled`. — **PASS**.
|
||||
- [ ] **X3 — Human-in-the-loop** — **PARTIAL**. The earlier yes/no answer blocker is no longer reproduced (I15/I16 now pass), and `gather` returning `timed_out=true` on a `blocked` run **was** verified (G13). Full interview completion remains unverified in this sweep.
|
||||
- [ ] **X4 — Steering** — **DEFERRED** (requires active LLM agent).
|
||||
- [x] **X5 — Archive flow** Covered by I10/I11: archive → search with `archived=true` returns it (also returned by default search — see I10 finding). Unarchive reverses. — **PASS** with caveat.
|
||||
- [x] **X6 — Search/cursor under churn** Page 1 `first=3` → cursor saved. Created new run `01KRC625KG…` mid-flow. Page 2 with original cursor returned 3 older runs; a fresh page 1 placed the new run at position 1. — **ACCEPTED / SIMPLIFIED**. Pagination is not snapshot-isolated; clients that need newly inserted earlier results should restart the search. Code now applies filters before sorting/cursoring so unrelated runs outside the filtered result set do not trim filtered pages.
|
||||
- [x] **X7 — Events while running** Started `gh-list` run, listed events `desc` immediately (max seq=8), gathered to completion, re-listed (max seq=46). Seq numbers grew monotonically; no early events lost. — **PASS**.
|
||||
- [x] **X8 — Truncated event recovery** Fetched the `ImplementPlan` `run.created` event (embeds ~30 KB goal) at default `max_content_length=20000` → `truncated:true`, payload returned as a JSON string. — **PASS**.
|
||||
- [ ] **X9 — Stranger inputs** — Skipped per scope decision. Trivially safe since inputs go through TOML conversion to be stored as values; the MCP layer never opens paths.
|
||||
|
||||
---
|
||||
|
||||
## 7. Mechanics for the manual sweep
|
||||
|
||||
- **Driver** — run these scenarios through an MCP client (e.g. Claude Code with the `fabro` MCP server configured) against a locally running `fabro server`.
|
||||
- **Reusable run IDs** — keep a handful of already-terminal runs around (e.g. one `gh-list` succeeded, one failed `implement-plan`) as fixtures for `events`, `gather` (instant-return), `interact.get`, and `archive` scenarios.
|
||||
- **Server unreachable cases** — stop the API server with the MCP client still connected to exercise error propagation paths.
|
||||
- **Issue tracking** — file a GitHub issue per defect; link the scenario ID (e.g. `C13`) so this plan and the bugs cross-reference.
|
||||
|
|
@ -1,457 +0,0 @@
|
|||
# Plan: Events as Source of Truth Follow-Ups
|
||||
|
||||
Close the remaining event-contract gaps required before we can execute `~/.claude/plans/memoized-pondering-knuth.md` and make projected `RunState` the primary read model.
|
||||
|
||||
## Context
|
||||
|
||||
`docs-internal/plan-events-as-source-of-truth.md` has mostly landed. The event stream is materially stronger now, but it still does not cover every field that `memoized-pondering-knuth.md` wants to derive from events.
|
||||
|
||||
The next step is not a broad store refactor. It is a narrow follow-up pass that:
|
||||
|
||||
- finishes the missing event coverage
|
||||
- makes the remaining source-of-truth boundaries explicit
|
||||
- leaves `memoized-pondering-knuth.md` with no hidden event-contract assumptions
|
||||
|
||||
This plan is a prerequisite plan, not the full event-sourced store migration.
|
||||
|
||||
## Simplification Rules
|
||||
|
||||
These rules govern every follow-up event change in this document:
|
||||
|
||||
- enrich an existing semantic event before inventing a new one
|
||||
- keep run-level summary data on run-level events
|
||||
- keep handler-specific metadata on handler-specific events
|
||||
- avoid storage-shaped event names like `*.recorded`, `*.persisted`, or `*.written`
|
||||
- explicitly retain non-event concerns instead of half-eventizing them
|
||||
|
||||
If a proposed event change violates one of those rules, prefer a simpler shape.
|
||||
|
||||
## Goal
|
||||
|
||||
After this plan lands, the later `memoized-pondering-knuth.md` work should be able to:
|
||||
|
||||
- build a projected `RunState` without inventing missing data
|
||||
- replace direct read-side APIs with projection helpers
|
||||
- remove duplicated write-side persistence for all event-backed fields
|
||||
|
||||
without first having to stop and redesign the event model again.
|
||||
|
||||
## Relationship To The Existing Plans
|
||||
|
||||
### What `plan-events-as-source-of-truth.md` already solved
|
||||
|
||||
- `run.created`
|
||||
- `stage.completed.response`
|
||||
- `sandbox.initialized` sandbox metadata
|
||||
- `checkpoint.completed.diff`
|
||||
- `command.started` / `command.completed`
|
||||
- `retro.started.prompt/provider/model`
|
||||
- `retro.completed.response/retro`
|
||||
|
||||
### What is still missing for `memoized-pondering-knuth.md`
|
||||
|
||||
- semantic run status events
|
||||
- checkpoint events that can reconstruct full checkpoint snapshots and history
|
||||
- full pull request record coverage
|
||||
- final patch coverage
|
||||
- provider-used coverage
|
||||
- parallel-results coverage
|
||||
- an explicit decision for fields that should remain non-event for now
|
||||
|
||||
## Decisions
|
||||
|
||||
### 1. Use semantic run lifecycle events, not a generic `run.status_changed`
|
||||
|
||||
Status should be reconstructed from explicit run lifecycle events rather than a generic “status changed” envelope.
|
||||
|
||||
Add event coverage for:
|
||||
|
||||
- `run.submitted`
|
||||
- `run.starting`
|
||||
- `run.running`
|
||||
- `run.paused`
|
||||
- `run.removing`
|
||||
- `run.completed`
|
||||
- `run.failed`
|
||||
- `run.dead`
|
||||
|
||||
Projection rule:
|
||||
|
||||
- the latest status-bearing run event defines `RunStatusRecord.status`
|
||||
- event-specific fields define `RunStatusRecord.reason`
|
||||
- envelope `ts` defines `RunStatusRecord.updated_at`
|
||||
|
||||
`run.started` remains the start-record / execution-metadata event, not the canonical status event.
|
||||
|
||||
This separation is intentional:
|
||||
|
||||
- `run.started` answers "when and how did execution begin?"
|
||||
- `run.running` answers "what is the run's status?"
|
||||
|
||||
Status mapping table:
|
||||
|
||||
| Event | Projected `RunStatus` | `StatusReason` rule |
|
||||
|---|---|---|
|
||||
| `run.submitted` | `Submitted` | `None` |
|
||||
| `run.starting` | `Starting` | optional if the emitter has a concrete reason, otherwise `None` |
|
||||
| `run.running` | `Running` | `None` |
|
||||
| `run.paused` | `Paused` | preserve emitted reason if present |
|
||||
| `run.removing` | `Removing` | `None` |
|
||||
| `run.completed` | `Succeeded` | preserve emitted reason if present; default should remain `Completed` or `PartialSuccess` based on terminal outcome |
|
||||
| `run.failed` | `Failed` | preserve emitted reason if present; expected common reasons include workflow/bootstrap/sandbox failures |
|
||||
| `run.dead` | `Dead` | preserve emitted reason if present; otherwise `None` |
|
||||
|
||||
If any current status mutation cannot be represented cleanly by this table, fix the event model in this follow-up plan rather than pushing ambiguity into the later projector.
|
||||
|
||||
### 2. Keep the boundary tight: not every stored value must become an event in this pass
|
||||
|
||||
This follow-up plan should only eventize the fields that block the later projected-state cutover.
|
||||
|
||||
Retain as non-event concerns for now:
|
||||
|
||||
- binary assets
|
||||
- artifact value blobs / offloaded context artifacts
|
||||
|
||||
This means `memoized-pondering-knuth.md` should be updated afterwards so `artifact_values` is no longer listed as a required event-backed row for the first cut.
|
||||
|
||||
### 3. Prefer complete event payloads over event joins that require hidden store lookups
|
||||
|
||||
If a projected record needs fields that do not already exist in another authoritative event, add them directly to the relevant event.
|
||||
|
||||
Do not rely on:
|
||||
|
||||
- sidecar JSON files
|
||||
- legacy store records
|
||||
- “the caller can join this with some other direct read”
|
||||
|
||||
Prefer one self-contained semantic event over reconstructing a record from several unrelated low-level events when that reconstruction adds complexity for little value.
|
||||
|
||||
## Follow-Up Coverage Matrix
|
||||
|
||||
This matrix is the contract for this plan. Each row must be green before `memoized-pondering-knuth.md` starts removing read/write APIs.
|
||||
|
||||
| Field / record needed later | Current direct source | Current event state | Follow-up required |
|
||||
|---|---|---|---|
|
||||
| `RunStatusRecord` | `put_status` in create/start/resume/finalize/disk paths | Incomplete; no semantic status event family | Add semantic run lifecycle events and a status mapping table |
|
||||
| `StartRecord` | `put_start` | Mostly covered by `run.started` | Verify `run.started` fully covers `run_branch`, `base_sha`, `start_time`; no shape change if already true |
|
||||
| latest `Checkpoint` | `put_checkpoint` | Incomplete; `checkpoint.completed` only carries `node_id`, `status`, `git_commit_sha`, `diff` | Enrich `checkpoint.completed` to carry a full checkpoint snapshot payload |
|
||||
| checkpoint history | `append_checkpoint` / `list_checkpoints` | Incomplete; history cannot be rebuilt from current event payload | Use fully-populated `checkpoint.completed` as append-only checkpoint history |
|
||||
| `Conclusion` | `put_conclusion` | Partially covered by terminal events plus stage aggregation | Verify the projector can derive full `Conclusion`, including retries/tokens/stage summaries, from existing events; if projection stays awkward, enrich terminal run events instead of adding new conclusion-only events |
|
||||
| `PullRequestRecord` | `put_pull_request` | Incomplete; `pull_request.created` only carries URL/number/draft | Enrich `pull_request.created` to carry full `PullRequestRecord` fields |
|
||||
| final patch | `put_final_patch` | Incomplete; terminal run event carries final SHA but not patch text | Enrich `run.completed` with `final_patch` |
|
||||
| node provider metadata | `put_node_provider_used` | Incomplete; prompt/CLI events carry provider/model, but agent-mode still relies on sidecar sync | Project from existing handler-specific events and enrich forwarded agent session events if needed |
|
||||
| node parallel results | `put_node_parallel_results` | Incomplete; `parallel.branch.completed.head_sha` is not enough | Enrich `parallel.completed` to carry the final results payload |
|
||||
| node diff | `put_node_diff` | Partially covered by `checkpoint.completed.diff` | Decide and document whether node diff is sourced from the latest checkpoint event for that node or a dedicated node diff event; keep one canonical rule |
|
||||
| retro prompt/response/retro payload | `put_retro_prompt`, `put_retro_response`, `put_retro` | Covered | No new event work; just parity-test it |
|
||||
| sandbox record | `put_sandbox` | Covered | No new event work; just parity-test it |
|
||||
|
||||
## Required Event Changes
|
||||
|
||||
### 1. Add semantic run lifecycle events
|
||||
|
||||
Add new `Event` variants for:
|
||||
|
||||
- `RunSubmitted`
|
||||
- `RunStarting`
|
||||
- `RunRunning`
|
||||
- `RunPaused`
|
||||
- `RunRemoving`
|
||||
- `RunDead`
|
||||
|
||||
Existing terminal events remain:
|
||||
|
||||
- `run.completed`
|
||||
- `run.failed`
|
||||
|
||||
Required payload fields:
|
||||
|
||||
- `reason: Option<StatusReason>` where applicable
|
||||
- any extra fields already emitted on terminal events should stay there
|
||||
|
||||
Emit from the same places that currently call `put_status`:
|
||||
|
||||
- `lib/components/fabro-workflow/src/operations/create.rs`
|
||||
- `lib/components/fabro-workflow/src/operations/start.rs`
|
||||
- `lib/components/fabro-workflow/src/operations/resume.rs`
|
||||
- `lib/components/fabro-workflow/src/pipeline/finalize.rs`
|
||||
- `lib/components/fabro-workflow/src/lifecycle/disk.rs`
|
||||
- CLI administrative flows that directly mutate status:
|
||||
- `lib/apps/fabro-cli/src/commands/runs/rm.rs`
|
||||
- `lib/apps/fabro-cli/src/commands/run/rewind.rs`
|
||||
|
||||
### 2. Enrich `checkpoint.completed` to carry a full checkpoint snapshot
|
||||
|
||||
Current `checkpoint.completed` is not enough to rebuild `Checkpoint`.
|
||||
|
||||
Add fields covering:
|
||||
|
||||
- `timestamp` is still the envelope `ts`
|
||||
- `current_node`
|
||||
- `completed_nodes`
|
||||
- `node_retries`
|
||||
- `context_values`
|
||||
- `node_outcomes`
|
||||
- `next_node_id`
|
||||
- `git_commit_sha`
|
||||
- `loop_failure_signatures`
|
||||
- `restart_failure_signatures`
|
||||
- `node_visits`
|
||||
- `diff`
|
||||
|
||||
Emitter seam:
|
||||
|
||||
- `lib/components/fabro-workflow/src/lifecycle/event.rs`
|
||||
|
||||
Producer seam for the source checkpoint object:
|
||||
|
||||
- `lib/components/fabro-workflow/src/lifecycle/disk.rs`
|
||||
|
||||
Design rule:
|
||||
|
||||
- one `checkpoint.completed` event must be sufficient to reconstruct one historical checkpoint record without replaying prior stage events
|
||||
|
||||
That keeps checkpoint history export and `rebuild_meta` simple.
|
||||
|
||||
Do not split checkpoint reconstruction back across `stage.completed` and other incidental events unless there is a strong size or performance reason. A saved checkpoint is a first-class domain event and should be self-contained.
|
||||
|
||||
### 3. Enrich `pull_request.created` to carry the full record
|
||||
|
||||
Current event payload is too small for `PullRequestRecord`.
|
||||
|
||||
Add:
|
||||
|
||||
- `html_url`
|
||||
- `number`
|
||||
- `owner`
|
||||
- `repo`
|
||||
- `base_branch`
|
||||
- `head_branch`
|
||||
- `title`
|
||||
- `draft`
|
||||
|
||||
Producer seam:
|
||||
|
||||
- `lib/components/fabro-workflow/src/pipeline/pull_request.rs`
|
||||
|
||||
After this lands, `put_pull_request` should become removable during the later memoized-state cutover.
|
||||
|
||||
Do not add a second storage-oriented PR event. The semantic event is already "pull request created"; it just needs the full payload.
|
||||
|
||||
### 4. Enrich `run.completed` with the final patch
|
||||
|
||||
Current final patch only exists via direct store writes.
|
||||
|
||||
Do not add a separate storage-shaped event. The final patch is run-level terminal metadata, so it belongs on the terminal success event.
|
||||
|
||||
Enrich `run.completed`, using the patch already computed from:
|
||||
|
||||
- `lib/components/fabro-workflow/src/lifecycle/git.rs`
|
||||
|
||||
Required payload:
|
||||
|
||||
- `final_patch: Option<String>`
|
||||
|
||||
Projection rule:
|
||||
|
||||
- `RunState.final_patch` projects from `run.completed.properties.final_patch`
|
||||
|
||||
This keeps final run summary data in one place alongside:
|
||||
|
||||
- `status`
|
||||
- `duration_ms`
|
||||
- `artifact_count`
|
||||
- `final_git_commit_sha`
|
||||
|
||||
If failed runs later need final patch coverage too, extend the terminal failure event deliberately. Do not introduce a separate patch-persistence event unless terminal events prove insufficient.
|
||||
|
||||
### 5. Finish provider-used coverage using existing handler-specific events
|
||||
|
||||
The current system still reads `provider_used.json` from disk and syncs it into the store. That is not event-sourced.
|
||||
|
||||
Replace that with one explicit projection rule based on existing handler-specific events.
|
||||
|
||||
Use:
|
||||
|
||||
- `stage.prompt` for prompt-mode stages
|
||||
- forwarded `agent.session.started` for agent-mode stages
|
||||
- `agent.cli.started` for CLI-backed agent stages
|
||||
|
||||
If agent-mode forwarded session events still do not carry enough metadata, enrich `AgentEvent::SessionStarted` rather than adding a new stage-wide event.
|
||||
|
||||
Required projected output:
|
||||
|
||||
- `mode`
|
||||
- `provider`
|
||||
- `model`
|
||||
- any existing raw provider-used JSON fields that are still needed by consumers
|
||||
|
||||
Likely seams:
|
||||
|
||||
- `lib/components/fabro-workflow/src/handler/agent.rs`
|
||||
- `lib/components/fabro-workflow/src/handler/llm/api.rs`
|
||||
- `lib/components/fabro-workflow/src/pipeline/retro.rs` if retro uses the same forwarded agent session path
|
||||
- any CLI-backed LLM path if it still produces `provider_used.json`
|
||||
|
||||
Do not keep the current “read JSON sidecar, then `put_node_provider_used`” pattern once this event exists.
|
||||
|
||||
Do not add a stage-generic provider-used event. Provider metadata is transport-specific and should stay attached to the prompt/agent/CLI events that actually know it.
|
||||
|
||||
### 6. Enrich `parallel.completed` with the final results payload
|
||||
|
||||
`parallel.branch.completed.head_sha` is useful but not enough to replace `put_node_parallel_results`.
|
||||
|
||||
Use the existing terminal parallel event rather than adding a storage-shaped event name.
|
||||
|
||||
Add to `parallel.completed`, emitted from:
|
||||
|
||||
- `lib/components/fabro-workflow/src/handler/parallel.rs`
|
||||
|
||||
Required new payload:
|
||||
|
||||
- `results` as the same JSON array currently persisted to `parallel_results.json`
|
||||
|
||||
Projection rule:
|
||||
|
||||
- `StageProjection.parallel_results` projects from `parallel.completed.properties.results`
|
||||
|
||||
Why this is the right event:
|
||||
|
||||
- it is emitted after all branch executions have joined
|
||||
- the final result set has already been assembled
|
||||
- it represents completion of the parallel node’s branch-collection phase
|
||||
|
||||
The workflow-level outcome of the node still comes from `stage.completed`; `parallel.completed` just becomes the canonical source for the branch result set.
|
||||
|
||||
Do not add `parallel.results_recorded` or similar. The semantic event already exists.
|
||||
|
||||
### 7. Lock down the node diff rule
|
||||
|
||||
We already added `checkpoint.completed.diff`, but the memoized plan should not proceed until there is one explicit derivation rule for node diff.
|
||||
|
||||
Decision required:
|
||||
|
||||
- either `StageProjection.diff` is “latest checkpoint diff for that node visit”
|
||||
- or add a dedicated `node.diff_generated` event
|
||||
|
||||
This follow-up plan should pick one and update docs/tests accordingly.
|
||||
|
||||
Given the current code, using `checkpoint.completed.diff` is the simpler option unless multiple diffs per node visit need to be preserved.
|
||||
|
||||
Prefer `checkpoint.completed.diff` unless a concrete consumer proves that diff generation and checkpoint persistence are semantically different moments.
|
||||
|
||||
## File Map
|
||||
|
||||
Likely files to touch:
|
||||
|
||||
- `docs-internal/events.md`
|
||||
- `docs-internal/run-directory-keys.md`
|
||||
- `docs-internal/events-strategy.md`
|
||||
- `lib/components/fabro-workflow/src/event.rs`
|
||||
- `lib/components/fabro-workflow/src/lifecycle/event.rs`
|
||||
- `lib/components/fabro-workflow/src/lifecycle/disk.rs`
|
||||
- `lib/components/fabro-workflow/src/lifecycle/git.rs`
|
||||
- `lib/components/fabro-workflow/src/operations/create.rs`
|
||||
- `lib/components/fabro-workflow/src/operations/start.rs`
|
||||
- `lib/components/fabro-workflow/src/operations/resume.rs`
|
||||
- `lib/components/fabro-workflow/src/pipeline/finalize.rs`
|
||||
- `lib/components/fabro-workflow/src/pipeline/pull_request.rs`
|
||||
- `lib/components/fabro-workflow/src/handler/agent.rs`
|
||||
- `lib/components/fabro-workflow/src/handler/parallel.rs`
|
||||
- `lib/apps/fabro-cli/src/commands/runs/rm.rs`
|
||||
- `lib/apps/fabro-cli/src/commands/run/rewind.rs`
|
||||
- tests in `fabro-workflow`, `fabro-cli`, and `fabro-store`
|
||||
|
||||
## Phases
|
||||
|
||||
### Phase 1: Define the missing event contract
|
||||
|
||||
- add semantic run lifecycle events
|
||||
- enrich `checkpoint.completed`
|
||||
- enrich `pull_request.created`
|
||||
- enrich `run.completed` with `final_patch`
|
||||
- add provider-used event coverage
|
||||
- add parallel-results event coverage
|
||||
- document the node diff derivation rule
|
||||
|
||||
This phase is complete when every row in the follow-up coverage matrix is backed by an explicit event contract.
|
||||
|
||||
Priority during this phase:
|
||||
|
||||
- first enrich existing semantic events
|
||||
- only add a truly new event when no existing semantic event owns the data
|
||||
|
||||
### Phase 2: Emit the new events everywhere status/data currently writes directly
|
||||
|
||||
Replace silent state mutation with canonical event emission first.
|
||||
|
||||
Important rule:
|
||||
|
||||
- do not remove direct store writes yet
|
||||
- dual-write is acceptable in this phase
|
||||
- the purpose is to prove event completeness before the memoized-state migration begins
|
||||
|
||||
### Phase 3: Add parity tests against current stored records
|
||||
|
||||
Add tests that build real event sequences and verify the future projector contract is now possible for:
|
||||
|
||||
- status reconstruction
|
||||
- start record reconstruction
|
||||
- checkpoint reconstruction
|
||||
- checkpoint history reconstruction
|
||||
- pull request reconstruction
|
||||
- final patch reconstruction
|
||||
- provider-used reconstruction
|
||||
- parallel-results reconstruction
|
||||
|
||||
Where a direct legacy store record still exists, compare the event-derived value against the legacy persisted value.
|
||||
|
||||
Keep the tests shaped around semantic events, not internal store APIs. The point is to prove the event contract is sufficient.
|
||||
|
||||
Minimum parity scenarios:
|
||||
|
||||
- create-only run before execution starts
|
||||
- normal started/running run
|
||||
- resumed run
|
||||
- rewound run
|
||||
- successful git-backed run with final patch
|
||||
- PR-producing run
|
||||
- parallel run with branch results
|
||||
- retro-enabled run
|
||||
- failed run that exits through terminal/drop-guard paths
|
||||
|
||||
### Phase 4: Update the downstream migration plan
|
||||
|
||||
Once this follow-up plan lands:
|
||||
|
||||
- update `~/.claude/plans/memoized-pondering-knuth.md`
|
||||
- remove any rows that were intentionally retained as non-event concerns
|
||||
- mark the newly-completed event-backed rows as ready
|
||||
- delete stale “likely needs to be added” wording that is no longer true
|
||||
|
||||
This keeps the later store-migration plan honest and implementation-ready.
|
||||
|
||||
## Verification
|
||||
|
||||
1. `cargo build --workspace`
|
||||
2. `cargo clippy --workspace -- -D warnings`
|
||||
3. `cargo nextest run -p fabro-workflow`
|
||||
4. `cargo nextest run -p fabro-cli`
|
||||
5. `cargo nextest run -p fabro-store`
|
||||
6. `cargo nextest run --workspace`
|
||||
7. Manual:
|
||||
- create a run and inspect `progress.jsonl`
|
||||
- verify semantic run lifecycle events appear in the expected order
|
||||
- verify a run with git changes emits `run.completed.properties.final_patch`
|
||||
- verify a PR-producing run emits full PR metadata in `pull_request.created`
|
||||
- verify a parallel run emits canonical final results on `parallel.completed` without reading `parallel_results.json`
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
This follow-up plan is complete when:
|
||||
|
||||
- every row in the follow-up coverage matrix is either event-backed or explicitly retained as non-event
|
||||
- direct store writes are no longer the only source for status, checkpoint history, pull request record, final patch, provider-used, or parallel results
|
||||
- projector parity tests prove the later `RunState` refactor has the event data it needs
|
||||
- `memoized-pondering-knuth.md` can be updated to proceed without hidden event-contract gaps
|
||||
|
||||
At that point, the later migration work should mostly be mechanical projection and API cleanup, not more event-model design.
|
||||
|
|
@ -1,163 +0,0 @@
|
|||
# Plan: Events as Source of Truth
|
||||
|
||||
Make all run directory key data derivable from events in `progress.jsonl`.
|
||||
|
||||
## Summary of changes
|
||||
|
||||
### Clarified derivation rules
|
||||
|
||||
- Envelope fields count as event sources. Any file field may be sourced from event envelope metadata (`run_id`, `ts`, `node_id`, `node_label`) as well as `properties`.
|
||||
- When a file is reconstructed from multiple events, the derivation should be documented explicitly in `events.md` and `run-directory-keys.md`; consumers should not need to infer cross-event joins.
|
||||
- `retro.json` is reconstructed from multiple events: `run.started` provides `workflow_name` and `goal`, `retro.completed` provides the parsed `retro` payload, and the retro event envelope provides the completion timestamp.
|
||||
- `conclusion.json.final_git_commit_sha` is normalized from the terminal run event: `run.completed.properties.final_git_commit_sha` on success/partial success, `run.failed.properties.git_commit_sha` on failure.
|
||||
|
||||
### New events
|
||||
|
||||
| Event | Purpose |
|
||||
|-------|---------|
|
||||
| `run.created` | Full run definition (settings, graph, workflow source/config, labels, paths). Emitted at end of CREATE operation, before START. |
|
||||
| `command.started` | Command node invocation: script, language, timeout_ms |
|
||||
| `command.completed` | Command node result: stdout, stderr, exit_code, duration_ms, timed_out |
|
||||
| `agent.cli.started` | CLI-backend LLM invocation: mode, provider, model, command |
|
||||
| `agent.cli.completed` | CLI-backend LLM result: stdout, stderr |
|
||||
|
||||
### Enriched events
|
||||
|
||||
| Event | New fields |
|
||||
|-------|------------|
|
||||
| `stage.started` | Remove `script` (moved to `command.started`), make `handler_type` non-optional |
|
||||
| `stage.completed` | `context_updates`, `jump_to_node`, `context_values`, `node_visits`, `loop_failure_signatures`, `restart_failure_signatures`, `response` |
|
||||
| `sandbox.initialized` | `provider`, `identifier`, `working_directory`, `repo_cloned`, `clone_origin_url`, `clone_branch` |
|
||||
| `checkpoint.completed` | `diff` |
|
||||
| `parallel.branch.completed` | `head_sha` |
|
||||
| `agent.session.started` | `mode`, `provider`, `model` |
|
||||
| `stage.prompt` | `mode`, `provider`, `model` |
|
||||
| `retro.started` | `prompt`, `provider`, `model` |
|
||||
| `retro.completed` | `response`, `retro` (full Retro struct) |
|
||||
|
||||
### Already covered (no changes needed)
|
||||
|
||||
| Key | Event source |
|
||||
|-----|--------------|
|
||||
| `start.json` | `run.started` |
|
||||
| `nodes/{node_id}/prompt.md` | `stage.prompt` |
|
||||
| `nodes/{node_id}/status.json` | `stage.completed` |
|
||||
| `retro/status.json` | `retro.completed` / `retro.failed` |
|
||||
| `conclusion.json` | `run.completed` / `run.failed` + aggregation from `stage.completed` |
|
||||
| `checkpoints/*.json` | Same as `checkpoint.json` — derived from `stage.completed` replay |
|
||||
|
||||
---
|
||||
|
||||
## Detailed decisions
|
||||
|
||||
### 1–2. `_init.json` + `run.json` — new `run.created` event
|
||||
|
||||
**Decision:** Emit a `run.created` event at the end of the CREATE operation (before START). Carries everything needed to persist the run:
|
||||
|
||||
- From `_init.json`: `created_at`, `db_prefix`, `run_dir`
|
||||
- From `run.json`: `settings`, `graph`, `workflow_slug`, `source_directory`, `base_branch`, `labels`
|
||||
- From `workflow.fabro`/`workflow.toml`: `workflow_source` (raw dot text), `workflow_config` (raw TOML text)
|
||||
|
||||
The existing `run.started` stays lightweight — it signals execution has begun. The CREATE→START boundary is: `run.created` persists the run definition, `run.started` marks execution start.
|
||||
|
||||
Derivation details:
|
||||
- `_init.json.run_id` and `run.json.run_id` come from `run.created` envelope `run_id`
|
||||
- `_init.json.created_at` and `run.json.created_at` come from `run.created` envelope `ts`
|
||||
|
||||
### 3. `checkpoint.json` — internal engine state
|
||||
|
||||
**Decision:** Add `context_updates`, `jump_to_node`, `context_values`, `node_visits`, `loop_failure_signatures`, and `restart_failure_signatures` to the `stage.completed` event properties. All checkpoint fields become derivable from replaying stage events.
|
||||
|
||||
New fields on `stage.completed`:
|
||||
- `context_updates` — map of context key → JSON value set by this stage
|
||||
- `jump_to_node` — non-edge jump target (optional)
|
||||
- `context_values` — full accumulated context map after this stage
|
||||
- `node_visits` — map of node id → visit count after this stage
|
||||
- `loop_failure_signatures` — failure signature → count after this stage
|
||||
- `restart_failure_signatures` — failure signature → count after this stage
|
||||
|
||||
Derivation details:
|
||||
- `checkpoint.json.timestamp` comes from the corresponding `checkpoint.completed` envelope `ts`
|
||||
- `checkpoints/{seq:04}-{epoch_ms}.json` uses the same derivation as `checkpoint.json`, with snapshot timestamp taken from each `checkpoint.completed` envelope `ts`
|
||||
|
||||
### 4. `retro.json` — LLM-generated retro content
|
||||
|
||||
**Decision:** Embed the full `Retro` struct as a `retro` property on the `retro.completed` event.
|
||||
|
||||
Derivation details:
|
||||
- `retro.json.run_id` comes from the `retro.completed` envelope `run_id`
|
||||
- `retro.json.workflow_name` comes from `run.started.properties.name`
|
||||
- `retro.json.goal` comes from `run.started.properties.goal`
|
||||
- `retro.json.timestamp` comes from the `retro.completed` envelope `ts`
|
||||
- The remaining retro content comes from `retro.completed.properties.retro`
|
||||
|
||||
### 5. `sandbox.json` — missing fields
|
||||
|
||||
**Decision:** Add sandbox-native identity and clone metadata to `sandbox.initialized` so it alone is sufficient to reconstruct `sandbox.json`. Host paths and container mount points are not part of the durable event model; clone-based providers report their sandbox working directory plus repository clone state instead.
|
||||
|
||||
### 6. `workflow.fabro` + `workflow.toml` — raw source files
|
||||
|
||||
**Decision:** Add `workflow_source` (raw dot text) and `workflow_config` (raw TOML text) as string fields on `run.created`. Covered by gap 1–2.
|
||||
|
||||
### 7. `nodes/{node_id}/response.md` — LLM response text
|
||||
|
||||
**Decision:** Add a `response` string field to `stage.completed` for LLM stages.
|
||||
|
||||
### 8. `nodes/{node_id}/prompt.md` — already covered
|
||||
|
||||
No change needed. `stage.prompt` is emitted per handler invocation (including retries) with the full rendered prompt text.
|
||||
|
||||
### 9–10. `stdout.log`, `stderr.log`, `script_timing.json` — new `command.completed` event
|
||||
|
||||
**Decision:** Emit a `command.completed` event after a command node finishes. Fields:
|
||||
- `stdout`, `stderr`, `exit_code`, `duration_ms`, `timed_out`
|
||||
|
||||
The `node_id` is in the envelope.
|
||||
|
||||
### 11. `nodes/{node_id}/script_invocation.json` — new `command.started` event
|
||||
|
||||
**Decision:** Emit a `command.started` event with `script`, `language`, `timeout_ms`. Pairs with `command.completed`. Remove `script` from `stage.started` — it's handler-specific data that belongs on the handler-specific event (same pattern as `agent.session.started` and `stage.prompt`).
|
||||
|
||||
### 12. `cli_stdout.log`, `cli_stderr.log`, `provider_used.json` (CLI) — new `agent.cli.started` / `agent.cli.completed` events
|
||||
|
||||
**Decision:** Emit an `agent.cli.started` event before the CLI subprocess starts, with `mode` ("cli"), `provider`, `model`, `command`. Emit `agent.cli.completed` after it finishes, with `stdout`, `stderr`. The `node_id` is in the envelope.
|
||||
|
||||
### 13. `nodes/{node_id}/diff.patch` — git diff
|
||||
|
||||
**Decision:** Add a `diff` string field to `checkpoint.completed`.
|
||||
|
||||
### 14. `nodes/{node_id}/provider_used.json` — provider metadata
|
||||
|
||||
**Decision:** Add provider metadata to handler-specific events:
|
||||
- `agent.session.started` gets `mode` ("agent"), `provider`, `model`
|
||||
- `agent.cli.started` gets `mode` ("cli"), `provider`, `model`, `command`
|
||||
- `stage.prompt` gets `mode` ("prompt"), `provider`, `model`
|
||||
|
||||
### 15. `parallel_results.json` — `head_sha`
|
||||
|
||||
**Decision:** Add an optional `head_sha` field to `parallel.branch.completed`.
|
||||
|
||||
### 16. `retro/prompt.md` + `retro/response.md`
|
||||
|
||||
**Decision:** Add `prompt` to `retro.started`. Add `response` to `retro.completed` (alongside the parsed retro struct).
|
||||
|
||||
### 17. `retro/provider_used.json`
|
||||
|
||||
**Decision:** Add `provider` and `model` to `retro.started` alongside the prompt.
|
||||
|
||||
### Conclusion timestamps and final SHA normalization
|
||||
|
||||
**Decision:** Treat terminal run events as the authoritative source for `conclusion.json`.
|
||||
|
||||
Derivation details:
|
||||
- `conclusion.json.timestamp` comes from the terminal event envelope `ts` (`run.completed` or `run.failed`)
|
||||
- `conclusion.json.final_git_commit_sha` comes from `run.completed.properties.final_git_commit_sha` on success/partial success
|
||||
- On failure, `conclusion.json.final_git_commit_sha` is reconstructed from `run.failed.properties.git_commit_sha`
|
||||
|
||||
---
|
||||
|
||||
## Follow-up improvements
|
||||
|
||||
- `node_visits`, `loop_failure_signatures`, `restart_failure_signatures` on `stage.completed` are snapshots of accumulated state. In the future, these could be derived from event replay instead of being carried on each event — removing them would reduce event size but require replay logic in every consumer.
|
||||
- `context_values` is the full accumulated context map. If context maps grow large, a future optimization could emit only `context_updates` (the delta) and require consumers to accumulate. For now, shipping the full snapshot is simpler.
|
||||
- `stdout`/`stderr` on `command.completed` could be large. If this becomes a problem, consider a size threshold with truncation or a separate blob store with a reference in the event.
|
||||
|
|
@ -1,410 +0,0 @@
|
|||
# Slow Test Improvement Opportunities
|
||||
|
||||
Date: 2026-04-07
|
||||
|
||||
All measurements in this note were taken with `ulimit -n 4096` in the test subshell.
|
||||
|
||||
Primary timing dataset:
|
||||
- `/tmp/fabro-slow-tests-ulimit.7FJkSO/slow_tests_passing.csv`
|
||||
- `/tmp/fabro-slow-tests-ulimit.7FJkSO/report_passing.txt`
|
||||
|
||||
Passing suite baseline:
|
||||
- `cargo nextest run --workspace --no-fail-fast --status-level fail --final-status-level fail --show-progress none`
|
||||
- Result: `3631 passed, 182 skipped`
|
||||
|
||||
Method:
|
||||
- Ranking is based on the 5-pass passing dataset above.
|
||||
- Impact estimates are aggregate median test-time reductions, not additive suite wall-clock reductions.
|
||||
- Where a number is inferred rather than directly measured, that is called out explicitly.
|
||||
|
||||
## Top 10
|
||||
|
||||
### [x] 1. Change two slow `exec` mock responses from retriable `500` to non-retriable `400`
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/exec.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `fabro-cli::it::cmd::exec::exec_cli_server_target_overrides_configured_server_target`: `6.858s` median
|
||||
- `fabro-cli::it::cmd::exec::exec_server_target_uses_remote_transport_instead_of_local_api_key_resolution`: `6.787s` median
|
||||
- Direct microbenchmark of the same CLI path:
|
||||
- mocked `500`: `7.49s` median
|
||||
- mocked `400`: `0.053s` median
|
||||
|
||||
Implementation status:
|
||||
- Implemented in `lib/apps/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- Verified with `ulimit -n 4096` via 5 targeted nextest runs per test
|
||||
- Post-change nextest exec-time medians:
|
||||
- `exec_server_target_uses_remote_transport_instead_of_local_api_key_resolution`: `1.580s`
|
||||
- `exec_cli_server_target_overrides_configured_server_target`: `1.563s`
|
||||
|
||||
Estimated impact:
|
||||
- About `13.54s` aggregate median test time
|
||||
|
||||
Complexity:
|
||||
- Low
|
||||
|
||||
Pros:
|
||||
- Pure test change
|
||||
- Strongest measured single win
|
||||
- Keeps the same assertion shape if the response body marker is preserved
|
||||
|
||||
Cons:
|
||||
- If retry-on-5xx coverage matters, keep one dedicated retry-focused test elsewhere
|
||||
|
||||
---
|
||||
|
||||
### 2. Short-circuit delete-path worker grace for already-terminal runs
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-server/src/server.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `fabro-cli::it::cmd::system_prune::system_prune_yes_deletes_matching_runs`: `10.477s`
|
||||
- `fabro-cli::it::cmd::rm::rm_deletes_completed_run`: `5.359s`
|
||||
- `fabro-cli::it::cmd::rm::rm_partial_failure_reports_which_identifiers_failed`: `5.293s`
|
||||
- `fabro-cli::it::cmd::rm::rm_partial_failure_json_includes_removed_and_errors`: `5.257s`
|
||||
- `fabro-cli::it::cmd::rm::rm_force_deletes_run_without_sandbox_json_when_store_has_sandbox`: `5.275s`
|
||||
- Server code uses `WORKER_CANCEL_GRACE = 5s` in `terminate_worker_for_deletion()`
|
||||
|
||||
Estimated impact:
|
||||
- Roughly `20-25s` aggregate across the measured completed-run delete tests
|
||||
- This is an inference from the timing cluster plus the `5s` grace, not a standalone delta benchmark
|
||||
|
||||
Complexity:
|
||||
- Medium
|
||||
|
||||
Pros:
|
||||
- Helps real behavior, not just tests
|
||||
- Likely addresses the single slowest test too
|
||||
|
||||
Cons:
|
||||
- Needs careful correctness review around active worker shutdown semantics
|
||||
- Higher overlap with several delete-related tests
|
||||
|
||||
---
|
||||
|
||||
### [x] 3. Collapse the five abnormally slow `help` integration tests into one smoke test or a lighter harness
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/artifact.rs`
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/artifact_list.rs`
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/artifact_cp.rs`
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/config.rs`
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
|
||||
Measured evidence:
|
||||
- Slow `help` tests:
|
||||
- `artifact_list::help`: `1.659s`
|
||||
- `artifact_cp::help`: `1.656s`
|
||||
- `artifact::help`: `1.640s`
|
||||
- `config::help`: `1.592s`
|
||||
- `attach::help`: `1.559s`
|
||||
- Aggregate median across those 5 tests: `8.106s`
|
||||
- Direct command timings:
|
||||
- `artifact list --help`: about `10ms`
|
||||
- `attach --help`: about `9ms`
|
||||
- `settings --help`: about `10ms`
|
||||
|
||||
Estimated impact:
|
||||
- Conservative recoverable time: about `6.45s`
|
||||
|
||||
Implementation status:
|
||||
- Implemented by removing the 5 command-owned help tests and replacing them with `scenario::smoke::help_smoke_covers_high_cost_commands`
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli help_smoke_covers_high_cost_commands completion_smoke_covers_help_and_generation --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `2 passed`
|
||||
- Post-change timing over 5 targeted runs:
|
||||
- `fabro-cli::it::scenario::smoke::help_smoke_covers_high_cost_commands`: `2.164s` median
|
||||
|
||||
Complexity:
|
||||
- Low
|
||||
|
||||
Pros:
|
||||
- Pure harness cleanup
|
||||
- Clearly process/setup dominated rather than command-work dominated
|
||||
|
||||
Cons:
|
||||
- Less granular failure reporting
|
||||
|
||||
---
|
||||
|
||||
### [x] 4. Replace `doctor_no_color_when_no_color_set` with a render-path assertion
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/doctor.rs`
|
||||
- `lib/foundation/fabro-util/src/check_report.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `fabro-cli::it::cmd::doctor::doctor_no_color_when_no_color_set`: `5.131s`
|
||||
- Direct timing of `fabro doctor` under minimal test-like env: `5.115s`
|
||||
- Existing unit coverage already exercises no-color report rendering
|
||||
|
||||
Estimated impact:
|
||||
- About `5.13s`
|
||||
|
||||
Implementation status:
|
||||
- Implemented by deleting `fabro-cli::it::cmd::doctor::doctor_no_color_when_no_color_set`
|
||||
- Added a unit-level render assertion in `lib/apps/fabro-cli/src/commands/doctor.rs`:
|
||||
- `render_report_text_without_color_has_no_ansi`
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli render_report_text_without_color_has_no_ansi --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `1 passed`
|
||||
- Removed median cost from the suite: `5.131s`
|
||||
|
||||
Complexity:
|
||||
- Low to medium
|
||||
|
||||
Pros:
|
||||
- Same intent can likely be covered without a full diagnostics run
|
||||
- Very high return for a single test
|
||||
|
||||
Cons:
|
||||
- Slightly less end-to-end than the current test
|
||||
- Requires choosing the right lower-level render assertion
|
||||
|
||||
---
|
||||
|
||||
### [x] 5. Fix local Unix-socket autostart so it doesn't burn the full 5s readiness wait
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/src/server_client.rs`
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/server_start.rs`
|
||||
|
||||
Measured evidence:
|
||||
- Pre-fix 5-run timing for `fabro-cli::it::cmd::server_start::concurrent_autostart_converges_on_one_shared_daemon_and_cleans_up`:
|
||||
- runs: `6.786998459`, `6.833243958`, `6.832145834`, `6.851452709`, `6.768980709`
|
||||
- median: `6.832s`
|
||||
- stdev: `0.035s`
|
||||
- Direct measurement showed the real bottleneck was not the test's polling loops:
|
||||
- two concurrent fresh `fabro --json settings` calls each took about `5.1s`
|
||||
- `fabro server stop --timeout 0` only took about `0.12s`
|
||||
- Root cause: the Unix-socket client was doing a full `wait_for_server_ready()` loop before attempting local autostart when no daemon was running
|
||||
|
||||
Estimated impact:
|
||||
- Measured win on the original `server_start` test: about `5.02s`
|
||||
- This also speeds up other fresh local Unix-socket autostart paths that hit the same client logic
|
||||
|
||||
Complexity:
|
||||
- Medium
|
||||
|
||||
Pros:
|
||||
- Fixes a real product-path inefficiency instead of just shaving test harness overhead
|
||||
- Large win on the original slow test
|
||||
|
||||
Cons:
|
||||
- Touched shared local-server connection logic, so verification needs to cover the autostart path itself
|
||||
|
||||
Implementation status:
|
||||
- Implemented by splitting the Unix-socket connection path into:
|
||||
- a single immediate health probe before autostart
|
||||
- the existing retrying readiness wait after autostart
|
||||
- Kept the original integration test coverage in `lib/apps/fabro-cli/tests/it/cmd/server_start.rs`
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli concurrent_autostart_converges_on_one_shared_daemon_and_cleans_up --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `1 passed`
|
||||
- Post-change 5-run timing for `fabro-cli::it::cmd::server_start::concurrent_autostart_converges_on_one_shared_daemon_and_cleans_up`:
|
||||
- runs: `1.801041000`, `1.812114833`, `1.760408750`, `1.817953958`, `1.958977916`
|
||||
- median: `1.812s`
|
||||
- stdev: `0.075s`
|
||||
- Aggregate measured change for the original test:
|
||||
- before: `6.832s`
|
||||
- after: `1.812s`
|
||||
- saved: `5.020s`
|
||||
- Direct post-change autostart probe across 3 fresh concurrent runs:
|
||||
- median process runtime: `0.092s`
|
||||
- stdev: `0.028s`
|
||||
|
||||
---
|
||||
|
||||
### [x] 6. Collapse three lightweight `attach` smoke tests into one scenario-style test
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `attach_requires_run_arg`: `1.595s`
|
||||
- `attach_uses_configured_server_target_without_server_flag`: `1.555s`
|
||||
- `attach_errors_when_live_stream_ends_before_terminal_event`: `1.629s`
|
||||
- Aggregate median: `4.779s`
|
||||
- Direct `fabro attach` parse-error path is about `12ms`
|
||||
|
||||
Estimated impact:
|
||||
- Conservative recoverable time: about `3.15s`
|
||||
|
||||
Implementation status:
|
||||
- Implemented by removing the 3 command-owned smoke tests from `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
- Added `fabro-cli::it::scenario::smoke::attach_smoke_covers_arg_validation_and_remote_server_behaviors`
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli attach_smoke_covers_arg_validation_and_remote_server_behaviors --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `1 passed`
|
||||
- Post-change timing over 5 targeted runs:
|
||||
- `fabro-cli::it::scenario::smoke::attach_smoke_covers_arg_validation_and_remote_server_behaviors`: `1.584s` median
|
||||
- Aggregate measured change for the full 3-test batch:
|
||||
- before: `4.779s` median test-time sum
|
||||
- after: `1.584s` median test-time sum
|
||||
- saved: `3.195s`
|
||||
|
||||
Complexity:
|
||||
- Low to medium
|
||||
|
||||
Pros:
|
||||
- Fits the user's preference for merging complex cmd coverage into more natural scenarios
|
||||
- Mostly harness/process cost
|
||||
|
||||
Cons:
|
||||
- Bundles distinct failure modes together
|
||||
|
||||
---
|
||||
|
||||
### [x] 7. Collapse the three `completion` tests
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/completion.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `completion::generates_zsh_completions`: `1.567s`
|
||||
- `completion::generates_fish_completions`: `1.566s`
|
||||
- `completion::help`: `1.564s`
|
||||
- Aggregate median: `4.697s`
|
||||
- Direct command timings:
|
||||
- `completion zsh`: about `13ms`
|
||||
- `completion fish`: about `13ms`
|
||||
- `completion --help`: about `10ms`
|
||||
|
||||
Estimated impact:
|
||||
- Conservative recoverable time: about `3.13s`
|
||||
|
||||
Implementation status:
|
||||
- Implemented by removing the 3 command-owned completion smoke tests and replacing them with `scenario::smoke::completion_smoke_covers_help_and_generation`
|
||||
- Post-change timing over 5 targeted runs:
|
||||
- `fabro-cli::it::scenario::smoke::completion_smoke_covers_help_and_generation`: `2.147s` median
|
||||
- Aggregate measured change for the full 8-test batch:
|
||||
- before: `12.803s` median test-time sum
|
||||
- after: `4.310s` median test-time sum
|
||||
- saved: `8.492s`
|
||||
|
||||
Complexity:
|
||||
- Low
|
||||
|
||||
Pros:
|
||||
- Very safe refactor
|
||||
- Strong evidence that cost is test harness overhead
|
||||
|
||||
Cons:
|
||||
- Less granular failures if combined too aggressively
|
||||
|
||||
---
|
||||
|
||||
### [x] 8. Remove or merge the duplicate attach replay test
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `attach_replays_completed_detached_run`: `2.696s`
|
||||
- `attach_replays_from_store_without_run_json_or_progress_jsonl`: `2.675s`
|
||||
- The two tests are currently identical in code and assertions
|
||||
|
||||
Implementation status:
|
||||
- Implemented by removing the duplicate test from `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli attach_replays_completed_detached_run --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `1 passed`
|
||||
|
||||
Estimated impact:
|
||||
- Immediate `2.675s` if the duplicate is removed
|
||||
|
||||
Complexity:
|
||||
- Low
|
||||
|
||||
Pros:
|
||||
- Full savings on one test
|
||||
- Strongest low-risk cleanup in `attach.rs`
|
||||
|
||||
Cons:
|
||||
- If the intended missing-file case matters, the merged test should actually delete `run.json` / `progress.jsonl`
|
||||
|
||||
---
|
||||
|
||||
### [x] 9. Make `attach_before_completion_streams_to_finished_state` event-driven instead of sleep-driven
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `attach_before_completion_streams_to_finished_state`: `3.043s`
|
||||
- The test includes `sleep(Duration::from_secs(1))`
|
||||
- `write_gated_workflow()` adds another fixed `sleep 0.2`
|
||||
|
||||
Implementation status:
|
||||
- Implemented by replacing the fixed 1-second gate-release sleep with a real attach-output signal in `lib/apps/fabro-cli/tests/it/cmd/attach.rs`
|
||||
- The test now spawns `fabro attach`, waits for replayed stderr output (`✓ start`), then releases the workflow gate
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli attach_before_completion_streams_to_finished_state --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `1 passed`
|
||||
- Isolated A/B benchmark over 5 targeted nextest runs with `ulimit -n 4096`, comparing the current workspace to a detached `HEAD` worktree using the same `CARGO_TARGET_DIR`:
|
||||
- before (`HEAD` sleep-driven test): `8.013s` median, `0.227s` stdev
|
||||
- after (current event-driven test): `6.933s` median, `0.016s` stdev
|
||||
- saved: `1.079s`
|
||||
|
||||
Estimated impact:
|
||||
- Measured isolated saving: `1.079s`
|
||||
- Full-suite saving should be at least about `1.0s`
|
||||
|
||||
Complexity:
|
||||
- Low
|
||||
|
||||
Pros:
|
||||
- Removes an explicit fixed delay
|
||||
- Makes the test more deterministic
|
||||
|
||||
Cons:
|
||||
- Overlaps with the broader gated-workflow helper improvement below
|
||||
|
||||
---
|
||||
|
||||
### [x] 10. Remove or parameterize the fixed `sleep 0.2` in `write_gated_workflow()`
|
||||
|
||||
Files:
|
||||
- `lib/apps/fabro-cli/tests/it/cmd/support.rs`
|
||||
|
||||
Measured evidence:
|
||||
- `write_gated_workflow()` hardcodes `sleep 0.2`
|
||||
- The helper is used in 6 cmd tests
|
||||
|
||||
Implementation status:
|
||||
- Implemented by deleting the fixed `sleep 0.2` from `write_gated_workflow()` in `lib/apps/fabro-cli/tests/it/cmd/support.rs`
|
||||
- Verified with `ulimit -n 4096; cargo nextest run -p fabro-cli -E 'test(attach_before_completion_streams_to_finished_state) | test(ctrl_c_cancels_active_run_via_server) | test(rm_force_terminates_active_run_worker) | test(start_rejects_already_active_or_completed_run) | test(start_runs_under_server_ownership_without_launcher_record)' --status-level fail --final-status-level fail --show-progress none`
|
||||
- Verification result: `5 passed`
|
||||
- Targeted 5-pass benchmark with `ulimit -n 4096` over the 5 tests that currently use the helper:
|
||||
- before: `24.783s` aggregate median test-time sum
|
||||
- after: `23.558s` aggregate median test-time sum
|
||||
- saved: `1.225s`
|
||||
- Per-test median deltas:
|
||||
- `attach_before_completion_streams_to_finished_state`: `1.977s -> 1.635s`
|
||||
- `ctrl_c_cancels_active_run_via_server`: `6.781s -> 6.681s`
|
||||
- `rm_force_terminates_active_run_worker`: `11.984s -> 11.876s`
|
||||
- `start_rejects_already_active_or_completed_run`: `2.041s -> 1.684s`
|
||||
- `start_runs_under_server_ownership_without_launcher_record`: `2.000s -> 1.682s`
|
||||
|
||||
Estimated impact:
|
||||
- Measured aggregate saving across current helper users: `1.225s`
|
||||
|
||||
Complexity:
|
||||
- Low
|
||||
|
||||
Pros:
|
||||
- Small suite-wide gain
|
||||
- Straightforward helper cleanup
|
||||
|
||||
Cons:
|
||||
- Overlaps slightly with item 9
|
||||
|
||||
## Notes On Excluded Ideas
|
||||
|
||||
- I did not rank broad `rm` test consolidation highly on its own because the dominant cost appears to be the delete path itself, not just fixture setup.
|
||||
- I did not rank `system_prune_dry_run_lists_matching_runs_without_deleting` because it is already fast at `0.183s`; the expensive case is specifically `--yes`.
|
||||
- I did not rank `attach_json_errors_without_prompting_for_human_input` higher than item 8 because it is clearly slow (`6.882s`) but I did not finish a direct before/after measurement for replacing its `logs --json` polling loop with direct event-store polling.
|
||||
|
||||
## Suggested First Pass
|
||||
|
||||
If optimizing for highest impact with lowest complexity:
|
||||
|
||||
1. Change the two slow `exec` tests to use non-retriable mock statuses
|
||||
2. Remove or fix the duplicate attach replay test
|
||||
3. Collapse the slow `help` / `completion` smoke tests into lighter coverage
|
||||
|
|
@ -1,446 +0,0 @@
|
|||
---
|
||||
title: "feat: Add server daemon management with Unix socket support"
|
||||
type: feat
|
||||
status: completed
|
||||
date: 2026-04-02
|
||||
deepened: 2026-04-02
|
||||
---
|
||||
|
||||
# feat: Add server daemon management with Unix socket support
|
||||
|
||||
## Overview
|
||||
|
||||
Transform `fabro server` from a foreground-only TCP server into a proper daemon with background/foreground modes, stop/status lifecycle commands, Unix socket binding, and flock-based locking to prevent thundering herd when multiple CLI invocations auto-start the server.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The fabro server currently runs only in the foreground on a TCP port. Users must manually manage the process lifecycle. There is no way to check if a server is running, stop it gracefully, or prevent duplicate instances. When the CLI eventually auto-starts the server on demand, concurrent CLI invocations could race to start multiple servers simultaneously.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. `fabro server start` launches as a background daemon by default
|
||||
- R2. `fabro server start --foreground` retains current blocking behavior
|
||||
- R3. `fabro server stop` sends SIGTERM, waits, escalates to SIGKILL
|
||||
- R4. `fabro server status` reports running/stopped with PID, bind address, uptime
|
||||
- R5. A JSON server record tracks PID and metadata; stale records are auto-cleaned
|
||||
- R6. `--bind` replaces `--host`/`--port`, supporting both Unix sockets and TCP addresses
|
||||
- R7. Default bind is `{storage_dir}/fabro.sock` (Unix socket)
|
||||
- R8. flock-based locking prevents concurrent start attempts (thundering herd)
|
||||
- R9. Only one server instance can run at a time per storage directory
|
||||
- R10. TLS is not supported on Unix sockets (only on TCP)
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No systemd/launchd integration (out of scope)
|
||||
- No log rotation or `server logs` subcommand beyond basic prev-file rotation (future work)
|
||||
- Breaking change: `--host` and `--port` are removed, replaced by `--bind`
|
||||
- Client-side Unix socket connectivity (TypeScript Axios client, CLI-to-server calls) is tracked as a follow-up concern -- this plan covers the server side only
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-cli/src/commands/run/launcher.rs` -- JSON-based launcher records with PID tracking, stale detection via `process_alive()` + `ps` command-line matching, lazy cleanup on read
|
||||
- `lib/crates/fabro-cli/src/commands/run/start.rs` -- Self-re-exec pattern: spawns `fabro __detached` with `pre_exec_setsid`, stdout/stderr to log file, writes record after spawn, checks `try_wait()` for immediate failure, forwards `--storage-dir` to child
|
||||
- `lib/crates/fabro-cli/src/commands/run/detached.rs` -- `scopeguard::guard(launcher_path, remove_launcher_record)` for guaranteed cleanup on exit; `title_init()`/`title_set()` for proctitle; receives record path via `--launcher-path` arg
|
||||
- `lib/crates/fabro-proc/src/` -- `process_alive`, `sigterm`, `sigkill`, `pre_exec_setsid`, `title_init`/`title_set`. All functions are thin libc wrappers -- no retry loops or higher-level logic
|
||||
- `lib/crates/fabro-server/src/serve.rs` -- Current `serve_command()` with `ServeArgs`, config polling, webhook manager lifecycle. No graceful shutdown wired. TLS path uses manual `loop { listener.accept() }` via `hyper_util`, not `axum::serve`
|
||||
- `lib/crates/fabro-cli/src/args.rs:650` -- `#[command(name = "__detached", hide = true)]` hidden subcommand pattern with its own args struct
|
||||
- `lib/crates/fabro-cli/src/args.rs:972-984` -- `ServerNamespace`/`ServerCommand` enum
|
||||
- `lib/crates/fabro-cli/src/main.rs:108-195` -- Config log level extraction and command dispatch for server
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
No `docs/solutions/` directory exists. Patterns are embedded in the launcher record system.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Hidden subcommand for daemon child, not a flag**: The daemon spawns `fabro server __serve --record-path <path> --bind <addr> ...` as a detached child. `__serve` is a hidden `ServerCommand` variant with its own args struct, matching the `__detached` pattern in `RunCommands`. This keeps `ServeArgs` focused on server runtime concerns and process lifecycle in `fabro-cli`.
|
||||
|
||||
- **Process lifecycle stays in fabro-cli**: `fabro-server` has no dependency on `fabro-proc` and should not gain one. A `foreground.rs` in `fabro-cli/src/commands/server/` wraps `serve_command()` with record writes, scopeguard cleanup, and proctitle management -- same boundary as `detached.rs` wrapping workflow operations.
|
||||
|
||||
- **Record ownership: parent writes, child cleans up**: In daemon mode, the parent writes `server.json` after spawn (and cleans up on failure). The child receives the record path via `--record-path` and sets up a `scopeguard` to remove it on exit. This matches the launcher record ownership model exactly.
|
||||
|
||||
- **Server record, not bare PID file**: A JSON `ServerRecord` (pid, bind: Bind, log_path, started_at) stored at `{storage_dir}/server.json`, following the `LauncherRecord` pattern. The `bind` field uses the `Bind` enum (not a raw string) so consumers get type-safe access without re-parsing. Enables `status` to report rich info and supports PID-command-line validation against PID reuse.
|
||||
|
||||
- **flock on a separate lock file**: `{storage_dir}/server.lock` is acquired with `LOCK_EX | LOCK_NB` before any start attempt. Losers of the race block on the lock (with timeout), then discover the server already running. The lock file is separate from `server.json` so the record can be atomically rewritten without interfering with the lock. `flock()` auto-releases on process crash.
|
||||
|
||||
- **Keep fabro-proc thin**: Only `try_flock_exclusive(file) -> io::Result<bool>` goes in `fabro-proc` (thin libc wrapper). The timeout/retry loop lives in the caller (`server/start.rs`), consistent with every other function in `fabro-proc` being a single-syscall wrapper.
|
||||
|
||||
- **`Bind` enum defined in fabro-server**: A `Bind` enum (`Bind::Unix(PathBuf) | Bind::Tcp(SocketAddr)`) lives in `fabro-server` since it's a server concern ("what am I binding to?"). Used in both `ServeArgs` resolution and `ServerRecord`. Serializes cleanly via serde tagged enum: `{"unix": "/path"}` or `{"tcp": "127.0.0.1:3000"}`. Consumers (stop, status) can match on the variant directly instead of re-parsing a string -- e.g., `stop` knows to clean up the socket file when `bind` is `Bind::Unix`.
|
||||
|
||||
- **Bind address parsing**: `parse_bind(s: &str) -> Result<Bind>` in `fabro-server`. If the value contains `/`, it's a Unix socket path. Otherwise it's `host:port` TCP. Default: `{storage_dir}/fabro.sock`. Unix socket paths are validated against the 104-byte limit on macOS (108 on Linux).
|
||||
|
||||
- **Graceful shutdown via SIGTERM handler**: Wire `tokio::signal::unix::signal(SignalKind::terminate())` into `axum::serve().with_graceful_shutdown()`. The foreground mode also handles SIGINT (ctrl-c). **Known limitation:** The TLS codepath uses a manual `loop { listener.accept() }` via `hyper_util` and cannot use `with_graceful_shutdown`. Under TLS, `server stop` will rely on SIGTERM causing process exit (default behavior) but may need SIGKILL escalation. This is acceptable for now.
|
||||
|
||||
- **Process title includes bind address**: `fabro: server {bind}` to support PID-command-line validation and disambiguate if the single-instance invariant ever relaxes.
|
||||
|
||||
- **No TLS on Unix sockets**: When bind is a Unix socket, skip the TLS codepath entirely. TLS only applies to TCP binds.
|
||||
|
||||
- **Log rotation on start**: Rename existing `server.log` to `server.log.prev` before starting, so crash diagnostics from the previous run are preserved.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Where does flock live?** Only `try_flock_exclusive` in `fabro-proc` (thin wrapper). Timeout loop in caller.
|
||||
- **Default bind address?** `{storage_dir}/fabro.sock` (Unix socket). Resolved storage dir is used so it respects `--storage-dir` and config overrides.
|
||||
- **How does the parent know the daemon is ready?** Poll-connect to the socket/port with a short timeout (up to 5s). Same approach as pg_ctl.
|
||||
- **What happens to TLS + Unix socket?** Not supported. If `--bind` is a socket path and TLS is configured, emit a warning and skip TLS.
|
||||
- **Hidden flag or hidden subcommand?** Hidden subcommand (`__serve`), matching the `__detached` pattern. Not a flag on `ServeArgs`.
|
||||
- **Where does process lifecycle code live?** In `fabro-cli/src/commands/server/`, not in `fabro-server`. Same boundary as `detached.rs`.
|
||||
- **Client connectivity with Unix socket default?** Tracked as follow-up -- this plan covers server-side only. The `server.json` record stores the bind address so clients can discover it.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- Exact readiness polling interval and timeout values (start with 50ms interval, 5s timeout)
|
||||
- Whether `server stop` should print tail of server.log on timeout before SIGKILL
|
||||
- Exact chmod permissions on the Unix socket file (start with default, tighten if needed)
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
```
|
||||
fabro server start
|
||||
|
|
||||
acquire flock(server.lock)
|
||||
/ \
|
||||
(got lock) (blocked)
|
||||
| |
|
||||
read server.json wait for lock (retry loop in start.rs)
|
||||
/ \ |
|
||||
(live pid) (none/stale) (got lock)
|
||||
| | |
|
||||
"already rotate server.log -> server.log.prev
|
||||
running" spawn: fabro server __serve --record-path ... --bind ...
|
||||
exit 1 pre_exec_setsid, stdout/stderr -> server.log
|
||||
|
|
||||
parent: write server.json with child PID
|
||||
parent: poll-connect to bind address
|
||||
/ \
|
||||
(connected) (timeout)
|
||||
| |
|
||||
exit 0 print error + log tail
|
||||
clean up server.json
|
||||
exit 1
|
||||
|
||||
fabro server __serve --record-path <path> --bind <addr> ...
|
||||
|
|
||||
title_init() + title_set("fabro: server <bind>")
|
||||
scopeguard(record_path, remove_server_record)
|
||||
register SIGTERM/SIGINT shutdown
|
||||
|
|
||||
bind listener (Unix or TCP)
|
||||
axum::serve(...).with_graceful_shutdown(...)
|
||||
|
|
||||
(on shutdown signal)
|
||||
scopeguard fires: remove server.json
|
||||
remove socket file (if Unix)
|
||||
```
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
U1[Unit 1: flock in fabro-proc]
|
||||
U2[Unit 2: ServerRecord]
|
||||
U3[Unit 3: Bind enum + --bind + Unix socket]
|
||||
U4[Unit 4: daemon spawn + __serve]
|
||||
U5[Unit 5: server stop]
|
||||
U6[Unit 6: server status]
|
||||
U7[Unit 7: main.rs dispatch]
|
||||
|
||||
U1 --> U4
|
||||
U3 --> U2
|
||||
U2 --> U4
|
||||
U2 --> U5
|
||||
U2 --> U6
|
||||
U3 --> U4
|
||||
U4 --> U7
|
||||
U5 --> U7
|
||||
U6 --> U7
|
||||
```
|
||||
|
||||
Units 1 and 3 can run in parallel. Unit 2 depends on Unit 3 (for the `Bind` enum type). Units 5 and 6 can run in parallel after Unit 2. Unit 7 ties everything together.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Add flock wrapper to fabro-proc**
|
||||
|
||||
**Goal:** Provide `try_flock_exclusive` in `fabro-proc` as a thin libc wrapper for advisory file locking.
|
||||
|
||||
**Requirements:** R8
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-proc/src/flock.rs`
|
||||
- Modify: `lib/crates/fabro-proc/src/lib.rs`
|
||||
- Test: `lib/crates/fabro-proc/src/flock.rs` (inline tests)
|
||||
|
||||
**Approach:**
|
||||
- `try_flock_exclusive(file: &File) -> io::Result<bool>` -- `libc::flock(fd, LOCK_EX | LOCK_NB)`, returns `Ok(false)` on `EWOULDBLOCK`
|
||||
- `flock_unlock(file: &File) -> io::Result<()>` -- `libc::flock(fd, LOCK_UN)` for explicit unlock
|
||||
- Unix-only (`#[cfg(unix)]`), consistent with existing `fabro-proc` gating
|
||||
- No retry loops or timeout logic -- keep this crate at the syscall-wrapper level
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-proc/src/signal.rs` -- same style: thin wrapper over libc, `#[cfg(unix)]` gating, pub functions re-exported from `lib.rs`
|
||||
- `lib/crates/fabro-proc/src/pre_exec.rs` -- unsafe block style and safety comments
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: acquire lock on a temp file, confirm returns true
|
||||
- Happy path: release lock (drop file), re-acquire succeeds
|
||||
- Edge case: try_flock_exclusive on already-locked file (held by another fd) returns Ok(false)
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-proc` passes
|
||||
- `cargo clippy -p fabro-proc -- -D warnings` clean
|
||||
|
||||
- [x] **Unit 2: Add ServerRecord and lifecycle helpers**
|
||||
|
||||
**Goal:** Create a `ServerRecord` struct with read/write/remove/is_running helpers, mirroring `LauncherRecord`.
|
||||
|
||||
**Requirements:** R5, R9
|
||||
|
||||
**Dependencies:** Unit 3 (for `Bind` enum type)
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-cli/src/commands/server/record.rs`
|
||||
- Create: `lib/crates/fabro-cli/src/commands/server/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/mod.rs` (add `pub(crate) mod server;` gated with `#[cfg(feature = "server")]`)
|
||||
|
||||
**Approach:**
|
||||
- `ServerRecord { pid: u32, bind: Bind, log_path: PathBuf, started_at: DateTime<Utc> }` where `Bind` is the enum from `fabro-server` (Unit 3). The `bind` field serializes as a tagged enum (`{"unix": "/path"}` or `{"tcp": "127.0.0.1:3000"}`), giving consumers type-safe access -- e.g., `stop` matches on `Bind::Unix` to know it should remove the socket file
|
||||
- Paths: `server_record_path(storage_dir) -> {storage_dir}/server.json`, `server_lock_path(storage_dir) -> {storage_dir}/server.lock`, `server_log_path(storage_dir) -> {storage_dir}/server.log`
|
||||
- `server_record_is_running(record) -> bool` -- `process_alive(pid)` + `ps` command-line match for "fabro" and "server"
|
||||
- `active_server_record(storage_dir) -> Option<ServerRecord>` -- read, check liveness, lazy-clean stale
|
||||
- Path helpers only -- lock acquisition logic lives in Unit 4
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/run/launcher.rs` -- identical record lifecycle pattern: `write_*`, `read_*`, `remove_*`, `*_is_running`, `active_*`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: write record, read it back, fields match
|
||||
- Happy path: active_server_record returns None when no record file exists
|
||||
- Edge case: active_server_record returns None and removes file when PID is dead (use pid u32::MAX)
|
||||
- Edge case: active_server_record returns None and removes file when process doesn't match command-line check
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` for the new module's tests pass
|
||||
|
||||
- [x] **Unit 3: Add Bind enum, replace --host/--port with --bind, add Unix socket listener**
|
||||
|
||||
**Goal:** Define the `Bind` enum as the shared type for bind addresses. Change `ServeArgs` to use `--bind` instead of `--host`/`--port`. Support both Unix socket and TCP binding in `serve_command`. Wire graceful shutdown.
|
||||
|
||||
**Requirements:** R6, R7, R10
|
||||
|
||||
**Dependencies:** None (parallel with Unit 1)
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/bind.rs` (Bind enum + parse_bind + Display impl)
|
||||
- Modify: `lib/crates/fabro-server/src/lib.rs` (pub mod bind)
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs`
|
||||
- Modify: `lib/crates/fabro-server/Cargo.toml` (ensure tokio `net` feature includes unix support)
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs` (update dispatch if ServeArgs shape changes)
|
||||
- Test: `lib/crates/fabro-server/tests/it/api.rs` (update any tests using --host/--port)
|
||||
- Test: `lib/crates/fabro-server/src/bind.rs` (inline tests for parse_bind)
|
||||
|
||||
**Approach:**
|
||||
- Define `Bind` enum in `bind.rs`: `Bind::Unix(PathBuf) | Bind::Tcp(SocketAddr)` with `Serialize`/`Deserialize` (serde tagged enum), `Display`, `Clone`, `Debug`, `PartialEq`. This type is used by both `serve_command` and `ServerRecord` (Unit 2)
|
||||
- `parse_bind(bind: &str) -> Result<Bind>`. Contains `/` -> Unix socket; otherwise `host:port` parsed as `SocketAddr`. Validate Unix socket path length (104 bytes on macOS, 108 on Linux)
|
||||
- `Bind::display()` shows the address for human-readable output (used in proctitle, status, logs)
|
||||
- Replace `--host` and `--port` on `ServeArgs` with `--bind` (`Option<String>`, no default in clap -- default computed at runtime from resolved storage dir using the socket path)
|
||||
- In `serve_command`, branch on `Bind` variant: `UnixListener::bind` vs `TcpListener::bind`
|
||||
- For Unix sockets: remove stale socket file before bind, skip TLS codepath (log warning if TLS configured)
|
||||
- Wire `axum::serve(listener, router).with_graceful_shutdown(shutdown_signal())` for the non-TLS path, where `shutdown_signal` awaits SIGTERM or SIGINT. **Note:** The TLS path (`serve_tls`) uses a manual accept loop and cannot use `with_graceful_shutdown` -- document as known limitation, SIGTERM will still cause process exit
|
||||
- Derive `Clone` on `ServeArgs` to simplify the config polling task (currently manually clones each field)
|
||||
|
||||
**Patterns to follow:**
|
||||
- Current `serve.rs` listener binding and axum::serve pattern
|
||||
- Axum 0.8 supports `UnixListener` directly via `axum::serve`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: parse_bind with "127.0.0.1:3000" returns Tcp variant
|
||||
- Happy path: parse_bind with "/tmp/fabro.sock" returns Unix variant
|
||||
- Edge case: parse_bind with invalid address returns error
|
||||
- Edge case: parse_bind with path exceeding 104 bytes returns error on macOS
|
||||
- Happy path: server binds to Unix socket and accepts HTTP requests over it
|
||||
- Happy path: server binds to TCP address (existing behavior preserved)
|
||||
- Edge case: stale socket file is removed before binding
|
||||
- Integration: graceful shutdown on SIGTERM -- server stops accepting connections and exits cleanly
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes
|
||||
- Existing server tests still pass (adapted for --bind)
|
||||
|
||||
- [x] **Unit 4: Add daemon spawn, __serve hidden subcommand, and foreground wrapper**
|
||||
|
||||
**Goal:** Make `server start` launch a background daemon by default. `--foreground` retains current behavior. Both modes write/clean server records. Daemon mode uses flock to prevent thundering herd. `__serve` is the hidden subcommand the daemon child runs.
|
||||
|
||||
**Requirements:** R1, R2, R8, R9
|
||||
|
||||
**Dependencies:** Units 1, 2, 3
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-cli/src/commands/server/start.rs` (daemon spawn logic + flock retry loop)
|
||||
- Create: `lib/crates/fabro-cli/src/commands/server/foreground.rs` (wraps `serve_command` with record lifecycle, scopeguard, proctitle)
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs` (add `__Serve` hidden variant to `ServerCommand` with its own args struct; add `--foreground` flag to `Start` variant args)
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/mod.rs` (dispatch)
|
||||
|
||||
**Approach:**
|
||||
- **`ServerCommand::__Serve(ServeChildArgs)`**: Hidden subcommand with `--record-path`, `--bind`, plus forwarded args (`--model`, `--provider`, `--dry-run`, `--sandbox`, `--max-concurrent-runs`, `--config`, `--storage-dir`). Dispatches to `foreground.rs`.
|
||||
- **`foreground.rs`**: `title_init()` + `title_set("fabro: server {bind}")`, `scopeguard::guard(record_path, remove_server_record)`, then calls `serve_command()`. Mirrors `detached.rs` wrapping workflow operations.
|
||||
- **`start.rs` daemon path**: Open `server.lock`, retry `try_flock_exclusive` in a loop (50ms intervals, 5s timeout); check `active_server_record`; if running, print "already running" and exit 1; rotate `server.log` to `server.log.prev`; spawn self with `fabro server __serve --record-path <path> --bind <addr> ...` using `pre_exec_setsid`, stdout/stderr to `server.log`, stdin null, `env_remove("FABRO_JSON")`; write `server.json` with child PID; check `try_wait()` for immediate failure; poll-connect to bind address (50ms intervals, 5s timeout); on success print `"server started (pid N) on <bind>"`, exit 0; on failure print error + tail of log, clean up, exit 1
|
||||
- **`start.rs` foreground path** (`--foreground`): Write `server.json`, register scopeguard for cleanup, then call `serve_command()` directly (no re-exec)
|
||||
- **Forward all relevant args to child**: `--storage-dir`, `--config`, `--model`, `--provider`, `--dry-run`, `--sandbox`, `--max-concurrent-runs`
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/run/start.rs` -- self-re-exec with `pre_exec_setsid`, log redirect, record write, `try_wait` check, `--storage-dir` forwarding, `env_remove("FABRO_JSON")`
|
||||
- `lib/crates/fabro-cli/src/commands/run/detached.rs` -- `scopeguard` cleanup, `title_init`/`title_set`, receives record path via arg
|
||||
- `lib/crates/fabro-cli/src/args.rs:650` -- `#[command(name = "__detached", hide = true)]` pattern
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `server start` spawns daemon, writes server.json, exits 0
|
||||
- Happy path: `server start --foreground` runs in foreground, writes server.json, cleans up on exit
|
||||
- Edge case: `server start` when already running prints "already running" and exits 1
|
||||
- Edge case: `server start` with stale server.json (dead PID) cleans up and starts fresh
|
||||
- Happy path: flock prevents concurrent start -- second caller waits and finds server running
|
||||
- Edge case: daemon fails to start (bad bind address) -- parent reports error, cleans up record
|
||||
- Edge case: daemon child exits immediately -- parent detects via try_wait, reports error
|
||||
- Integration: after daemon start, server.json contains correct PID and bind address
|
||||
- Integration: server.log.prev contains previous log content after restart
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` passes
|
||||
- Manual: `fabro server start` starts daemon, `fabro server start` again says "already running"
|
||||
|
||||
- [x] **Unit 5: Add server stop subcommand**
|
||||
|
||||
**Goal:** `fabro server stop` sends SIGTERM, waits for graceful exit, escalates to SIGKILL, cleans up.
|
||||
|
||||
**Requirements:** R3
|
||||
|
||||
**Dependencies:** Unit 2
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-cli/src/commands/server/stop.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs` (add `Stop` variant to `ServerCommand` with `StopArgs { timeout }`)
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/mod.rs`
|
||||
|
||||
**Approach:**
|
||||
- Read `active_server_record` -- if None, print "not running", exit 1
|
||||
- `fabro_proc::sigterm(pid)`
|
||||
- Poll `process_alive(pid)` at 100ms intervals up to `--timeout` (default 10s)
|
||||
- If still alive after timeout, `fabro_proc::sigkill(pid)`
|
||||
- Remove `server.json` and socket file (match on `record.bind` -- if `Bind::Unix(path)`, remove the socket file)
|
||||
- Print "server stopped"
|
||||
|
||||
**Patterns to follow:**
|
||||
- `fabro_proc::sigterm`/`sigkill`/`process_alive` for signal management
|
||||
- `launcher.rs::remove_launcher_record` for cleanup
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: stop a running server -- sends SIGTERM, process exits, record cleaned up
|
||||
- Edge case: stop when not running -- prints "not running", exits 1
|
||||
- Edge case: stop with stale record (dead PID) -- cleans up record, prints "not running", exits 1
|
||||
- Edge case: process doesn't exit within timeout -- escalates to SIGKILL
|
||||
- Happy path: Unix socket file is removed after stop
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` passes
|
||||
- Manual: `fabro server start && fabro server stop` completes cleanly
|
||||
|
||||
- [x] **Unit 6: Add server status subcommand**
|
||||
|
||||
**Goal:** `fabro server status` reports running/stopped state with metadata. Supports `--json`.
|
||||
|
||||
**Requirements:** R4
|
||||
|
||||
**Dependencies:** Unit 2
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-cli/src/commands/server/status.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs` (add `Status` variant to `ServerCommand` with `StatusArgs { json }`)
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/mod.rs`
|
||||
|
||||
**Approach:**
|
||||
- Read `active_server_record` -- if None, print "not running", exit 1
|
||||
- Compute uptime from `started_at`
|
||||
- Human output: `"running (pid N) on <bind>, started X ago"`
|
||||
- `--json`: `{ "status": "running", "pid": N, "bind": "...", "started_at": "...", "uptime_seconds": N }`
|
||||
- Exit code: 0 = running, 1 = not running (same as `pg_ctl status`)
|
||||
|
||||
**Patterns to follow:**
|
||||
- Other CLI commands that support `--json` output (check `globals.json` usage pattern)
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: status when running -- prints info, exits 0
|
||||
- Happy path: status --json when running -- outputs valid JSON with expected fields
|
||||
- Edge case: status when not running -- prints "not running", exits 1
|
||||
- Edge case: status with stale record -- cleans up, prints "not running", exits 1
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` passes
|
||||
|
||||
- [x] **Unit 7: Update main.rs dispatch and config loading for new server subcommands**
|
||||
|
||||
**Goal:** Wire all server subcommands (start, stop, status, __serve) into CLI dispatch. Fix config log level extraction to handle new ServerCommand variants.
|
||||
|
||||
**Requirements:** R1, R2, R3, R4
|
||||
|
||||
**Dependencies:** Units 4, 5, 6
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs` (update `Commands::name()` match arm for all new variants)
|
||||
|
||||
**Approach:**
|
||||
- Change `let ServerCommand::Start(args) = ns.command;` to `match ns.command { Start(..) => ..., Stop(..) => ..., Status(..) => ..., __Serve(..) => ... }` in both the config log level block and the dispatch block
|
||||
- `__Serve` and `Start` (when in foreground/daemon mode) load server settings for log level; `Stop` and `Status` load user settings
|
||||
- Update `Commands::name()` to return `"server start"`, `"server stop"`, `"server status"`, `"server __serve"` for telemetry
|
||||
- Log prefix: `"server"` for `Start`/`__Serve`, `"cli"` for `Stop`/`Status`
|
||||
- `#[cfg(feature = "server")]` gating on all new paths
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing dispatch pattern in `main.rs` for other namespace commands (e.g., `Commands::RunCmd`)
|
||||
- Feature gating on all server references
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `fabro server stop --help` prints help text
|
||||
- Happy path: `fabro server status --help` prints help text
|
||||
- Happy path: `fabro server start --help` still works with new --bind flag and --foreground flag
|
||||
- Happy path: telemetry name returns correct values for each subcommand
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` passes (including existing server tests)
|
||||
- `cargo clippy --workspace -- -D warnings` clean
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** `serve_command()` gains a graceful shutdown signal handler. A new `foreground.rs` wrapper in `fabro-cli` manages server record lifecycle around `serve_command()`. Config polling task and webhook manager lifecycle preserved unchanged. Webhook manager shutdown (line 274-277 of `serve.rs`) becomes reachable for the first time via graceful shutdown -- the existing code is correct but the implementing agent should not add a scopeguard that drops the tokio runtime before async shutdown runs.
|
||||
- **Error propagation:** Daemon start failures surface to the parent via poll-connect timeout + log tail. Stop failures surface via exit code.
|
||||
- **State lifecycle risks:** Stale `server.json` after crash -- mitigated by PID liveness + command-line check on every read, with lazy cleanup (same proven pattern as launcher records). Stale socket file -- removed before bind attempt.
|
||||
- **API surface parity:** The `--bind` change is breaking for anyone using `--host`/`--port`. No API endpoint changes. Client-side connectivity to Unix sockets (TypeScript Axios client, CLI HTTP calls) is not addressed in this plan and needs follow-up.
|
||||
- **Integration coverage:** Unit tests can verify record lifecycle and parse_bind. Integration tests should cover the full start/status/stop cycle with a real server process.
|
||||
- **Unchanged invariants:** All HTTP routes, auth, config reloading, webhook manager, and SSE streaming behavior are unchanged. The server's runtime behavior is identical once it's listening.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| PID reuse after crash leads to signaling wrong process | Two-phase check: `process_alive` + `ps` command-line matching for "fabro" and "server" with bind address in proctitle, same proven pattern as launcher records |
|
||||
| flock not supported on all filesystems (e.g., NFS) | Storage dir is local by convention (~/.fabro). Document that network filesystems are unsupported for storage |
|
||||
| Unix socket path exceeds 104-byte limit on macOS | `parse_bind` validates path length at parse time with a clear error message |
|
||||
| Axum 0.8 UnixListener support | Axum 0.8 is already the workspace version; `serve()` accepts `UnixListener` natively |
|
||||
| Breaking --host/--port removal | Acceptable per scope decision. Users see a clear clap error pointing to --bind |
|
||||
| Race between parent writing server.json and child exiting | Check `try_wait()` immediately after spawn (same pattern as `start.rs`); if child already exited, clean up and report error |
|
||||
| TLS path lacks graceful shutdown | Documented as known limitation. SIGTERM still causes process exit; stop command escalates to SIGKILL after timeout. TLS + daemon is an uncommon combination |
|
||||
| Client-side code assumes TCP | Tracked as follow-up. Server record stores bind address for client discovery |
|
||||
|
||||
## Sources & References
|
||||
|
||||
- Related code: `lib/crates/fabro-cli/src/commands/run/launcher.rs`, `lib/crates/fabro-cli/src/commands/run/start.rs`, `lib/crates/fabro-cli/src/commands/run/detached.rs`
|
||||
- Related code: `lib/crates/fabro-proc/src/signal.rs`, `lib/crates/fabro-proc/src/pre_exec.rs`
|
||||
- Related code: `lib/crates/fabro-server/src/serve.rs`
|
||||
- Related code: `lib/crates/fabro-cli/src/args.rs:650` (`__detached` hidden subcommand pattern), `lib/crates/fabro-cli/src/args.rs:972-984` (`ServerCommand`)
|
||||
- Related code: `lib/crates/fabro-cli/src/main.rs:108-195`
|
||||
|
|
@ -1,566 +0,0 @@
|
|||
---
|
||||
title: "feat: auto-start server and route CLI store access over HTTP"
|
||||
type: feat
|
||||
status: active
|
||||
date: 2026-04-02
|
||||
origin: docs/ideation/2026-04-02-slatedb-consolidation-ideation.md
|
||||
deepened: 2026-04-04
|
||||
---
|
||||
|
||||
# feat: auto-start server and route CLI store access over HTTP
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 1 replaces direct CLI access to SlateDB with a Unix-socket HTTP client that talks to `fabro server`, and auto-starts that daemon whenever CLI store access is needed. Use the generated `fabro-api` Rust client as the transport surface where the existing API already matches the needed operations.
|
||||
|
||||
Phase 2 is an explicit follow-on decision: if we require strict single-owner semantics for all workflow execution writes, detached/start/resume execution must also move under server ownership rather than remaining in CLI-spawned engine processes.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The old plan assumed most of the HTTP surface and daemon infrastructure still needed to be built. That is no longer true.
|
||||
|
||||
Current state in the repo:
|
||||
|
||||
- Server daemon management is already implemented in `fabro-cli`:
|
||||
- `lib/crates/fabro-cli/src/commands/server/start.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/record.rs`
|
||||
- Unix socket bind support is already implemented in `fabro-server`:
|
||||
- `lib/crates/fabro-server/src/serve.rs`
|
||||
- `lib/crates/fabro-server/src/bind.rs`
|
||||
- The server already owns a single `SlateStore` instance and already exposes store-backed endpoints for:
|
||||
- run state
|
||||
- events
|
||||
- live event attach over SSE
|
||||
- blobs
|
||||
- checkpoint
|
||||
- retro
|
||||
- stage artifacts
|
||||
- The generated `fabro-api` client is reqwest-based and can be constructed with a custom `reqwest::Client`.
|
||||
- Reqwest 0.13 in this repo supports Unix sockets via `ClientBuilder::unix_socket(...)`.
|
||||
|
||||
The real remaining work is narrower:
|
||||
|
||||
1. CLI store access still opens `SlateStore` directly from local disk.
|
||||
2. CLI does not auto-start the server when store access is needed.
|
||||
3. Some API gaps remain, especially durable run listing and durable run deletion.
|
||||
4. Several CLI command paths still assume local engine processes own workflow execution and store writes.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. CLI commands that need store access auto-start `fabro server` when no active daemon is available.
|
||||
- R2. CLI store reads and writes stop opening SlateDB directly and instead use the server over HTTP via Unix socket.
|
||||
- R3. `fabro server` becomes the only process that opens SlateDB for migrated CLI store-access flows in phase 1, with full execution-path consolidation tracked separately in Unit 6 if strict single-owner semantics remain required.
|
||||
- R4. The generated `fabro-api` Rust client is used for server communication where its current API surface applies.
|
||||
- R5. Existing `InMemoryStore`-based tests and server-internal `SlateStore` usage remain unaffected.
|
||||
- R6. Event streaming remains live and efficient for attach/log-follow workflows.
|
||||
- R7. Binary transfer for blobs and artifacts remains raw bytes over HTTP.
|
||||
- R8. Error messages for server startup and server-unreachable cases are explicit and actionable.
|
||||
- R9. The plan must reflect the current repo state rather than the assumptions in the original 2026-04-02 draft.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
In scope:
|
||||
|
||||
- CLI auto-start of the local server daemon
|
||||
- HTTP-backed client access for CLI store consumers
|
||||
- Server API additions needed for store parity
|
||||
- Migration of CLI run discovery, logs/attach, blob/artifact access, and delete flows to server-backed access
|
||||
|
||||
Out of scope for the first pass:
|
||||
|
||||
- TypeScript/web client changes
|
||||
- Replacing server-internal `SlateStore`
|
||||
- Removing local run directories or runtime files
|
||||
- Re-architecting workflow execution to be fully server-owned in the same change set
|
||||
- Full trait refactors across `fabro-workflow` unless they are required to unblock the CLI migration
|
||||
|
||||
Follow-on scope, likely separate plan or addressed by Unit 6's decision fork:
|
||||
|
||||
- Consolidating detached/resume/start execution so workflow engine writes are also server-owned end-to-end
|
||||
|
||||
## Current-State Audit
|
||||
|
||||
### Already Implemented
|
||||
|
||||
- Daemon lifecycle:
|
||||
- `lib/crates/fabro-cli/src/commands/server/start.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/status.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/stop.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/record.rs`
|
||||
- Unix socket server binding:
|
||||
- `lib/crates/fabro-server/src/serve.rs`
|
||||
- `lib/crates/fabro-server/src/bind.rs`
|
||||
- Existing server routes relevant to store access:
|
||||
- `GET /api/v1/runs/{id}/state`
|
||||
- `GET /api/v1/runs/{id}/events`
|
||||
- `GET /api/v1/runs/{id}/attach`
|
||||
- `POST /api/v1/runs/{id}/events`
|
||||
- `POST /api/v1/runs/{id}/blobs`
|
||||
- `GET /api/v1/runs/{id}/blobs/{blobId}`
|
||||
- `GET|POST /api/v1/runs/{id}/stages/{stageId}/artifacts`
|
||||
- `GET /api/v1/runs/{id}/stages/{stageId}/artifacts/download`
|
||||
- `GET /api/v1/runs/{id}/checkpoint`
|
||||
- `GET /api/v1/runs/{id}/retro`
|
||||
- `RunProjection` already contains much more than the old plan assumed:
|
||||
- checkpoint and checkpoint history
|
||||
- retro and retro prompt/response
|
||||
- sandbox
|
||||
- final patch
|
||||
- pull request
|
||||
|
||||
### Still Missing or Mismatched
|
||||
|
||||
- `lib/crates/fabro-cli/src/store.rs` still builds a local `SlateStore`
|
||||
- CLI commands are typed against concrete `SlateStore` / `SlateRunStore`
|
||||
- Server `GET /api/v1/runs` is not durable store-backed; it serves in-memory managed runs only
|
||||
- No durable delete endpoint exists for runs
|
||||
- Artifact listing CLI still reads local artifact directories directly rather than using the server
|
||||
- Detached CLI execution still opens the store directly and runs workflow engine code locally
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Use `fabro-api::Client` over Unix socket, not a custom hyper-only client.**
|
||||
- The previous plan's "reqwest cannot do Unix sockets" assumption is stale.
|
||||
- The generated client already covers `state`, `events`, `attach`, `blobs`, and artifact endpoints.
|
||||
- Build a thin `fabro-cli` client wrapper around:
|
||||
- `fabro_api::Client`
|
||||
- `reqwest::ClientBuilder::unix_socket(socket_path)`
|
||||
- For any operation not yet present in the OpenAPI spec, add the endpoint to the spec and regenerate `fabro-api`.
|
||||
|
||||
- **Do not introduce a new transport crate until there is a clear reuse case.**
|
||||
- The immediate consumers are in `fabro-cli`.
|
||||
- A small `fabro-cli::server_client` module is enough for the first migration.
|
||||
- If a second Rust crate later needs the same client, extract then.
|
||||
|
||||
- **Auto-start belongs in CLI store/bootstrap code, not in the generated client.**
|
||||
- The generated client should stay transport-only.
|
||||
- Server lifecycle discovery/start remains in `fabro-cli`.
|
||||
|
||||
- **Treat `RunProjection` as the primary read snapshot.**
|
||||
- The existing `/runs/{id}/state` endpoint already returns the coarse-grained shape most CLI reads need.
|
||||
- This should replace many fine-grained local store reads without widening the API.
|
||||
|
||||
- **Split the migration into two layers.**
|
||||
- Layer 1: CLI read/write operations that are naturally expressible against the current server API
|
||||
- Layer 2: execution-path consolidation for detached/resume/start flows if we want the server, not CLI subprocesses, to be the sole write owner
|
||||
|
||||
- **Preserve local run-directory access where it is orthogonal to SlateDB.**
|
||||
- Run discovery still needs local run-dir paths for UI output and fallback/orphan detection.
|
||||
- Runtime interview files and launcher metadata remain file-based unless separately redesigned.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved for This Plan
|
||||
|
||||
- **Should we use the generated `fabro-api` client?**
|
||||
- Yes. It matches the repo direction and now works with Unix socket transport via reqwest.
|
||||
|
||||
- **Do we need a brand-new HTTP store crate first?**
|
||||
- No. Start with a thin CLI-side server client and only extract if a second consumer appears.
|
||||
|
||||
- **Does the server already expose enough snapshot data?**
|
||||
- Mostly yes. `RunProjection` already covers much more than the earlier plan assumed.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- Whether to model the new CLI-side access layer as:
|
||||
- a direct "server client" API, or
|
||||
- a local wrapper that mimics `SlateStore` / `SlateRunStore`
|
||||
- Whether artifact-list CLI should remain filesystem-based for local-only debugging or migrate fully to server-backed listing in phase 1
|
||||
- Whether detached engine execution should be migrated in the same branch or explicitly deferred behind a feature boundary
|
||||
|
||||
## Relevant Code and Patterns
|
||||
|
||||
### Daemon and Unix Socket Patterns
|
||||
|
||||
- `lib/crates/fabro-cli/src/commands/server/start.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/record.rs`
|
||||
- `lib/crates/fabro-server/src/serve.rs`
|
||||
- `lib/crates/fabro-server/src/bind.rs`
|
||||
|
||||
### Existing Generated Client
|
||||
|
||||
- `lib/crates/fabro-api/src/lib.rs`
|
||||
- `lib/crates/fabro-api/build.rs`
|
||||
- `docs/api-reference/fabro-api.yaml`
|
||||
|
||||
### Store-Backed Server Routes
|
||||
|
||||
- `lib/crates/fabro-server/src/server.rs`
|
||||
|
||||
### CLI Entry Points That Must Migrate
|
||||
|
||||
- `lib/crates/fabro-cli/src/store.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/runs/list.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/logs.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/attach.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/diff.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/ssh.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/output.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/store/dump.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/pr/create.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/pr/list.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/pr/view.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/runs/rm.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/system/df.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/artifact/list.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/artifact/cp.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/wait.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/preview.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/rewind.rs`
|
||||
|
||||
### Run Discovery Coupling
|
||||
|
||||
- `lib/crates/fabro-workflow/src/run_lookup.rs`
|
||||
|
||||
### Execution-Path Coupling
|
||||
|
||||
- `lib/crates/fabro-cli/src/commands/run/create.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/start.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/detached.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/resume.rs`
|
||||
|
||||
## High-Level Design
|
||||
|
||||
### Layer 1: CLI server-backed store access
|
||||
|
||||
`fabro-cli` gains a small client/bootstrap layer:
|
||||
|
||||
1. Resolve active server from `server.json`
|
||||
2. If absent or stale, auto-start daemon using existing lock/spawn/readiness logic
|
||||
3. Construct `reqwest::Client` bound to the Unix socket
|
||||
4. Construct `fabro_api::Client` with base URL like `http://fabro`
|
||||
5. Expose helper methods for:
|
||||
- run state
|
||||
- run events list
|
||||
- run events attach SSE stream
|
||||
- blob read/write
|
||||
- stage artifact list/read/write
|
||||
- durable run list
|
||||
- durable run delete
|
||||
|
||||
CLI command handlers stop calling `build_store()` and instead call a new helper such as:
|
||||
|
||||
`store::connect_server(storage_dir) -> Result<ServerStoreClient>`
|
||||
|
||||
### Layer 2: API parity for run discovery and deletion
|
||||
|
||||
The server adds durable endpoints for:
|
||||
|
||||
- listing runs from the store catalog rather than only in-memory managed runs
|
||||
- deleting run store state
|
||||
|
||||
The CLI keeps local run-dir fallback/orphan detection logic from `run_lookup.rs`, but its durable run summary source becomes the server.
|
||||
|
||||
### Layer 3: Optional execution consolidation
|
||||
|
||||
If we want strict compliance with "server is the only process accessing SlateDB", then detached/resume/start flows must stop opening run stores locally. That likely means:
|
||||
|
||||
- CLI creates/starts runs by calling server APIs
|
||||
- server-owned scheduler/executor performs writes
|
||||
- attach/logs become purely server-backed observers
|
||||
|
||||
This is separable from the read-path migration and should be treated as a deliberate second stage.
|
||||
|
||||
### Artifact handling boundary in phase 1
|
||||
|
||||
Artifact metadata and binary reads can move to server-backed endpoints in phase 1, but local run-directory artifact scanning may remain temporarily filesystem-based where commands are acting as local debugging tools rather than store clients. Implementation should make that boundary explicit rather than leaving a silent mixed-mode design.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [ ] **Unit 1: Add CLI server bootstrap and generated-client construction**
|
||||
|
||||
**Goal:** Replace raw local `SlateStore` bootstrap in `fabro-cli` with "find or start server, then connect over Unix socket".
|
||||
|
||||
**Requirements:** R1, R2, R4, R5, R8
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/store.rs`
|
||||
- Create: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs`
|
||||
- Modify: `lib/crates/fabro-cli/Cargo.toml`
|
||||
|
||||
**Approach:**
|
||||
- Add `ensure_server_running(storage_dir: &Path) -> Result<Bind>` in `server/start.rs` or a sibling helper module.
|
||||
- Reuse:
|
||||
- `acquire_lock`
|
||||
- `active_server_record`
|
||||
- daemon spawn path
|
||||
- readiness polling
|
||||
- Fast path: if `active_server_record()` exists, return its bind.
|
||||
- If no record exists, start the daemon on the default Unix socket path and wait for readiness.
|
||||
- In a new `server_client.rs`, build:
|
||||
- `reqwest::ClientBuilder::new().unix_socket(socket_path)`
|
||||
- `fabro_api::Client::new_with_client("http://fabro", reqwest_client)`
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/server/start.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/record.rs`
|
||||
- `lib/crates/fabro-api/src/lib.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Existing active server record returns immediately without spawning
|
||||
- Missing server record triggers daemon start and waits for readiness
|
||||
- Stale server record is ignored and replaced by a working daemon
|
||||
- Unix socket connection errors produce a clear CLI-facing error
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-cli`
|
||||
- targeted tests for server start/status helpers in `fabro-cli`
|
||||
|
||||
- [ ] **Unit 2: Add durable server endpoints needed for CLI parity**
|
||||
|
||||
**Goal:** Close the durable API gaps that block CLI migration.
|
||||
|
||||
**Requirements:** R2, R3, R4, R5
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/api-reference/fabro-api.yaml`
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs`
|
||||
- Modify: `lib/crates/fabro-api/build.rs` only if codegen constraints require it
|
||||
- Regenerate: `lib/crates/fabro-api` via normal build
|
||||
|
||||
**Required endpoints:**
|
||||
- `GET /api/v1/store/runs`
|
||||
- durable run summaries from `state.store.list_runs(...)`
|
||||
- `DELETE /api/v1/store/runs/{id}`
|
||||
- durable store deletion for a run
|
||||
|
||||
**Contract guardrail:**
|
||||
- Do not change existing `GET /api/v1/runs` response semantics in this unit.
|
||||
- The existing `/runs` route remains the board-oriented runtime view backed by `state.runs`.
|
||||
- Durable catalog access belongs on the distinct `/api/v1/store/runs` surface unless a separate reviewed plan intentionally merges the concepts.
|
||||
|
||||
**Optional endpoint for phase-1 cleanup if needed:**
|
||||
- `GET /api/v1/runs/{id}/artifacts`
|
||||
- if we decide to stop using local artifact directory scanning for listing/copy
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing store-backed handlers in `lib/crates/fabro-server/src/server.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Durable run list returns runs persisted before current server boot
|
||||
- Durable run delete removes store state for existing run
|
||||
- Deleting missing run is idempotent or returns a clearly documented 404 behavior
|
||||
- New endpoints are represented in `fabro-api` codegen output
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-api`
|
||||
- `cargo nextest run -p fabro-server`
|
||||
|
||||
- [ ] **Unit 3: Migrate run discovery to server-backed durable summaries**
|
||||
|
||||
**Goal:** Stop CLI run discovery from reading store summaries via direct `SlateStore`.
|
||||
|
||||
**Requirements:** R2, R3, R4
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/run_lookup.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/list.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/system/df.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/list.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/mod.rs`
|
||||
- Add tests in:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/`
|
||||
- `lib/crates/fabro-workflow` tests if `run_lookup` signatures change
|
||||
|
||||
**Approach:**
|
||||
- Decouple `run_lookup` from concrete `SlateStore` inputs.
|
||||
- Introduce a smaller input shape for durable summaries, likely:
|
||||
- a plain `Vec<RunSummary>`, or
|
||||
- a small trait implemented by both local tests and the new CLI client wrapper
|
||||
- Preserve local run-dir fallback/orphan detection from filesystem scanning.
|
||||
- Use server-provided durable summaries as the authoritative store source.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-workflow/src/run_lookup.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Persisted run appears in list even after server restart
|
||||
- Local orphan run still appears when store summary is absent
|
||||
- Prefix resolution still works against durable summaries plus local paths
|
||||
- `runs list` behavior remains unchanged for filters and JSON output
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli runs_list`
|
||||
- targeted `run_lookup` tests
|
||||
|
||||
- [ ] **Unit 4: Migrate read-heavy CLI commands to server-backed state/events/blob/artifact access**
|
||||
|
||||
**Goal:** Move the majority of CLI read flows off direct SlateDB access.
|
||||
|
||||
**Requirements:** R2, R3, R4, R6, R7, R8
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/logs.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/attach.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/diff.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/ssh.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/output.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/store/dump.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/create.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/view.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/wait.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/preview.rs`
|
||||
|
||||
**Approach:**
|
||||
- Replace direct `open_run_reader()` usage with calls to:
|
||||
- `get_run_state`
|
||||
- `list_run_events`
|
||||
- `attach_run_events`
|
||||
- `read_run_blob`
|
||||
- `list_stage_artifacts`
|
||||
- artifact download endpoint
|
||||
- Build one SSE parsing helper in CLI for `attach_run_events()` byte streams.
|
||||
- Continue using `RunProjection` as the coarse-grained read model.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-server/src/server.rs` attach SSE response shape
|
||||
- Existing CLI attach/log rendering logic
|
||||
|
||||
**Test scenarios:**
|
||||
- `logs --follow` continues to stream events to completion
|
||||
- `attach` replays existing events then follows live events
|
||||
- state-driven commands still read final patch, PR data, sandbox, checkpoint, and retro from `RunProjection`
|
||||
- blob and artifact download remain raw bytes
|
||||
|
||||
**Verification:**
|
||||
- targeted `fabro-cli` command tests:
|
||||
- logs
|
||||
- attach
|
||||
- diff
|
||||
- pr view/create
|
||||
- store dump
|
||||
|
||||
- [ ] **Unit 5: Migrate write/delete CLI operations that should hit the server**
|
||||
|
||||
**Goal:** Stop CLI deletion and similar store mutations from touching SlateDB directly.
|
||||
|
||||
**Requirements:** R2, R3, R4, R8
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/rm.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/start.rs` if status validation moves to server reads only
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/rewind.rs` only if it currently depends on direct store writes in the targeted path
|
||||
|
||||
**Approach:**
|
||||
- Replace direct `store.delete_run()` calls with server API delete.
|
||||
- Replace direct event append for `RunRemoving` with `POST /runs/{id}/events`.
|
||||
- Keep local run-dir deletion and sandbox cleanup local unless a server-owned deletion flow is explicitly introduced.
|
||||
|
||||
**Test scenarios:**
|
||||
- removing a completed run deletes local run dir and durable store state
|
||||
- removing a run with missing store state still behaves predictably
|
||||
- server-unreachable deletion path returns actionable error text
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli runs_rm`
|
||||
|
||||
- [ ] **Unit 6: Decide and document the execution-ownership boundary**
|
||||
|
||||
**Goal:** Explicitly close the gap between "CLI reads via server" and "server is the only process accessing SlateDB".
|
||||
|
||||
**Requirements:** R3, R9
|
||||
|
||||
**Files:**
|
||||
- Modify: this plan document after implementation decision, or create follow-on plan
|
||||
- Review:
|
||||
- `lib/crates/fabro-cli/src/commands/run/create.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/start.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/detached.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/resume.rs`
|
||||
|
||||
**Decision fork:**
|
||||
|
||||
Option A: **Phase-1 complete means CLI read/write store access is server-backed, but local engine subprocesses remain**
|
||||
- Faster
|
||||
- Leaves a strict reading of R3 partially unmet
|
||||
|
||||
Option B: **Phase-2 also migrates execution ownership to the server**
|
||||
- CLI create/start/resume become HTTP calls
|
||||
- Detached local engine path is retired or reduced to server-only launch
|
||||
- Strictly satisfies "server is the only process accessing SlateDB"
|
||||
|
||||
**Recommendation:**
|
||||
- Treat Option A as the first implementation milestone
|
||||
- Open a follow-on plan immediately for Option B if the requirement remains strict
|
||||
|
||||
**Implementation note (2026-04-04):**
|
||||
- This branch follows Option A.
|
||||
- CLI durable run discovery, wait/logs/diff/preview/PR listing, and run deletion are moving behind the server-backed store client.
|
||||
- Detached/create/start/resume execution ownership remains local for now and still needs a follow-on server-owned execution plan if strict single-owner SlateDB semantics remain required.
|
||||
|
||||
**Test scenarios:**
|
||||
- explicit documentation of whichever boundary we choose
|
||||
- no silent mixing of local-store and server-store code paths remains after the chosen milestone
|
||||
|
||||
## Sequencing
|
||||
|
||||
1. Unit 1 first: auto-start and client bootstrap
|
||||
2. Unit 2 second: add missing durable API surface
|
||||
3. Unit 3 third: migrate run discovery and durable summary reads
|
||||
4. Unit 4 fourth: migrate read-heavy commands
|
||||
5. Unit 5 fifth: migrate store mutations that still happen in CLI
|
||||
6. Unit 6 last: finalize the execution-ownership boundary and either defer or continue
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
- **Risk: `/api/v1/runs` semantics are runtime-board state, not durable store state**
|
||||
- Mitigation: add distinct `/api/v1/store/runs` routes rather than silently repurposing `/runs`
|
||||
|
||||
- **Risk: `run_lookup` is coupled to concrete `SlateStore`**
|
||||
- Mitigation: extract a smaller durable-summary input shape before touching multiple commands
|
||||
|
||||
- **Risk: SSE parsing via generated client is lower-level than current in-process stream usage**
|
||||
- Mitigation: centralize byte-stream-to-event parsing in one helper and cover it with focused tests
|
||||
|
||||
- **Risk: some CLI commands still depend on local runtime files rather than store data**
|
||||
- Mitigation: migrate only true store access in this plan; do not conflate run-dir filesystem concerns with SlateDB consolidation
|
||||
|
||||
- **Risk: execution paths still open the store directly after read-path migration**
|
||||
- Mitigation: explicitly treat execution consolidation as a tracked decision point, not an accidental omission
|
||||
|
||||
## Verification Strategy
|
||||
|
||||
Per-unit targeted verification:
|
||||
|
||||
- `cargo build -p fabro-api`
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo nextest run -p fabro-cli`
|
||||
|
||||
Focused command coverage should include:
|
||||
|
||||
- server start/status/stop
|
||||
- runs list
|
||||
- logs
|
||||
- attach
|
||||
- diff
|
||||
- pr view/create/list
|
||||
- runs rm
|
||||
- store dump
|
||||
|
||||
Manual smoke flow after Units 1-5:
|
||||
|
||||
1. stop any running server
|
||||
2. run a CLI command that needs store access
|
||||
3. verify server auto-starts
|
||||
4. verify the command succeeds through the Unix socket path
|
||||
5. verify no CLI path in the tested flow opens local SlateDB directly
|
||||
|
||||
Durability smoke flow:
|
||||
|
||||
1. create or identify a persisted run
|
||||
2. stop the server
|
||||
3. start the server again
|
||||
4. verify durable run listing still finds the run through the HTTP path
|
||||
5. verify run state for that run is still readable through the HTTP path
|
||||
|
||||
## Change Summary
|
||||
|
||||
The old plan is no longer the right implementation guide. The repo already has daemon management, Unix socket support, store-backed server endpoints, and a generated Rust client that can be used over UDS. The remaining plan is to:
|
||||
|
||||
- auto-start the server from CLI store bootstrap
|
||||
- use `fabro-api::Client` over Unix socket
|
||||
- add the missing durable run-list/delete endpoints
|
||||
- migrate CLI store consumers off direct `SlateStore`
|
||||
- then explicitly decide whether execution ownership also moves fully into the server
|
||||
|
|
@ -1,74 +0,0 @@
|
|||
# Simplify `RunEvent` While Keeping Wire JSON Stable
|
||||
|
||||
## Summary
|
||||
- Refactor the event model so `RunEvent` stores only envelope metadata plus a typed `EventBody`; the JSON wire format stays `{ ..., "event": "...", "properties": { ... } }`.
|
||||
- Treat this as an internal Rust API break now: remove public `RunEvent.event` and `RunEvent.properties`, update repo call sites in one pass, and align the code with `docs-internal/events-strategy.md`'s "canonical envelope built once" rule.
|
||||
- Preserve forward-compatibility for unknown stored events explicitly instead of relying on duplicate cached fields.
|
||||
- Phase the refactor into three commits so the direct `Event -> RunEvent` mapping can land and be verified before the cached-field removal.
|
||||
|
||||
## Implementation Changes
|
||||
- Sequencing
|
||||
- Commit 1: add `EventBody::event_name() -> &str`, remove `event_name_from_body()` and `properties_from_body()`, and replace both with explicit implementations that keep cached fields working through commits 1 and 2.
|
||||
- Commit 2: rework `fabro-workflow` to construct `RunEvent` directly from `Event`; this is the main structural refactor and the primary regression risk.
|
||||
- Commit 3: remove cached `RunEvent.event` / `RunEvent.properties`, update callers and tests, and replace `EventBody::Unknown` with a raw-preserving variant.
|
||||
- `lib/crates/fabro-types/src/run_event/mod.rs`
|
||||
- Redefine `RunEvent` to contain `id`, `ts`, `run_id`, optional envelope metadata, and `body: EventBody` only.
|
||||
- Keep `RunEvent::from_value`, `from_json_str`, and `to_value`, but make them thin wire-boundary helpers around a private raw wire struct for `{ event, properties }`.
|
||||
- Replace `EventBody::Unknown` with a raw-preserving variant such as `Unknown { name: String, properties: Value }`.
|
||||
- Add `EventBody::event_name() -> &str` implemented as an exhaustive `match` returning the serde rename string for each known variant and `name.as_str()` for `Unknown`.
|
||||
- In commit 1, replace `properties_from_body()` with an explicit property-serialization helper that derives the inner properties payload without the current serialize-and-pluck helper pattern; it may still serialize as an interim step, but it should exist only to support cached fields and wire serialization during the transition.
|
||||
- Keep JSON property extraction as a serialization helper, not a hot-path public API. Use it only in `RunEvent::to_value` / `Serialize` and in wire-shape tests that need JSON-level assertions.
|
||||
- Remove `refresh_cache`, `event_name_from_body`, and `properties_from_body`.
|
||||
- Call out unknown-event fallback explicitly: `Unknown { name, properties }` cannot rely on `#[serde(other)]`, so `RunEvent::from_value` must use a custom fallback path that preserves raw `event` and `properties` when typed `EventBody` deserialization fails.
|
||||
- `lib/crates/fabro-workflow/src/event.rs`
|
||||
- Split the current conversion into two explicit pieces: envelope metadata extraction and `Event -> EventBody` construction.
|
||||
- Rework `to_run_event_at()` to build `RunEvent` directly, not via `json!` plus `RunEvent::from_value`.
|
||||
- Keep all existing canonicalization rules, but express them as Rust matches: `run_id` stripping, node/session extraction, node-label defaults, failure/error normalization, and agent/sandbox nested event flattening.
|
||||
- Treat `Event::Agent` and `Event::Sandbox` as the bulk of the work:
|
||||
- `Event::Agent` must expand each `AgentEvent` sub-variant into the corresponding `EventBody` variant while also lifting `stage -> node_id`, preserving `session_id` / `parent_session_id` in the envelope, and merging `visit` into the inner props where required.
|
||||
- `Event::Sandbox` must unwrap each `SandboxEvent` sub-variant into the corresponding `EventBody` variant while preserving the current flattened wire shape.
|
||||
- `Event::WorkflowRunFailed` must continue converting `FabroError` into the stored string form used by `RunFailedProps`.
|
||||
- stage/parallel/prompt/watchdog variants must continue moving `node_id`/`stage`/`branch`/`node` into the envelope with the same current `node_label` defaults.
|
||||
- Make the lossy cross-crate conversions explicit in the implementation and guard them with wire-shape characterization tests:
|
||||
- `fabro_agent::AgentError -> String`
|
||||
- `fabro_llm::error::SdkError -> string fields in retry props`
|
||||
- `fabro_llm` usage types -> `fabro_types` usage structs
|
||||
- `fabro_workflow::error::FabroError -> String`
|
||||
- Delete `tagged_variant_fields*` once all variant mapping is direct and covered by tests.
|
||||
- Keep redaction/persistence logic driven by serialized `RunEvent` wire value; no wire-shape change and no redaction contract change.
|
||||
- Explicitly keep the `build_redacted_event_payload` pipeline out of scope for this pass: no changes to `to_value() -> normalize -> to_string -> redact -> from_str`.
|
||||
- `lib/crates/fabro-store/src/types.rs`, `lib/crates/fabro-store/src/run_state.rs`, and repo consumers
|
||||
- Update call sites to stop reading `RunEvent.event` and `RunEvent.properties` directly.
|
||||
- Default rule: production consumers match on `body`; only serialization/wire tests should rely on JSON property extraction.
|
||||
- Route store decoding through one helper path (`TryFrom<&EventPayload>` or `RunEvent::from_value`) and keep clone-based payload parsing for now; zero-copy parsing is out of scope for this pass.
|
||||
- Update strategy/docs terminology only, not code naming: leave `RunEvent` as the code type in this pass and align `docs-internal/events-strategy.md` if needed.
|
||||
|
||||
## Test Plan
|
||||
- `lib/crates/fabro-types/src/run_event/mod.rs`
|
||||
- known event round-trip preserves the wire JSON shape
|
||||
- unknown event round-trip preserves raw `event` and `properties`
|
||||
- known event name with invalid properties still fails deserialization
|
||||
- absent optional envelope fields serialize as omitted fields, not `null`
|
||||
- `lib/crates/fabro-workflow/src/event.rs`
|
||||
- characterization tests for representative variants: stage event, agent event, sandbox event, and run failure
|
||||
- assert direct construction produces the same wire JSON and envelope fields as today
|
||||
- assert `build_redacted_event_payload` still returns a valid `EventPayload`
|
||||
- add focused coverage for agent flattening and sandbox flattening, since those wrappers are the highest-risk conversion paths
|
||||
- `lib/crates/fabro-store/src/run_state.rs` or adjacent store tests
|
||||
- replay persisted payloads into `RunProjection` still reconstructs run, status, checkpoint, retro, and pull-request state correctly
|
||||
- Test migration rules
|
||||
- behavior tests should prefer matching on typed `body` instead of reintroducing JSON-shaped assertions
|
||||
- wire-contract tests should assert on `to_value()` / serialized JSON when the exact `properties` shape matters
|
||||
- do not replace all former `stored.properties["foo"]` assertions with a general-purpose allocating helper in production code
|
||||
- `fabro-cli/src/commands/run/run_progress/event.rs::from_run_event()` is already aligned with the target design because it matches on `EventBody`; only any remaining CLI tests asserting through `stored.properties` need migration in commit 3
|
||||
- Verification
|
||||
- run `cargo nextest run -p fabro-types`
|
||||
- run `cargo nextest run -p fabro-workflow`
|
||||
- run `cargo nextest run -p fabro-store`
|
||||
- run `cargo fmt --check --all` and `cargo clippy --workspace -- -D warnings`
|
||||
|
||||
## Assumptions
|
||||
- The JSON wire protocol stays compatible; only the internal Rust representation and helper APIs change.
|
||||
- Internal Rust API break is acceptable now; tests and internal consumers will be updated in the same pass.
|
||||
- Unknown stored events are a supported forward-compatibility case and must survive parse/serialize unchanged.
|
||||
- This pass optimizes for simplicity and maintainability first; deeper read-side performance work such as borrowed parsing, eliminating `Value` clones in projection, or optimizing the redaction pipeline can follow separately.
|
||||
|
|
@ -1,126 +0,0 @@
|
|||
# Shared Test Storage + Production Auto-Start for CLI Tests
|
||||
|
||||
## Summary
|
||||
Use one shared test `storage_dir` per test session and rely on the existing production auto-start behavior to converge on a single shared daemon for that storage root.
|
||||
|
||||
Session identity rules:
|
||||
- when `NEXTEST_RUN_ID` is present, use one shared storage dir for the full `cargo nextest run`
|
||||
- when `NEXTEST_RUN_ID` is absent, use one shared storage dir per test process
|
||||
|
||||
The test harness will not implement its own daemon bootstrap protocol. Instead:
|
||||
- every test process points `FABRO_STORAGE_DIR` at the same test-run storage root
|
||||
- the first CLI command that needs the daemon triggers normal production auto-start
|
||||
- existing `server.lock`, `server.json`, and `fabro.sock` behavior prevents duplicate servers for that shared storage dir
|
||||
- the test harness is responsible only for:
|
||||
- selecting the shared test storage root
|
||||
- making test assertions/helpers safe under shared storage
|
||||
- cleaning up the shared daemon and temp root at the end of the test run
|
||||
|
||||
This keeps test behavior aligned with production daemon identity semantics.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Shared `storage_dir` in `fabro-test`
|
||||
In `lib/crates/fabro-test/src/lib.rs`:
|
||||
- Change `TestContext::new` to detect `NEXTEST_RUN_ID`.
|
||||
- Derive a shared test root under temp:
|
||||
- if `NEXTEST_RUN_ID` is present: `$TMPDIR/fabro-nextest/<NEXTEST_RUN_ID>/`
|
||||
- otherwise: `$TMPDIR/fabro-test-process/<pid>/`
|
||||
- shared storage dir: `<root>/storage`
|
||||
- Keep `temp_dir` and `home_dir` per context; only `storage_dir` becomes shared for the session.
|
||||
- Do not explicitly start the daemon from the harness.
|
||||
- Keep using the normal CLI command path so the first server-backed command triggers production auto-start against the shared storage dir.
|
||||
- Add concrete session cleanup coordination using marker files:
|
||||
- under the session root, create `clients/<pid>` marker files
|
||||
- protect create/remove/scan operations with a session lock file
|
||||
- on `TestContext` init:
|
||||
- acquire lock
|
||||
- create or refresh this process marker
|
||||
- remove stale markers for dead PIDs
|
||||
- release lock
|
||||
- on process teardown:
|
||||
- acquire lock
|
||||
- remove this process marker
|
||||
- remove any other stale dead markers
|
||||
- if no markers remain, call `fabro server stop --storage-dir <shared>` and remove the shared temp root
|
||||
- release lock
|
||||
- Crash behavior:
|
||||
- crashed processes may leave stale markers behind
|
||||
- future init/teardown paths reap dead markers under the same lock
|
||||
- teardown cleanup is best-effort; if `fabro server stop` or root removal fails, later harness initialization remains responsible for authoritative stale-session reaping
|
||||
- Add stale-run cleanup on harness initialization:
|
||||
- scan old `fabro-nextest/*` roots
|
||||
- if all tracked PIDs for a root are dead, stop any server tied to that root and remove it
|
||||
- likewise scan old `fabro-test-process/*` roots and reap dead process-owned sessions
|
||||
|
||||
The harness should only coordinate test-run ownership and cleanup, not daemon startup.
|
||||
|
||||
### 2. Per-test labeling for shared-state safety
|
||||
Add a per-`TestContext` test case ULID and expose:
|
||||
- `fabro_test_run=<NEXTEST_RUN_ID>`
|
||||
- `fabro_test_case=<test-case-ulid>`
|
||||
|
||||
Update run-creation helpers to append these labels to created runs:
|
||||
- `run`
|
||||
- `create`
|
||||
- detached/create-start helpers
|
||||
- any workflow fixture helpers that create runs internally
|
||||
|
||||
Use existing production `--label KEY=VALUE` support; do not invent a new namespacing mechanism.
|
||||
|
||||
### 3. Replace isolated-storage helper assumptions
|
||||
Update helpers in:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/support.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/workflow/mod.rs`
|
||||
|
||||
Specifically:
|
||||
- remove helpers that assume there is exactly one run in `storage_dir/runs`
|
||||
- replace `only_run(context)`-style logic with:
|
||||
- exact run-id lookup when the helper already has the run id, or
|
||||
- test-case-label-based lookup when the helper needs to discover “the run created by this test”
|
||||
- keep direct store inspection helpers, but always resolve a concrete run first
|
||||
|
||||
### 4. Make shared-daemon tests robust
|
||||
Update tests to match the shared-daemon model:
|
||||
- exact-run tests remain strict and use ULIDs directly
|
||||
- global/listing tests (`ps`, `runs list`, `system df`, workflow-slug/recency lookup) should assert the presence/properties of the current test’s run(s), not exact global emptiness/counts unless explicitly scoped
|
||||
- when a command offers structured output, prefer parsing that output and filtering to the current test’s run(s) over broad transcript snapshots or loose substring matching
|
||||
- destructive tests must always be scoped:
|
||||
- exact run IDs when possible
|
||||
- otherwise use existing `--label` filters
|
||||
- broad destructive operations like “delete everything” are not allowed in shared-daemon tests
|
||||
|
||||
Rewrite current tests that depend on ambient exclusivity, especially:
|
||||
- helpers asserting a single run in storage
|
||||
- `ps` tests expecting global count equality
|
||||
- `system prune` tests filtering only by common workflow names like `Simple`
|
||||
|
||||
## Important Interface / Behavior Changes
|
||||
- `fabro-test::TestContext` uses a shared `storage_dir` per nextest run when `NEXTEST_RUN_ID` is set.
|
||||
- Test-created runs gain deterministic labels:
|
||||
- `fabro_test_run`
|
||||
- `fabro_test_case`
|
||||
- Test code must treat shared storage as normal under nextest and avoid assumptions based on storage exclusivity.
|
||||
|
||||
## Test Plan
|
||||
- `fabro-test` coverage:
|
||||
- multiple contexts in one nextest run resolve to the same shared storage dir
|
||||
- multiple contexts without `NEXTEST_RUN_ID` but in the same process resolve to the same shared storage dir
|
||||
- contexts still get distinct `temp_dir` and `home_dir`
|
||||
- marker-file cleanup removes stale prior session roots
|
||||
- last-process cleanup stops the daemon and removes the shared root
|
||||
- CLI integration updates:
|
||||
- helper coverage for resolving runs by exact ULID or test-case label
|
||||
- `ps`, `runs list`, and `system prune` tests updated to shared-storage-safe assertions
|
||||
- destructive tests verified to target only test-owned runs
|
||||
- End-to-end acceptance:
|
||||
- a full `cargo nextest run -p fabro-cli` should converge on one daemon per `NEXTEST_RUN_ID` storage root
|
||||
- a `cargo test --workspace` invocation should converge on one daemon per test process, not per `TestContext`
|
||||
- after the run, no test-owned `fabro.sock` daemon remains for that root
|
||||
- add an early validation test or harness check that concurrent auto-start against the same shared `storage_dir` converges on one daemon under parallel load
|
||||
|
||||
## Assumptions and Defaults
|
||||
- Production auto-start semantics for a single `storage_dir` are the source of truth and already provide duplicate-server protection via the existing lock/record path.
|
||||
- `NEXTEST_RUN_ID` is used when available to derive the shared nextest-run root; otherwise the current process PID is used to derive a shared per-process root.
|
||||
- The shared test storage root is fully separate from production storage in both modes.
|
||||
- No separate harness-managed daemon bootstrap protocol is added.
|
||||
- No changes to production daemon lifetime semantics are part of this plan.
|
||||
|
|
@ -1,419 +0,0 @@
|
|||
# CLI De-globalize Server URL And Storage Dir
|
||||
|
||||
## Summary
|
||||
Make `--storage-dir` and `--server-url` command-scoped instead of global so the CLI surface matches the architecture we now have.
|
||||
|
||||
This pass should:
|
||||
|
||||
- keep only truly global flags in `GlobalArgs`
|
||||
- move local-storage selection onto the commands that actually use local storage
|
||||
- move remote-server selection onto the commands that actually support remote targeting
|
||||
- remove false affordances from help output, docs, and env-var wiring
|
||||
|
||||
This plan is the direct follow-on to [2026-04-05-next-steps-after-cli-mode-removal.md](../ideation/2026-04-05-next-steps-after-cli-mode-removal.md).
|
||||
|
||||
## Scope Boundaries
|
||||
In scope:
|
||||
- de-globalize `--storage-dir` / `FABRO_STORAGE_DIR`
|
||||
- de-globalize `--server-url` / `FABRO_SERVER_URL`
|
||||
- update clap types, parser tests, dispatch signatures, and command help
|
||||
- keep `model` and `exec` behavior consistent with the recent cleanup, but expressed through command-local args
|
||||
- update docs/examples that still show top-level target flags
|
||||
|
||||
Out of scope:
|
||||
- changing server/runtime behavior for `run`, `model`, or `exec`
|
||||
- adding new remote-capable commands
|
||||
- making `exec` server-owned
|
||||
- changing `[server].base_url` semantics again
|
||||
- broad config/schema changes outside the CLI arg surface
|
||||
|
||||
## Problem Frame
|
||||
The code no longer has a meaningful whole-program “mode”, but the CLI still advertises target-selection flags as if every command can choose between local storage and a remote server.
|
||||
|
||||
That is now misleading in several different ways:
|
||||
|
||||
- many commands still show `--server-url` even though they never use it
|
||||
- many commands still show `--storage-dir` even though they do not read local runtime state
|
||||
- docs still describe these flags as global CLI surface area
|
||||
- help snapshot churn is broader than the real behavior surface because the flags leak into unrelated commands
|
||||
|
||||
The goal is not to invent new behavior. The goal is to make the CLI honest about which commands actually support which target-selection controls.
|
||||
|
||||
## Key Decisions
|
||||
- `GlobalArgs` remains, but only for true global flags:
|
||||
- `--json`
|
||||
- `--debug`
|
||||
- `--no-upgrade-check`
|
||||
- `--quiet`
|
||||
- `--verbose`
|
||||
- `--storage-dir` and `--server-url` stop being top-level/global clap args entirely.
|
||||
- target-selection args belong to leaf commands, not parent namespaces.
|
||||
- Rationale: keep natural syntax such as:
|
||||
- `fabro run foo.fabro --storage-dir /tmp/fabro`
|
||||
- `fabro model list --server-url https://fabro.example.com/api/v1`
|
||||
- `fabro server start --storage-dir /tmp/fabro`
|
||||
- Avoid awkward parent-namespace syntax like `fabro model --server-url ... list`.
|
||||
- `FABRO_STORAGE_DIR` and `FABRO_SERVER_URL` remain supported, but only for commands that define the corresponding arg.
|
||||
- command-local target syntax becomes the supported surface.
|
||||
- Old forms like `fabro --server-url ... model list` and `fabro --storage-dir ... run ...` are intentionally removed in this pass.
|
||||
- during implementation, temporary duplication between global target args and the new leaf-command args is acceptable.
|
||||
- Rationale: this refactor touches many commands, so the migration should stay compile-safe until the old global fields are fully unused and can be removed in one cleanup step.
|
||||
- `settings` keeps `--storage-dir`, because it changes the resolved local settings output.
|
||||
- `settings` does not keep `--server-url`.
|
||||
- Rationale: command-local remote target overrides should not masquerade as merged durable config.
|
||||
- `preflight` keeps `--storage-dir`, because it resolves a local run-oriented settings stack and should continue to allow explicit local storage selection.
|
||||
- `exec` keeps only `--server-url`.
|
||||
- `exec` does not need `--storage-dir`.
|
||||
- `model list` and `model test` keep both:
|
||||
- `--server-url` for explicit remote server targeting
|
||||
- `--storage-dir` for explicit local auto-start/storage selection
|
||||
- the existing `model` config/defaulting contract stays intact:
|
||||
- explicit `--server-url` wins
|
||||
- explicit `--storage-dir` suppresses configured `[server].base_url`
|
||||
- otherwise `model` may default to configured `[server].base_url`
|
||||
- the existing `exec` contract stays intact:
|
||||
- server routing only happens when the command-local `server_url` value is set, whether by CLI flag or `FABRO_SERVER_URL`
|
||||
- configured `[server].base_url` alone still does not reroute `exec`
|
||||
- `fabro model` with no subcommand remains the convenience alias for default listing behavior.
|
||||
- target overrides are not a compatibility goal for the bare alias in this pass; users should use `fabro model list ...` when specifying target args explicitly.
|
||||
|
||||
## Command Matrix
|
||||
### `--server-url` only
|
||||
- `fabro exec`
|
||||
|
||||
### `--storage-dir` and `--server-url`
|
||||
- `fabro model list`
|
||||
- `fabro model test`
|
||||
|
||||
### `--storage-dir` only
|
||||
- `fabro run`
|
||||
- `fabro create`
|
||||
- `fabro start`
|
||||
- `fabro attach`
|
||||
- `fabro logs`
|
||||
- `fabro resume`
|
||||
- `fabro rewind`
|
||||
- `fabro fork`
|
||||
- `fabro wait`
|
||||
- `fabro diff`
|
||||
- hidden `fabro __runner`
|
||||
- `fabro ps`
|
||||
- `fabro rm`
|
||||
- `fabro inspect`
|
||||
- `fabro artifact list`
|
||||
- `fabro artifact cp`
|
||||
- `fabro sandbox cp`
|
||||
- `fabro sandbox preview`
|
||||
- `fabro sandbox ssh`
|
||||
- `fabro store dump`
|
||||
- `fabro pr create`
|
||||
- `fabro pr list`
|
||||
- `fabro pr view`
|
||||
- `fabro pr merge`
|
||||
- `fabro pr close`
|
||||
- `fabro system prune`
|
||||
- `fabro system df`
|
||||
- `fabro server start`
|
||||
- `fabro server stop`
|
||||
- `fabro server status`
|
||||
- hidden `fabro server __serve`
|
||||
- `fabro settings`
|
||||
- `fabro preflight`
|
||||
|
||||
### Neither target arg
|
||||
- `fabro validate`
|
||||
- `fabro graph`
|
||||
- `fabro parse`
|
||||
- `fabro doctor`
|
||||
- `fabro install`
|
||||
- `fabro repo init`
|
||||
- `fabro repo deinit`
|
||||
- `fabro workflow list`
|
||||
- `fabro workflow create`
|
||||
- `fabro provider login`
|
||||
- hidden `fabro skill install`
|
||||
- `fabro secret get`
|
||||
- `fabro secret list`
|
||||
- `fabro secret set`
|
||||
- `fabro secret rm`
|
||||
- `fabro docs`
|
||||
- `fabro discord`
|
||||
- `fabro completion`
|
||||
- `fabro upgrade`
|
||||
- internal analytics/panic commands
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Narrow `GlobalArgs` and add command-scoped target arg structs
|
||||
In `lib/crates/fabro-cli/src/args.rs`:
|
||||
- add the new command-scoped target arg structs first, while temporarily leaving `storage_dir` and `server_url` on `GlobalArgs`
|
||||
- keep `GlobalArgs` as the long-term home only for the true-global output/logging/upgrade-check surface
|
||||
- add small reusable arg structs:
|
||||
- `StorageDirArgs { storage_dir: Option<PathBuf> }`
|
||||
- `ServerUrlArgs { server_url: Option<String> }`
|
||||
- `ModelTargetArgs { storage_dir: Option<PathBuf>, server_url: Option<String> }`
|
||||
- keep the `storage_dir` / `server_url` conflict on `ModelTargetArgs`
|
||||
- keep the existing env bindings:
|
||||
- `FABRO_STORAGE_DIR`
|
||||
- `FABRO_SERVER_URL`
|
||||
|
||||
This temporary duplication is intentional. The crate should continue to compile while commands migrate off `GlobalArgs`.
|
||||
|
||||
Because the target args will now live on leaf commands, convert inline/anonymous clap variants into explicit args structs where needed. The important conversions are:
|
||||
- `Exec(AgentArgs)` -> `Exec(ExecArgs)` where `ExecArgs` flattens:
|
||||
- `ServerUrlArgs`
|
||||
- `fabro_agent::cli::AgentArgs`
|
||||
- `ModelsCommand::List { ... }` -> `ModelsCommand::List(ModelListArgs)`
|
||||
- `ModelsCommand::Test { ... }` -> `ModelsCommand::Test(ModelTestArgs)`
|
||||
- `RunCommands::Start { run: String }` -> `RunCommands::Start(StartArgs)` where `StartArgs` flattens `StorageDirArgs`
|
||||
- `RunCommands::Attach { run: String }` -> `RunCommands::Attach(AttachArgs)` where `AttachArgs` flattens `StorageDirArgs`
|
||||
- `RunCommands::Runner { ... }` -> `RunCommands::Runner(RunnerArgs)` where `RunnerArgs` flattens `StorageDirArgs`
|
||||
- `ServerCommand::Start { ... }` -> `ServerCommand::Start(ServerStartArgs)` where `ServerStartArgs` flattens:
|
||||
- `StorageDirArgs`
|
||||
- the existing `foreground` flag
|
||||
- `ServeArgs`
|
||||
- `ServerCommand::Stop { ... }` -> `ServerCommand::Stop(ServerStopArgs)` where `ServerStopArgs` flattens `StorageDirArgs`
|
||||
- `ServerCommand::Status { ... }` -> `ServerCommand::Status(ServerStatusArgs)` where `ServerStatusArgs` flattens `StorageDirArgs`
|
||||
- `ServerCommand::Serve { ... }` -> `ServerCommand::Serve(ServerServeArgs)` where `ServerServeArgs` flattens:
|
||||
- `StorageDirArgs`
|
||||
- the existing `record_path` field
|
||||
- `ServeArgs`
|
||||
|
||||
Also flatten `StorageDirArgs` into the leaf arg types that currently rely on global storage selection, including:
|
||||
- `RunArgs`
|
||||
- `LogsArgs`
|
||||
- `DiffArgs`
|
||||
- `ResumeArgs`
|
||||
- `RewindArgs`
|
||||
- `ForkArgs`
|
||||
- `WaitArgs`
|
||||
- `RunsListArgs`
|
||||
- `RunsRemoveArgs`
|
||||
- `InspectArgs`
|
||||
- `ArtifactListArgs`
|
||||
- `ArtifactCpArgs`
|
||||
- `CpArgs`
|
||||
- `PreviewArgs`
|
||||
- `SshArgs`
|
||||
- `StoreDumpArgs`
|
||||
- `PrCreateArgs`
|
||||
- `PrListArgs`
|
||||
- `PrViewArgs`
|
||||
- `PrMergeArgs`
|
||||
- `PrCloseArgs`
|
||||
- `RunsPruneArgs`
|
||||
- `DfArgs`
|
||||
- `SettingsArgs`
|
||||
- `PreflightArgs`
|
||||
|
||||
### 2. Rework parser and dispatch wiring around leaf-command target args
|
||||
In `lib/crates/fabro-cli/src/main.rs`:
|
||||
- keep `Cli { globals, command }`, but with the narrower `GlobalArgs`
|
||||
- update dispatch pattern matches to use the new wrapper arg structs:
|
||||
- `ExecArgs`
|
||||
- `ModelListArgs`
|
||||
- `ModelTestArgs`
|
||||
- `StartArgs`
|
||||
- `AttachArgs`
|
||||
- `RunnerArgs`
|
||||
- replace parser tests that assume global target flags with command-local parser tests
|
||||
|
||||
Parser behavior to lock down:
|
||||
- `fabro run test/simple.fabro --storage-dir /tmp/fabro` parses
|
||||
- `fabro model list --server-url http://localhost:3000/api/v1` parses
|
||||
- `fabro exec --server-url http://localhost:3000/api/v1 "prompt"` parses
|
||||
- `fabro model list --storage-dir /tmp/fabro --server-url http://localhost:3000/api/v1` fails with the command-local conflict
|
||||
- `fabro --server-url http://localhost:3000/api/v1 model list` no longer parses
|
||||
- `fabro --storage-dir /tmp/fabro run test/simple.fabro` no longer parses
|
||||
|
||||
These parser assertions belong at the end of the migration, after `storage_dir` and `server_url` have actually been removed from `GlobalArgs`. Before that cleanup step, the old top-level forms will still parse and should not be treated as failures yet.
|
||||
|
||||
### 3. Replace “with globals” settings helpers with explicit local/remote override helpers
|
||||
The current helper layer in `lib/crates/fabro-cli/src/user_config.rs` is still shaped around global target args. That should be simplified to explicit command-local override helpers.
|
||||
|
||||
In `lib/crates/fabro-cli/src/user_config.rs`:
|
||||
- remove or rename the generic helpers that imply target args are global:
|
||||
- `user_layer_with_globals(...)`
|
||||
- `load_user_settings_with_globals(...)`
|
||||
- `apply_global_overrides(...)`
|
||||
- replace them with explicit helpers such as:
|
||||
- `user_layer_with_storage_dir(storage_dir: Option<&Path>) -> anyhow::Result<ConfigLayer>`
|
||||
- `load_user_settings_with_storage_dir(storage_dir: Option<&Path>) -> anyhow::Result<Settings>`
|
||||
- `exec_server_target(args: &ServerUrlArgs, settings: &Settings) -> Option<ServerTarget>`
|
||||
- `model_server_target(args: &ModelTargetArgs, settings: &Settings) -> Option<ServerTarget>`
|
||||
- keep `build_server_client(...)`
|
||||
|
||||
Behavior to preserve:
|
||||
- local-storage commands can still resolve settings with an explicit storage-dir override
|
||||
- `model` keeps its existing defaulting behavior
|
||||
- `exec` only resolves a remote target when its command-local `server_url` value is set
|
||||
- TLS continues to come from `[server].tls` when a remote target is selected
|
||||
|
||||
### 4. Repoint command implementations to explicit target args
|
||||
Update the commands that currently read target selection through `GlobalArgs`.
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/model.rs`:
|
||||
- switch from `GlobalArgs`-based target lookup to `ModelTargetArgs`
|
||||
- keep the recent server-canonical behavior unchanged
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/exec.rs`:
|
||||
- switch from `GlobalArgs`-based target lookup to `ServerUrlArgs`
|
||||
- remove any remaining dependence on `storage_dir`
|
||||
- load settings with plain `load_user_settings()`, not a storage-dir-aware helper
|
||||
- `exec` does not need local storage override semantics anymore
|
||||
- it should then pass `&ServerUrlArgs` to `exec_server_target(...)`
|
||||
|
||||
In the local-storage command modules:
|
||||
- replace `load_user_settings_with_globals(globals)` with the explicit storage-dir helper
|
||||
- read `storage_dir` from the command’s own args struct, not from `globals`
|
||||
|
||||
Key files here include:
|
||||
- `lib/crates/fabro-cli/src/commands/run/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/command.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/logs.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/resume.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/rewind.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/fork.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/wait.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/diff.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/cp.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/preview.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/ssh.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/runs/list.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/runs/rm.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/runs/inspect.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/artifact/list.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/artifact/cp.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/store/dump.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/pr/*.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/system/*.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/server/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/preflight.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/config/mod.rs`
|
||||
|
||||
Important internal-path detail:
|
||||
- hidden commands still need explicit local storage wiring
|
||||
- `fabro server __serve` must keep receiving `--storage-dir` from `lib/crates/fabro-cli/src/commands/server/start.rs`
|
||||
- hidden `fabro __runner` should continue to accept explicit storage-dir selection through its own args struct rather than through `GlobalArgs`
|
||||
|
||||
### 5. Make help output and docs reflect the new command contract
|
||||
In `docs/reference/cli.mdx`:
|
||||
- remove `--storage-dir` and `--server-url` from the “Global options” table
|
||||
- add a short “Command-scoped target selection” section or matrix
|
||||
- update examples to use command-local placement:
|
||||
- `fabro model list --server-url ...`
|
||||
- `fabro server start --storage-dir ...`
|
||||
|
||||
In `docs/reference/user-configuration.mdx`:
|
||||
- keep `[server].base_url` documentation
|
||||
- clarify that it is a default only for commands that support remote server targets
|
||||
- keep the `model` / `exec` asymmetry explicit
|
||||
- update examples away from top-level `fabro --server-url ...`
|
||||
|
||||
In `docs/administration/deploy-server.mdx`:
|
||||
- update “point the CLI at a server” examples to command-local syntax
|
||||
- clarify that `model` can use configured `[server].base_url`, while `exec` still needs explicit `--server-url`
|
||||
|
||||
In `docs/reference/run-directory.mdx`:
|
||||
- change “global `--storage-dir` flag” wording to command-local run-family wording
|
||||
|
||||
Also scan for stale examples in nearby docs and changelog/admin references and update only the ones that would now be actively misleading.
|
||||
|
||||
### 6. Update unit tests, parser tests, and help snapshots
|
||||
#### Unit and parser coverage
|
||||
In `lib/crates/fabro-cli/src/main.rs` tests:
|
||||
- replace the old global target-flag parse tests with command-local parse tests
|
||||
- add the explicit “old global placement no longer parses” cases
|
||||
|
||||
In `lib/crates/fabro-cli/src/user_config.rs` tests:
|
||||
- update helper tests to use the new arg structs
|
||||
- preserve coverage for:
|
||||
- `exec` CLI/env `server_url` routing
|
||||
- `exec` ignoring configured `[server].base_url`
|
||||
- `model` configured `[server].base_url` defaulting
|
||||
- `model` `storage_dir` suppressing configured remote target
|
||||
- TLS inheritance
|
||||
|
||||
#### Integration coverage
|
||||
Update behavior/help coverage in:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model_test.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/config.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/run.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/create.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/attach.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/logs.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/resume.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/rewind.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/wait.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/diff.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/runner.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/ps.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/inspect.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/store.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/store_dump.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/artifact_list.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/artifact_cp.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/sandbox_cp.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/sandbox_preview.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/sandbox_ssh.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/pr.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/pr_list.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/pr_view.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/pr_merge.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/pr_close.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/system.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/system_df.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/system_prune.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/server_start.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/server_stop.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/server_status.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/preflight.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/fabro.rs`
|
||||
|
||||
Behavior scenarios to add or preserve:
|
||||
- `exec` still routes through the server only when its command-local `server_url` is set
|
||||
- `model` still honors configured `[server].base_url` when no explicit `storage_dir` is set
|
||||
- `model` command-local `server_url` still overrides configured base URL
|
||||
- `model` command-local `storage_dir` still forces local behavior
|
||||
- old top-level target-flag placement fails at parse time
|
||||
|
||||
For snapshot churn:
|
||||
- use the repo workflow from `CLAUDE.md`
|
||||
- `cargo insta pending-snapshots`
|
||||
- verify the expected help/output changes
|
||||
- `cargo insta accept`
|
||||
|
||||
## Dependencies And Sequencing
|
||||
Apply the change in this order:
|
||||
|
||||
1. add the new command-scoped target arg structs in `args.rs`, but keep `storage_dir` and `server_url` on `GlobalArgs` temporarily so the crate still compiles during migration
|
||||
2. add the new explicit helpers in `user_config.rs` alongside the old global-based helpers
|
||||
3. repoint `exec` and `model` to the new target arg structs and helpers
|
||||
4. repoint the local-storage and server command modules, plus test harness/env wiring, off `GlobalArgs`
|
||||
5. remove `storage_dir` and `server_url` from `GlobalArgs`, then delete the old global-based helper path once it is unused
|
||||
6. update parser tests for the final clap shape, then update docs and help snapshots
|
||||
|
||||
This ordering keeps the refactor compile-safe: helper and command migration happen before the old global fields are removed, and parser assertions about the old top-level syntax move to the final cleanup step where they become true.
|
||||
|
||||
## Test Plan
|
||||
- targeted parser/unit tests:
|
||||
- `cargo test -p fabro-cli --lib main::tests -- --nocapture`
|
||||
- `cargo test -p fabro-cli --lib user_config::tests -- --nocapture`
|
||||
- targeted CLI integration tests:
|
||||
- `cargo nextest run -p fabro-cli cmd::exec:: --no-fail-fast`
|
||||
- `cargo nextest run -p fabro-cli cmd::model:: cmd::model_list:: cmd::model_test:: cmd::config:: --no-fail-fast`
|
||||
- `cargo nextest run -p fabro-cli cmd::run:: cmd::create:: cmd::attach:: cmd::logs:: cmd::resume:: cmd::rewind:: cmd::wait:: cmd::diff:: cmd::runner:: --no-fail-fast`
|
||||
- `cargo nextest run -p fabro-cli cmd::server_start:: cmd::server_stop:: cmd::server_status:: --no-fail-fast`
|
||||
- broader CLI sweep after targeted coverage is green:
|
||||
- `cargo nextest run -p fabro-cli --no-fail-fast`
|
||||
- final verification:
|
||||
- `cargo fmt --check --all`
|
||||
- `cargo clippy --workspace --all-targets -- -D warnings`
|
||||
|
||||
## Assumptions And Defaults
|
||||
- Pre-production status means removing the old global target-flag placement is acceptable; no compatibility shim is required.
|
||||
- `FABRO_STORAGE_DIR` and `FABRO_SERVER_URL` remain useful and should stay, but only where the corresponding command actually supports the underlying behavior.
|
||||
- The recent `model` and `exec` behavioral contracts are already correct; this pass is about CLI honesty and arg ownership, not product redefinition.
|
||||
- If we later want a broader “remote-capable command matrix” abstraction, it should be built on top of these command-local args rather than by reintroducing misleading global target flags.
|
||||
|
|
@ -1,242 +0,0 @@
|
|||
# CLI Exec Explicit Local Sessions And Mode Removal
|
||||
|
||||
## Summary
|
||||
Simplify the last misleading CLI mode seam by:
|
||||
|
||||
- making `fabro exec` explicitly CLI-owned/local
|
||||
- removing the global `ExecutionMode` / `resolve_mode` abstraction entirely
|
||||
- deleting `mode` from user config and resolved `Settings`
|
||||
- treating Fabro server usage as a command-specific connection choice instead of a whole-program execution mode
|
||||
|
||||
This pass does **not** move the agent loop into the server. `fabro exec` remains a local agent session. The only server-backed `exec` behavior in scope is optional model transport through `FabroServerAdapter` and the existing `/completions` endpoint.
|
||||
|
||||
## Scope Boundaries
|
||||
In scope:
|
||||
- `fabro exec`
|
||||
- removal of `ExecutionMode`, `ResolvedMode`, and `resolve_mode`
|
||||
- removal of `mode` from `user.toml` / `Settings`
|
||||
- command-scoped server-target resolution for `exec`
|
||||
- small adjacent `model` cleanup needed so `[server]` remains meaningful after `mode` is removed
|
||||
- docs/help/config/test cleanup for the new contract
|
||||
|
||||
Out of scope:
|
||||
- server-owned interactive agent sessions
|
||||
- new `/exec`, `/sessions`, or worker-RPC server APIs
|
||||
- moving tool execution, MCP, permissions, or output rendering into the server
|
||||
- changing the run lifecycle commands
|
||||
- changing the `/completions` API contract
|
||||
- adding a new persistent `exec` config field for default server routing
|
||||
|
||||
## Key Decisions
|
||||
- `fabro exec` always owns the agent session locally:
|
||||
- prompt loop
|
||||
- tool execution
|
||||
- permission prompts
|
||||
- MCP connections
|
||||
- event/output rendering
|
||||
- when `fabro exec` uses a Fabro server, only the LLM transport changes:
|
||||
- requests go through `fabro_llm::providers::FabroServerAdapter`
|
||||
- the adapter continues to call the existing `/completions` endpoint
|
||||
- remove `mode` entirely instead of narrowing it.
|
||||
- Once `exec` stops using it, there is no legitimate runtime consumer left.
|
||||
- `fabro exec` remote routing stays an explicit per-invocation choice in this pass:
|
||||
- `--server-url` enables server-routed model transport
|
||||
- configured `[server].base_url` alone does **not** reroute `exec`
|
||||
- Rationale: this keeps `exec` honest as a local command and avoids inventing a new “force direct” override surface immediately.
|
||||
- `[server]` remains a real config surface after `mode` removal, but its meaning changes:
|
||||
- it stores connection information for commands that support a remote Fabro server target
|
||||
- it is not a whole-program execution mode switch
|
||||
- `fabro model` should honor configured `[server].base_url` as its default remote target once `mode` is gone.
|
||||
- `--server-url` still overrides config
|
||||
- explicit `--storage-dir` still forces local auto-start for `model`
|
||||
- this is a small collateral cleanup to keep the config contract coherent
|
||||
- keep the global `--server-url` / `--storage-dir` clap conflict unchanged in this pass.
|
||||
- Rationale: reducing the misleading mode abstraction does not require broad CLI flag-surface churn, and `exec` does not need both simultaneously.
|
||||
- global help/docs must stop claiming:
|
||||
- `--storage-dir` implies standalone mode
|
||||
- `--server-url` implies server mode
|
||||
- no backward-compatibility shim is required for `mode` in `user.toml`, `fabro settings`, or docs.
|
||||
- `mode = "server"` / `mode = "standalone"` should disappear completely from the supported config surface:
|
||||
- remove it from docs, examples, tests, and resolved settings output
|
||||
- existing user config files that still contain it are out of contract after this pass
|
||||
- if deserialization happens to ignore the stale key, that is incidental behavior, not preserved product surface
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Remove global mode from shared config and settings types
|
||||
Delete the dead mode concept from the shared config graph.
|
||||
|
||||
In `lib/crates/fabro-types/src/settings/user.rs`:
|
||||
- delete `ExecutionMode`
|
||||
|
||||
In `lib/crates/fabro-types/src/settings/mod.rs`:
|
||||
- remove the `ExecutionMode` re-export
|
||||
- remove `Settings.mode`
|
||||
|
||||
In `lib/crates/fabro-config/src/user.rs`:
|
||||
- stop re-exporting `ExecutionMode`
|
||||
|
||||
In `lib/crates/fabro-config/src/config.rs`:
|
||||
- remove `ConfigLayer.mode`
|
||||
- remove `mode` combine logic
|
||||
|
||||
In `lib/crates/fabro-config/src/settings.rs`:
|
||||
- stop mapping `value.mode` into `Settings`
|
||||
|
||||
Behavior:
|
||||
- `fabro settings` no longer emits a `mode` field
|
||||
- `user.toml` no longer documents or accepts `mode` as a meaningful setting in this pass
|
||||
|
||||
### 2. Replace `resolve_mode` with command-scoped server-target helpers
|
||||
Stop encoding command behavior as a fake global mode decision.
|
||||
|
||||
In `lib/crates/fabro-cli/src/user_config.rs`:
|
||||
- delete:
|
||||
- `ResolvedMode`
|
||||
- `resolve_mode(...)`
|
||||
- keep `build_server_client(...)`
|
||||
- add one small shared remote-target type, for example:
|
||||
- `ServerTarget { base_url: String, tls: Option<ClientTlsSettings> }`
|
||||
- update `apply_global_overrides(...)` so it only applies:
|
||||
- `storage_dir`
|
||||
- `server.base_url`
|
||||
- and does **not** synthesize any `mode`
|
||||
- if `apply_global_overrides(...)` becomes a trivial two-field merge helper after `mode` removal, inline it at the call sites instead of preserving it mechanically
|
||||
- add concrete helpers that reflect the real command boundaries:
|
||||
- `exec_server_target(globals: &GlobalArgs, settings: &Settings) -> Option<ServerTarget>`
|
||||
- `model_server_target(globals: &GlobalArgs, settings: &Settings) -> Option<ServerTarget>`
|
||||
|
||||
Expected helper semantics:
|
||||
- `exec` helper:
|
||||
- returns a remote server target only when `--server-url` is present
|
||||
- uses configured `[server].tls` if available
|
||||
- ignores configured `[server].base_url` when no CLI flag is present
|
||||
- `model` helper:
|
||||
- returns `--server-url` when present
|
||||
- otherwise returns configured `[server].base_url` when present and no explicit `--storage-dir` was provided
|
||||
- otherwise returns no remote target so the command falls back to local server auto-start
|
||||
|
||||
This helper split is intentional. `exec` and `model` are both server-aware, but they do not have the same defaulting rules.
|
||||
|
||||
### 3. Make `fabro exec` explicitly local with optional server-routed model transport
|
||||
Remove the last server-vs-standalone branching from the command implementation.
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/exec.rs`:
|
||||
- remove the `resolve_mode(...)` call
|
||||
- remove the `match resolved.mode { ... }` branch
|
||||
- always build the session as a local CLI-owned agent session
|
||||
- when the `exec` server-target helper returns `Some(target)`:
|
||||
- build the HTTP client with `build_server_client(...)`
|
||||
- create a `FabroServerAdapter`
|
||||
- register it on a `fabro_llm::Client`
|
||||
- call `run_with_args_and_client(...)`
|
||||
- when the helper returns `None`:
|
||||
- keep the direct provider path via `run_with_args(...)`
|
||||
- replace logging from `mode = "server"/"standalone"` to something transport-shaped such as:
|
||||
- `transport = "server"`
|
||||
- `transport = "direct"`
|
||||
|
||||
Keep unchanged:
|
||||
- permission behavior
|
||||
- MCP server wiring
|
||||
- output format behavior
|
||||
- sub-agent behavior
|
||||
- sandbox/tool execution ownership
|
||||
|
||||
### 4. Keep `[server]` meaningful after removing `mode`
|
||||
Make the shared server config still useful without preserving the abstract mode layer.
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/model.rs`:
|
||||
- stop hand-rolling the `globals.server_url` match
|
||||
- use the new model-target helper from `user_config.rs`
|
||||
- preserve current user-visible `model` behavior apart from the new config defaulting:
|
||||
- remote target when `--server-url` is passed
|
||||
- remote target when `[server].base_url` is configured and no explicit `--storage-dir` is passed
|
||||
- local auto-start otherwise
|
||||
|
||||
This is the only planned collateral behavior change outside `exec`, and it exists to keep `[server]` coherent after `mode` removal.
|
||||
|
||||
### 5. Remove stale docs and help text
|
||||
Rewrite the user-facing contract around explicit server targets instead of execution modes.
|
||||
|
||||
In `lib/crates/fabro-cli/src/args.rs`:
|
||||
- no `--mode` flag exists today, so there is no parser flag removal in this file
|
||||
- update the global flag docstrings:
|
||||
- `--storage-dir` should describe local data/storage selection only
|
||||
- `--server-url` should describe targeting a Fabro API server for commands that support it
|
||||
- remove any wording that says either flag “implies” a mode
|
||||
|
||||
In docs:
|
||||
- `docs/reference/user-configuration.mdx`
|
||||
- remove the `mode` section
|
||||
- rewrite `[server]` as connection info for remote-target-capable commands
|
||||
- clarify the `exec` vs `model` behavior split explicitly
|
||||
- `docs/reference/cli.mdx`
|
||||
- update the global option descriptions for `--storage-dir` and `--server-url`
|
||||
- `docs/administration/deploy-server.mdx`
|
||||
- remove guidance telling users to set `mode = "server"` in `user.toml`
|
||||
- rewrite the “Pointing the CLI at a server” section around:
|
||||
- `--server-url`
|
||||
- configured `[server].base_url`
|
||||
- command-specific behavior
|
||||
- update any nearby docs that still describe “whole CLI server mode” rather than explicit server-target selection
|
||||
|
||||
### 6. Remove or rewrite stale tests
|
||||
Delete tests that only exist to preserve `mode` semantics, and add coverage for the real command boundaries.
|
||||
|
||||
In `lib/crates/fabro-cli/src/user_config.rs` tests:
|
||||
- replace `resolve_mode_*` tests with helper-focused tests covering:
|
||||
- `exec` has no server target by default
|
||||
- `exec` uses CLI `--server-url`
|
||||
- `exec` ignores configured `[server].base_url` without CLI `--server-url`
|
||||
- `model` uses configured `[server].base_url`
|
||||
- `model` CLI `--server-url` overrides configured base URL
|
||||
- `model` explicit `--storage-dir` suppresses configured remote targeting
|
||||
- TLS is still taken from `[server].tls` when a remote target is selected
|
||||
|
||||
In `lib/crates/fabro-cli/tests/it/cmd/exec.rs`:
|
||||
- update help snapshots for the new global flag wording
|
||||
- add one behavior test proving `--server-url` changes the failure mode away from local missing-provider-key validation
|
||||
- for example: with no local provider key configured and an unreachable `--server-url`, the command should fail on remote connection rather than `API key not set for provider ...`
|
||||
- add one regression test proving configured `[server].base_url` alone does not reroute `exec`
|
||||
- expected outcome: with no local provider key, `exec` still fails on the local missing-key path
|
||||
- add one explicit override test proving CLI `--server-url` wins over configured `[server].base_url` for `exec`
|
||||
- expected outcome: with both present, the command targets the CLI URL and the failure shape reflects that URL/path rather than the configured one
|
||||
|
||||
In `lib/crates/fabro-cli/tests/it/cmd/model.rs` and/or `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`:
|
||||
- add coverage showing configured `[server].base_url` is honored without passing `--server-url`
|
||||
|
||||
In `lib/crates/fabro-cli/tests/it/cmd/config.rs`:
|
||||
- remove `ExecutionMode` imports and expectations
|
||||
- update `fabro settings` assertions so `mode` is no longer expected in resolved output
|
||||
- keep coverage that `--server-url` still overrides configured `[server].base_url`
|
||||
|
||||
In help snapshots:
|
||||
- update any snapshots whose global options block still mentions implied server/standalone mode
|
||||
- especially:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/fabro.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/config.rs`
|
||||
- use the repo snapshot workflow from `CLAUDE.md`:
|
||||
- run `cargo insta pending-snapshots`
|
||||
- verify the expected help/output changes
|
||||
- then run `cargo insta accept`
|
||||
|
||||
## Test Plan
|
||||
- Targeted unit tests:
|
||||
- `cargo test -p fabro-cli user_config::tests -- --nocapture`
|
||||
- Targeted CLI integration tests:
|
||||
- `cargo nextest run -p fabro-cli cmd::exec:: cmd::model:: cmd::model_list:: cmd::config:: --no-fail-fast`
|
||||
- Broader regression sweep after the targeted tests are green:
|
||||
- `cargo nextest run -p fabro-cli --no-fail-fast`
|
||||
- Final verification:
|
||||
- `cargo fmt --check --all`
|
||||
- `cargo clippy --workspace --all-targets -- -D warnings`
|
||||
|
||||
## Assumptions And Defaults
|
||||
- `fabro exec` remains a local agent session in this pass. If we later want server-owned interactive sessions, that should be a separate product/architecture plan.
|
||||
- The existing `/completions` endpoint and `FabroServerAdapter` are sufficient for optional server-routed `exec` model traffic.
|
||||
- Pre-production status means removing `mode` outright is acceptable; no shim or migration warning is required.
|
||||
- `[server].base_url` remains valuable as a remote target config surface for commands like `model`, even after `mode` is removed.
|
||||
- `exec` staying CLI-flag-only for server routing is intentional in this pass. If users later need a default server-routed `exec`, that should be introduced as an explicit `exec`-scoped config surface rather than reintroducing a fake whole-program mode.
|
||||
|
|
@ -1,364 +0,0 @@
|
|||
# CLI Model Server Canonicalization And LLM Namespace Removal
|
||||
|
||||
## Summary
|
||||
Take the next low-risk simplification step after the run lifecycle cleanup by:
|
||||
|
||||
- removing the entire unused `fabro llm` CLI namespace
|
||||
- making the `fabro model` family fully server-canonical
|
||||
- leaving `fabro exec` unchanged for now
|
||||
|
||||
This pass is intentionally asymmetric:
|
||||
- `fabro llm` is removed from the CLI surface entirely
|
||||
- `fabro model` remains, but becomes a server-backed command family instead of a mixed standalone/server command
|
||||
- `fabro model test` keeps its current bulk/fan-out role in the CLI, but the server endpoint remains single-model only with an explicit test mode
|
||||
|
||||
Because backward compatibility is not required yet, this pass should prefer simplification over shims. `model test --deep` stays, but it becomes an explicit server capability via `mode=basic|deep` on the single-model test endpoint instead of relying on the old mixed local/server split.
|
||||
|
||||
## Scope Boundaries
|
||||
In scope:
|
||||
- remove `fabro llm`
|
||||
- add `provider` and `query` filters to `GET /api/v1/models`
|
||||
- keep `POST /api/v1/models/{id}/test` as a single-model health/test endpoint
|
||||
- add optional `mode=basic|deep` to `POST /api/v1/models/{id}/test`
|
||||
- make `fabro model list` and `fabro model test` always use the server
|
||||
|
||||
Out of scope:
|
||||
- `fabro exec`
|
||||
- broader removal of `ExecutionMode` / `resolve_mode` outside the `model` command family
|
||||
- changing `POST /models/{id}/test` into a bulk endpoint
|
||||
- changing model storage/catalog ownership away from the server’s built-in catalog
|
||||
- deleting lower-level `fabro_llm::cli` prompt/chat helpers unless they become dead and trivially removable during the refactor
|
||||
|
||||
## Key Decisions
|
||||
- `GET /api/v1/models` gets flat query params, not a generic filter object:
|
||||
- `provider=<name>`
|
||||
- `query=<substring>`
|
||||
- `query` matches `id`, `display_name`, and `aliases`, case-insensitively.
|
||||
- Pagination applies after filtering.
|
||||
- filtered `/api/v1/models` results preserve the built-in catalog order.
|
||||
- invalid `provider` filter values are rejected with `400`, not treated as “no filter” or “no matches”.
|
||||
- "invalid" means the query value fails to parse as a known `fabro_model::Provider` enum variant.
|
||||
- a parsed `provider` value that happens to match zero catalog entries still returns `200` with an empty page.
|
||||
- `POST /api/v1/models/{id}/test` continues to test exactly one model per request and gains one optional query param:
|
||||
- `mode=basic|deep`
|
||||
- default: `basic`
|
||||
- CLI fan-out stays in `fabro model test`, not in the HTTP API.
|
||||
- `model test --deep` is preserved and maps to `mode=deep` on repeated single-model server calls.
|
||||
- `fabro model` should use the generated `fabro_api::Client` for model HTTP calls, not ad hoc raw `reqwest` + URL assembly.
|
||||
- `fabro model` gets a command-specific server-target helper rather than reusing global `ExecutionMode` branching.
|
||||
- if `--server-url` is present, use remote HTTP(S) with configured TLS
|
||||
- otherwise use local server auto-start + Unix socket for the selected storage dir
|
||||
- this does not change `resolve_mode` behavior for other commands
|
||||
- `basic` is the explicit name for the current simple health check mode.
|
||||
- Rationale: an enum-shaped mode is clearer than `deep=true` and leaves room for future test kinds without changing the endpoint shape.
|
||||
- `POST /api/v1/models/{id}/test` accepts either a canonical model ID or an alias.
|
||||
- The server resolves aliases using the built-in catalog.
|
||||
- The response should always return the canonical `model_id`, not the alias string from the path.
|
||||
- `model test --model <id-or-alias>` should POST the provided value directly to `/api/v1/models/{id-or-alias}/test`.
|
||||
- the CLI does not pre-resolve aliases via `GET /models`
|
||||
- CLI `model list --json` preserves its current output contract as a plain array of model objects.
|
||||
- The server remains paginated internally, but the CLI should flatten that to preserve the existing CLI JSON surface.
|
||||
- Deep-mode API results remain binary at the schema level:
|
||||
- success cases return `status: ok`
|
||||
- any deep validation failure returns `status: error`
|
||||
- the failure details go in `error_message`
|
||||
- no new warning/partial result state is introduced in this pass
|
||||
- models without required tool support still return HTTP `200` with `status: error`
|
||||
- absence of reasoning traces alone does not fail deep mode in this pass
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Remove the `fabro llm` CLI namespace
|
||||
Update the CLI surface so `fabro llm` no longer exists.
|
||||
|
||||
In `lib/crates/fabro-cli/src/args.rs`:
|
||||
- remove the `Commands::Llm` variant
|
||||
- remove `LlmNamespace` and `LlmCommand`
|
||||
- remove `ChatArgs` / `PromptArgs` imports from `fabro_llm::cli`
|
||||
- remove command-name mapping for `llm prompt` and `llm chat`
|
||||
|
||||
In `lib/crates/fabro-cli/src/main.rs`:
|
||||
- remove the `Commands::Llm(...)` dispatch arm
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/mod.rs`:
|
||||
- remove `pub(crate) mod llm;`
|
||||
|
||||
Delete:
|
||||
- `lib/crates/fabro-cli/src/commands/llm/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/llm/chat.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/llm/prompt.rs`
|
||||
|
||||
Test/support cleanup:
|
||||
- remove `mod llm;` and `mod llm_prompt;` from `lib/crates/fabro-cli/tests/it/cmd/mod.rs`
|
||||
- delete:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/llm.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/llm_prompt.rs`
|
||||
- remove the now-unused `TestContext::llm()` helper from `lib/crates/fabro-test/src/lib.rs`
|
||||
- update top-level help snapshots in `lib/crates/fabro-cli/tests/it/cmd/fabro.rs` and any parser/help coverage that still mentions `llm`
|
||||
|
||||
This pass should only remove the CLI namespace. Do not widen the blast radius by opportunistically deleting unrelated lower-level LLM helpers unless the compiler proves they are now dead and the deletion is mechanical.
|
||||
|
||||
Because `fabro llm` is the only CLI surface for these paths today, expect some prompt/chat internals to become dead as a direct consequence of this removal. If the compiler confirms there are no remaining callers, delete the dead items in this pass rather than preserving unreachable code:
|
||||
- `PromptArgs`
|
||||
- `ChatArgs`
|
||||
- `run_prompt`
|
||||
- `run_chat`
|
||||
- `run_prompt_via_server`
|
||||
- `run_chat_via_server`
|
||||
|
||||
### 2. Make `/api/v1/models` a real server-owned list endpoint
|
||||
Treat `/api/v1/models` as a canonical non-demo API surface.
|
||||
|
||||
In `docs/api-reference/fabro-api.yaml`:
|
||||
- add optional query parameters to `GET /api/v1/models`:
|
||||
- `provider`
|
||||
- `query`
|
||||
- document `query` matching semantics explicitly:
|
||||
- substring match
|
||||
- case-insensitive
|
||||
- fields: `id`, `display_name`, `aliases`
|
||||
- add optional query parameter to `POST /api/v1/models/{id}/test`:
|
||||
- `mode=basic|deep`
|
||||
- default behavior when omitted: `basic`
|
||||
- document `basic` as the current simple prompt/availability check
|
||||
- document `deep` as the multi-turn tool-use / reasoning round-trip check
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
- keep `/models/{id}/test` wired to the real server handler
|
||||
- stop treating `/models` as demo semantics only
|
||||
- replace the `demo::list_models` route usage with a non-demo handler
|
||||
- implement a small query extractor for model filters and pagination in the real server path
|
||||
- implement a small query extractor for model test mode in the `test_model` handler
|
||||
- fix the `test_model` response to use `info.id` (the canonical model ID from the catalog lookup) instead of the raw `id` path parameter in all response branches, so alias lookups return the canonical ID
|
||||
|
||||
In `lib/crates/fabro-server/src/demo/mod.rs`:
|
||||
- `demo::list_models` is currently wired in both `demo_routes()` and `real_routes()`; replace both usages with the new non-demo handler
|
||||
- remove the now-unused `list_models` helper from the demo module
|
||||
|
||||
Behavior:
|
||||
- server builds the list from `fabro_model::Catalog::builtin()`
|
||||
- applies `provider` filter if present
|
||||
- applies `query` filter if present
|
||||
- paginates the filtered list
|
||||
- returns the same `PaginatedModelList` schema shape as today
|
||||
- preserves built-in catalog order after filtering
|
||||
- rejects unknown `provider` values with `400`
|
||||
- this means parse failure against `fabro_model::Provider`
|
||||
- a valid parsed provider with zero matching models still returns `200` and an empty page
|
||||
- `POST /models/{id}/test`:
|
||||
- defaults to `basic`
|
||||
- accepts either a canonical model ID or an alias
|
||||
- runs the current simple one-prompt check in `basic` mode
|
||||
- runs the deeper multi-turn tool-use / reasoning check in `deep` mode
|
||||
- still returns one result object for one model
|
||||
|
||||
### 3. Make `fabro model` server-canonical
|
||||
Remove standalone/server branching from the CLI `model` command family.
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/model.rs`:
|
||||
- stop using `resolve_mode`
|
||||
- stop passing `Option<ServerConnection>` into `run_models(...)`
|
||||
- construct a typed `fabro_api::Client` up front and pass it through unconditionally
|
||||
|
||||
In `lib/crates/fabro-cli/src/server_client.rs`:
|
||||
- keep the existing local auto-start + Unix-socket path for storage-backed connections
|
||||
- add one small model-command helper that returns a typed `fabro_api::Client` from either:
|
||||
- explicit remote base URL + configured TLS (`--server-url`), or
|
||||
- local auto-start + Unix socket for the selected storage dir
|
||||
- if needed, split the current Unix-only local connect helper into:
|
||||
- a local auto-start helper, and
|
||||
- a thin typed-client constructor for remote HTTP(S) base URLs
|
||||
- do not route `model` through `ServerStoreClient`; `model` should use the generated API client directly
|
||||
|
||||
This change is intentionally command-specific:
|
||||
- `--server-url` keeps working for remote server usage
|
||||
- `--storage-dir` or default local storage uses local server auto-start
|
||||
- `model` no longer branches on `ExecutionMode`
|
||||
- global `resolve_mode` behavior for other commands stays unchanged in this pass
|
||||
|
||||
### 4. Simplify model selection and test orchestration
|
||||
Keep the CLI in charge of bulk orchestration, but move catalog authority to the server.
|
||||
|
||||
In `lib/crates/fabro-llm/src/cli.rs`:
|
||||
- replace the raw `reqwest` + `base_url` model HTTP helpers with generated `fabro_api::Client` calls
|
||||
- update `fetch_models_from_server(...)` to forward `provider` and `query` to the server instead of filtering locally after the response
|
||||
- update the fetch helper to follow pagination until `meta.has_more` is false instead of assuming one page is enough
|
||||
- remove local provider filtering from the fetch helper
|
||||
- remove the local query filtering in `run_models(...)` (the `if let Some(q) = &query { ... models.retain(...) }` block), since the server now handles query filtering
|
||||
- simplify `run_models(...)` so it no longer accepts an optional server connection; `model` should always call the server-backed path
|
||||
- keep `model test` fan-out behavior in the CLI:
|
||||
- `model test --model <id-or-alias>` calls `POST /models/{id-or-alias}/test` once
|
||||
- `model test --provider <provider>` first resolves the filtered list via `GET /models?provider=...`, then POSTs `/test` once per returned model
|
||||
- bare `model test` first resolves the full list via `GET /models`, then POSTs `/test` once per model
|
||||
- `model test --deep` maps each request to `POST /models/{id}/test?mode=deep`
|
||||
- default `model test` behavior maps each request to `basic` mode
|
||||
- any shared fetch helper used from test fan-out paths passes `query=None`, because query filtering remains list-only in this pass
|
||||
|
||||
Preserve current broad behavior where reasonable:
|
||||
- `--model` remains the direct single-model selector and should pass the user-supplied ID or alias through unchanged
|
||||
- unknown model inputs should continue to surface an “unknown model” style error when the server returns 404
|
||||
- CLI fan-out result formatting and failure aggregation should remain substantially the same
|
||||
- `model list --json` should continue to print a plain JSON array, not the server’s paginated envelope
|
||||
- CLI output order should preserve the server/catalog order
|
||||
- CLI selection behavior remains:
|
||||
- `--model` takes precedence over `--provider`
|
||||
- query filtering applies only to `list`, not `test`, unless explicitly added later
|
||||
|
||||
### 5. Preserve `model test --deep` via server-owned test modes
|
||||
`--deep` remains useful, but it should stop depending on the old local test execution branch. The server should own both single-model test modes, and the CLI should only orchestrate fan-out.
|
||||
|
||||
Server-side implementation:
|
||||
- extract the single-model test logic out of CLI-only code and into a reusable non-CLI helper in `fabro-llm` so the server can execute:
|
||||
- `basic` mode
|
||||
- `deep` mode
|
||||
- keep that logic in `fabro-llm`, not inline in the axum handler; this is LLM-domain behavior, not route-local glue
|
||||
- shape the extracted helper around an internal outcome type that already matches the binary API contract:
|
||||
- success => `status: ok`
|
||||
- failure => `status: error` plus message detail
|
||||
- preserve the current timeout budgets:
|
||||
- `basic` uses the current short timeout budget (`30s`)
|
||||
- `deep` uses the current long timeout budget (`90s`)
|
||||
- keep deep mode's current in-process tool-closure pattern from `build_deep_test_params`; this pass does not add RPC or external tool-runner infrastructure
|
||||
- `mode=deep` for a model without tool support returns HTTP `200` with `status: error` and a clear `error_message`
|
||||
- if a reasoning-capable model completes deep mode without reasoning traces, do not fail for that fact alone in this pass
|
||||
- the initial source material is the existing logic in `lib/crates/fabro-llm/src/cli.rs`:
|
||||
- `build_deep_test_params`
|
||||
- `validate_deep_result`
|
||||
- current one-model test logic
|
||||
- the end state should be:
|
||||
- server calls a reusable `fabro-llm` helper for one-model test execution
|
||||
- CLI no longer owns authoritative one-model test behavior
|
||||
- do not leave deep behavior only in the CLI-local path once `model` becomes server-canonical
|
||||
|
||||
CLI-side implementation:
|
||||
- keep `deep` on `ModelsCommand::Test`
|
||||
- update the server-call helper(s) to pass `mode=deep` when requested
|
||||
- remove only the dead local standalone branches once the server owns both modes
|
||||
- remove the `"Warning: --deep is not supported in server mode"` diagnostic from `test_models_via_server`, since deep mode is now a server-owned capability
|
||||
- remove the `deep_unsupported` field from `ModelTestOutput` JSON serialization, since deep mode is now fully supported via the server
|
||||
|
||||
In CLI help/snapshots:
|
||||
- keep `--deep` on `model test --help`
|
||||
- update wording if needed so it reflects a server-backed deep test rather than a local-only path
|
||||
|
||||
### 6. Dependencies And Sequencing
|
||||
Apply this in order so the refactor has stable interfaces to land on:
|
||||
|
||||
- land the OpenAPI changes for `/models` filters and `/models/{id}/test?mode=basic|deep` first
|
||||
- update the server list/test handlers, including provider parsing, alias handling, and canonical response IDs
|
||||
- extract the reusable single-model `basic` / `deep` test helper in `fabro-llm`
|
||||
- regenerate the Rust typed API client via `cargo build -p fabro-api`
|
||||
- repoint `fabro model` and its fetch/test helpers to the generated `fabro_api::Client`
|
||||
- remove the `fabro llm` CLI namespace and any compiler-confirmed dead prompt/chat code
|
||||
- regenerate the TypeScript client once the server contract is settled
|
||||
|
||||
Section 2's endpoint and mode changes must land before replacing the deep-mode server flow described in Section 5.
|
||||
|
||||
### 7. Regenerate typed API clients through the normal workflow
|
||||
Because `/api/v1/models` changes, follow the repo’s API workflow instead of hand-editing generated clients.
|
||||
|
||||
Source of truth:
|
||||
- `docs/api-reference/fabro-api.yaml`
|
||||
|
||||
Generated/regenerated artifacts:
|
||||
- Rust API client/types via `cargo build -p fabro-api`
|
||||
- TypeScript client via `cd lib/packages/fabro-api-client && bun run generate`
|
||||
|
||||
Expected generated updates include:
|
||||
- `lib/packages/fabro-api-client/src/api/models-api.ts`
|
||||
- related generated model/type files under `lib/packages/fabro-api-client/src/models/`
|
||||
|
||||
## Important Interface / Behavior Changes
|
||||
- `fabro llm` is removed from the CLI surface completely.
|
||||
- `fabro model` always talks to the server.
|
||||
- `GET /api/v1/models` accepts:
|
||||
- `provider`
|
||||
- `query`
|
||||
- invalid `provider` values return `400`
|
||||
- invalid `provider` means the value does not parse as a known `fabro_model::Provider`
|
||||
- valid provider filters that simply match zero models still return `200` with an empty page
|
||||
- filtered results preserve built-in catalog order
|
||||
- `POST /api/v1/models/{id}/test` accepts:
|
||||
- optional `mode=basic|deep`
|
||||
- default mode `basic`
|
||||
- `/models/{id}/test` accepts aliases but returns the canonical `model_id`
|
||||
- `model test --model <alias>` posts that alias directly and relies on server-side alias resolution
|
||||
- `model test --deep` remains supported and maps to `mode=deep`.
|
||||
- `model list --json` continues to output a plain JSON array.
|
||||
|
||||
## Test Plan
|
||||
CLI command surface:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/fabro.rs`
|
||||
- top-level help no longer lists `llm`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model.rs`
|
||||
- bare `model` and `model list` still work
|
||||
- provider/query list behavior still matches expected snapshots
|
||||
- JSON output still parses as a plain array
|
||||
- `model list` still works with an auto-started local server and with `--server-url`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
|
||||
- help text still matches the new server-backed behavior
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/model_test.rs`
|
||||
- help text still mentions `--deep`
|
||||
- unknown model still errors cleanly
|
||||
- `--model <alias>` calls the single-model test endpoint directly and succeeds via server-side alias resolution
|
||||
- deep mode still routes through the server-backed model test flow
|
||||
- JSON output no longer includes `deep_unsupported`
|
||||
- delete now-obsolete `llm` CLI tests:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/llm.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/llm_prompt.rs`
|
||||
|
||||
Server/API behavior:
|
||||
- `lib/crates/fabro-server/src/server.rs`
|
||||
- add tests for `GET /api/v1/models` with:
|
||||
- no filters
|
||||
- `provider`
|
||||
- `query`
|
||||
- combined `provider + query`
|
||||
- case-insensitive query matching
|
||||
- pagination applied after filtering
|
||||
- invalid provider returns `400`
|
||||
- valid parsed provider + no matching query returns `200` with an empty page
|
||||
- filtered results preserve catalog order
|
||||
- extend `POST /api/v1/models/{id}/test` coverage for:
|
||||
- omitted mode defaults to `basic`
|
||||
- explicit `mode=basic`
|
||||
- explicit `mode=deep`
|
||||
- invalid mode rejected cleanly
|
||||
- alias path values resolve successfully and return the canonical `model_id`
|
||||
- unknown model still returns 404
|
||||
- `mode=deep` on a model without tool support returns `200` with `status: error`
|
||||
|
||||
LLM CLI internals:
|
||||
- `lib/crates/fabro-llm/src/cli.rs`
|
||||
- update `fetch_models_from_server` unit tests to assert outgoing `provider` / `query` params
|
||||
- add coverage that multi-page server responses are fully traversed
|
||||
- update/remove tests that assumed client-side provider filtering
|
||||
- add coverage that test fan-out paths call the shared fetch helper with `query=None`
|
||||
- add or update server-call tests so deep mode is forwarded as `mode=deep`
|
||||
- add helper-level coverage for the binary deep-mode contract:
|
||||
- tool-less models return `error`
|
||||
- missing reasoning traces alone do not fail
|
||||
- remove only the dead standalone-only test coverage after server ownership is in place
|
||||
|
||||
Full verification:
|
||||
- `cargo build -p fabro-api`
|
||||
- `cargo nextest run -p fabro-cli --no-fail-fast`
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo fmt --check --all`
|
||||
- `cargo clippy --workspace -- -D warnings`
|
||||
- `cd lib/packages/fabro-api-client && bun run generate`
|
||||
|
||||
## Assumptions And Defaults
|
||||
- `fabro llm` is dead product surface and should be removed cleanly, not hidden.
|
||||
- `exec` remains a separate product surface and is intentionally untouched in this pass.
|
||||
- `GET /api/v1/models` remains a built-in catalog view; this pass does not introduce live provider discovery.
|
||||
- CLI model fetches must traverse paginated `/models` responses until exhaustion.
|
||||
- `model test` remains a CLI orchestrator over repeated single-model HTTP calls.
|
||||
- local-storage-backed `fabro model` may auto-start the local server on first use.
|
||||
- for local auto-started servers, model testing assumes the daemon inherits the CLI environment, including provider credentials.
|
||||
- for explicit remote `--server-url` usage, provider credential availability is the remote server operator's responsibility.
|
||||
- `POST /api/v1/models/{id}/test` uses a single optional query param for mode selection:
|
||||
- `basic`
|
||||
- `deep`
|
||||
- Deep-mode validation failures are represented as `status: error` plus `error_message`, not a new intermediate status.
|
||||
- If both `--model` and `--provider` are supplied to `model test`, keep the current effective behavior of prioritizing the explicit model selection rather than inventing a new validation rule in this pass.
|
||||
- No backward-compatibility shims are needed for removed CLI commands or flags.
|
||||
|
|
@ -1,100 +0,0 @@
|
|||
# CLI Run Lifecycle Cleanup Compaction
|
||||
|
||||
## Summary
|
||||
Simplify the proven server-backed CLI run lifecycle without changing execution topology in this pass.
|
||||
|
||||
This pass keeps `/api/v1/runs/*` as the canonical run API, ignores `/boards/runs`, and treats the current server-owned in-process execution model as the stable behavior for now. The goal is to remove obsolete local-launcher compatibility, collapse duplicated server-backed lookup code, and leave the CLI in a cleaner client-to-server shape. The hidden internal command is renamed from `__detached` to `__runner` now so the code reflects its future role, but this pass does not yet make the server spawn it.
|
||||
|
||||
## Key Changes
|
||||
### 1. Lock the cleanup boundary
|
||||
- Treat the run lifecycle surface as server-backed and cleanup-eligible:
|
||||
- `run`, `create`, `start`, `resume`, `attach`, `wait`, `logs`, `diff`, `preview`, `ssh`, `runs/*`, `pr/*`, `artifact/*`, `system df/prune`, `store dump`
|
||||
- Leave these out of scope for this pass:
|
||||
- global `ExecutionMode` / `resolve_mode`
|
||||
- `model`, `exec`, `llm chat`, `llm prompt`
|
||||
- `/boards/runs`
|
||||
- changing `POST /runs/{id}/start` to spawn a worker
|
||||
- introducing worker-RPC execution
|
||||
|
||||
### 2. Rename and shrink the hidden worker entrypoint
|
||||
- Rename the hidden internal subcommand from `__detached` to `__runner`.
|
||||
- Rename the enum variant, parser tests, help snapshots, and the command module/test names so internal terminology matches the future worker model.
|
||||
- Narrow the hidden command contract to the minimum needed for its current thin behavior:
|
||||
- keep `run_id`
|
||||
- keep `resume`
|
||||
- keep storage selection via globals/settings
|
||||
- remove `run_dir`
|
||||
- remove `launcher_path`
|
||||
- Keep its implementation simple for now:
|
||||
- connect to the server
|
||||
- call `POST /runs/{id}/start`
|
||||
- poll terminal status
|
||||
- Do not keep `__detached` as an alias. This pass is the rename.
|
||||
|
||||
### 3. Remove launcher-era compatibility
|
||||
- Delete the launcher-record subsystem in `commands/run/launcher.rs`:
|
||||
- record file creation/removal
|
||||
- stale PID cleanup
|
||||
- process-command matching
|
||||
- run-id fallback via launcher metadata
|
||||
- Simplify `attach` to a server-only model when no explicit child handle is supplied:
|
||||
- infer run ID from the explicit argument or `run_dir/id.txt`
|
||||
- infer storage dir from the `runs/<id>` path shape only
|
||||
- cancel via `POST /runs/{id}/cancel`
|
||||
- remove launcher-PID probing, launcher-based kill logic, and “server-owned vs launcher-owned” branching
|
||||
- Remove the now-dead `engine_child` compatibility path from `attach` if it is no longer used by production callers.
|
||||
- Update `run`, `resume`, and related comments/tests so they describe server-owned execution accurately instead of launcher/detach-era behavior.
|
||||
|
||||
### 4. Collapse duplicated server-backed run resolution
|
||||
- Add one small internal helper layer for server-backed run lookup and state access.
|
||||
- Move the repeated pattern out of individual commands:
|
||||
- connect to server for storage dir
|
||||
- list durable run summaries
|
||||
- resolve a user-supplied run selector against `runs_base(...)`
|
||||
- optionally fetch current state/events
|
||||
- Repoint already-server-backed commands to this helper so they stop hand-rolling the same summary lookup logic.
|
||||
- Keep behavior unchanged; this is compaction, not a semantic migration.
|
||||
|
||||
### 5. Preserve the single-store ownership invariant explicitly
|
||||
- Do not add any direct SlateDB access to `__runner`.
|
||||
- Treat the server as the only SlateDB reader/writer.
|
||||
- Keep the future `__runner` model aligned with server-owned storage:
|
||||
- the worker process may execute workflow logic
|
||||
- all durable run mutation must still go through server HTTP endpoints over the Unix socket
|
||||
- In this cleanup pass, reflect that invariant in naming, comments, and any internal helper boundaries so later worker-RPC work does not have to undo new local-store assumptions.
|
||||
|
||||
### 6. Remove stale transitional tests and comments
|
||||
- Rewrite or delete tests that only exist to preserve launcher-record or `__detached` behavior.
|
||||
- Keep tests that prove the intended architecture:
|
||||
- server-backed detached run creation/start/attach
|
||||
- no launcher record is created in normal run/start/resume flow
|
||||
- hidden `__runner` still parses and works with its reduced contract
|
||||
- Update misleading comments and docstrings that still describe local detached engine ownership.
|
||||
|
||||
## Test Plan
|
||||
- Targeted CLI tests:
|
||||
- `cmd::start::*`
|
||||
- `cmd::attach::*`
|
||||
- `cmd::detached::*` renamed to `cmd::runner::*`
|
||||
- `cmd::resume::*`
|
||||
- `cmd::logs::*`
|
||||
- `cmd::wait::*`
|
||||
- Add or update focused tests for:
|
||||
- attach infers run ID from `id.txt` without launcher metadata
|
||||
- ctrl-c / detach uses server cancel for active runs
|
||||
- `__runner` help/parser no longer mentions launcher-era flags
|
||||
- no launcher files are created anywhere in the normal run/start/resume flow
|
||||
- Run full verification:
|
||||
- `cargo nextest run -p fabro-cli --no-fail-fast`
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo fmt --check --all`
|
||||
- `cargo clippy --workspace -- -D warnings`
|
||||
|
||||
## Assumptions And Defaults
|
||||
- `/boards/runs` is demo-only and ignored in this pass.
|
||||
- `POST /runs/{id}/start` continues to queue and execute runs inside the server process for now.
|
||||
- The future worker model is ordinary server-owned child processes, not detached launcher-managed processes.
|
||||
- The server remains the single SlateDB reader/writer; future `__runner` processes must use server HTTP endpoints over the Unix socket for durable mutation.
|
||||
- `__runner` is retained now because a later plan will make it the server-launched per-run worker, but that worker flip is explicitly not part of this cleanup pass.
|
||||
- The local run directory still exists and remains a valid source for `id.txt` and runtime/artifact paths where the current code already depends on it.
|
||||
- Broader standalone-to-server cleanup outside the proven run lifecycle area is deferred to a later plan.
|
||||
|
|
@ -1,570 +0,0 @@
|
|||
# Run-Adjacent Server-Only Cleanup
|
||||
|
||||
## Summary
|
||||
|
||||
Make the remaining user-facing run-adjacent commands server-only:
|
||||
|
||||
- `fabro resume`
|
||||
- `fabro diff`
|
||||
- `fabro fork`
|
||||
- `fabro rewind`
|
||||
- `fabro artifact list`
|
||||
- `fabro artifact cp`
|
||||
- `fabro pr create|list|view|merge|close`
|
||||
- `fabro sandbox preview`
|
||||
- `fabro sandbox ssh`
|
||||
- `fabro sandbox cp`
|
||||
|
||||
After this pass, those commands should no longer resolve runs through local `runs/` directories or flatten `--storage-dir`. They should all target a server the same way the core lifecycle commands already do:
|
||||
|
||||
1. explicit `--server` / `FABRO_SERVER`
|
||||
2. configured `[server].target`
|
||||
3. default local server instance, auto-started via the default local storage dir
|
||||
|
||||
There is intentionally no separate “force local” override for these commands in this pass. If `[server].target` is configured, that target wins unless the user passes an explicit `--server` value pointing at a local Unix socket. This is a simplicity tradeoff, not an accidental regression.
|
||||
|
||||
This is cleanup/compaction, not a new subsystem. The goal is to finish the architectural move already made for `run`, `create`, `start`, `attach`, `logs`, `wait`, `ps`, `inspect`, and `rm`.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
In scope:
|
||||
- the commands listed above
|
||||
- shared run-resolution helpers in `fabro-cli`
|
||||
- missing thin server APIs needed to make sandbox-oriented commands truly server-only
|
||||
- CLI help/docs/snapshots for the new contract
|
||||
|
||||
Out of scope:
|
||||
- `fabro store dump`
|
||||
- `fabro system df`
|
||||
- `fabro system prune`
|
||||
- hidden/internal commands like `__runner`
|
||||
- changing run execution topology
|
||||
- changing checkpoint format or git metadata format
|
||||
- changing GitHub auth/secrets flows
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The run lifecycle is only partially simplified today.
|
||||
|
||||
Core lifecycle commands are already server-only, but the rest of the run-adjacent surface still falls back to local path-based lookup through `ServerRunLookup` in [server_runs.rs](lib/crates/fabro-cli/src/server_runs.rs). That creates three kinds of drift:
|
||||
|
||||
- some commands still expose `--storage-dir` even though the real abstraction is now a server target
|
||||
- some commands read local run files even when equivalent data already exists in server state/store
|
||||
- some commands still reconnect directly from the CLI to sandboxes, which breaks the “server-owned runs” abstraction for remote targets
|
||||
|
||||
That is unnecessary complexity in a greenfield app with no production compatibility constraints.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- All in-scope commands become server-only.
|
||||
- They flatten `ServerTargetArgs`, not `StorageDirArgs`.
|
||||
- `--storage-dir` is removed from their public CLI surface.
|
||||
- `FABRO_STORAGE_DIR` is not part of the public contract for these commands.
|
||||
- If `[server].target` is configured, these commands use it unless an explicit `--server` is passed.
|
||||
- There is no separate “force local default instance” flag.
|
||||
|
||||
- `ServerRunLookup` becomes local/admin-only.
|
||||
- Keep it only for genuinely local maintenance commands like `store dump`, `system df`, and `system prune`.
|
||||
- User-facing run commands should resolve selectors through `ServerSummaryLookup` plus server state/events.
|
||||
|
||||
- `fabro diff` is simplified to stored server-backed output only.
|
||||
- Drop the live sandbox reconnect fallback.
|
||||
- Drop `--stat` and `--shortstat`.
|
||||
- Output comes only from stored diff data already present in run state (`final_patch` and per-node `diff`).
|
||||
- If no stored diff exists, return a clear error.
|
||||
|
||||
- `fabro fork` and `fabro rewind` remain local git operations, but not local run-store operations.
|
||||
- Run selection and run event/state loading come from the target server.
|
||||
- Repo mutation still happens against the caller’s local checkout, which is the correct boundary.
|
||||
- Before mutating the repo, the CLI should compare the current checkout against a durable stored repo identity and fail fast on obvious mismatch.
|
||||
|
||||
- `fabro pr *` stays CLI-owned for GitHub network calls, but server-owned for run lookup and pull-request record loading.
|
||||
- This keeps the current GitHub App model intact while removing local run-dir dependence.
|
||||
- `pr create` should use the same repo-mismatch guard as `fork` and `rewind` before operating on the caller’s checkout.
|
||||
|
||||
- `fabro artifact *` should reuse the existing stage artifact API instead of walking local `artifacts/` directories.
|
||||
- The CLI can derive relevant stage IDs from `RunProjection.nodes` and call the existing stage artifact list/download endpoints.
|
||||
|
||||
- `fabro sandbox preview`, `fabro sandbox ssh`, and `fabro sandbox cp` should stop reconnecting to sandboxes directly from the CLI.
|
||||
- The server owns the sandbox record and should own the reconnect.
|
||||
- The CLI becomes a thin consumer of server responses.
|
||||
|
||||
- The server API should stay thin and capability-shaped.
|
||||
- Reuse existing APIs where they already exist.
|
||||
- Add only the missing endpoints required for truly server-only sandbox operations.
|
||||
|
||||
- Backward compatibility is not a goal.
|
||||
- Remove obsolete flags and behavior instead of shimming them.
|
||||
- Prefer deleting speculative unused surface over preserving it.
|
||||
|
||||
## Sequencing
|
||||
|
||||
This plan should land in two phases.
|
||||
|
||||
Phase 1: pure CLI/server-state cleanup using APIs that already exist
|
||||
|
||||
- `resume`
|
||||
- `fork`
|
||||
- `rewind`
|
||||
- `pr *`
|
||||
- `artifact list`
|
||||
- `artifact cp` (the stage artifact list/download routes already exist and are implemented)
|
||||
- `diff`
|
||||
- Phase 1 OpenAPI cleanup for `diff`:
|
||||
- delete `/api/v1/runs/{id}/files`
|
||||
- shared `ServerSummaryLookup` / `ServerRunLookup` narrowing
|
||||
- help/docs/snapshot churn for those commands
|
||||
|
||||
Phase 2: thin server API completion for sandbox-owned commands
|
||||
|
||||
- `sandbox preview`
|
||||
- `sandbox ssh`
|
||||
- `sandbox cp`
|
||||
|
||||
This keeps the simpler repoints from being blocked on the few missing server capability routes.
|
||||
|
||||
The final `ServerRunLookup` narrowing should happen only after the last in-scope command that still imports it has been migrated. Do not try to enforce an admin-only boundary halfway through the sequence while migrated and unmigrated command families still coexist.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 0. Add a durable repo identity field for local-repo operations
|
||||
|
||||
The current `RunRecord.host_repo_path` is a filesystem path, not a durable cross-machine identity. It should not be used for a server-targeted repo-mismatch guard.
|
||||
|
||||
Add a new persisted field to `RunRecord`, for example:
|
||||
|
||||
- `repo_origin_url: Option<String>`
|
||||
|
||||
Recommended semantics:
|
||||
|
||||
- source it from `RunManifest.git.origin_url`, which is already sanitized before it reaches the server
|
||||
- persist it in the run record when a manifest-sourced run is created
|
||||
- treat it as the canonical repo-identity signal for CLI commands that mutate or inspect the caller’s local checkout on behalf of a server-selected run
|
||||
|
||||
Normalization rules should be explicit and shared:
|
||||
|
||||
- strip embedded credentials
|
||||
- normalize GitHub-style SSH URLs to HTTPS form
|
||||
- trim a trailing `.git`
|
||||
- trim trailing `/`
|
||||
|
||||
Guard behavior:
|
||||
|
||||
- `fork`, `rewind`, and `pr create` detect the current checkout’s origin URL locally
|
||||
- normalize it with the same helper used for the stored field
|
||||
- if both sides are present and clearly differ, fail with a targeted repo-mismatch error
|
||||
- if the stored field is absent, skip the guard rather than inventing a heuristic fallback
|
||||
|
||||
Files expected to change:
|
||||
|
||||
- [run.rs](lib/crates/fabro-types/src/run.rs)
|
||||
- the manifest-backed run creation path that already receives `manifest.git.origin_url`
|
||||
- any serialization/projection paths that persist and reload `RunRecord`
|
||||
|
||||
### 1. Convert remaining run-adjacent args to `ServerTargetArgs`
|
||||
|
||||
In [args.rs](lib/crates/fabro-cli/src/args.rs):
|
||||
|
||||
- replace `StorageDirArgs` with `ServerTargetArgs` for:
|
||||
- `ArtifactListArgs`
|
||||
- `ArtifactCpArgs`
|
||||
- `CpArgs`
|
||||
- `PreviewArgs`
|
||||
- `SshArgs`
|
||||
- `DiffArgs`
|
||||
- `ResumeArgs`
|
||||
- `RewindArgs`
|
||||
- `ForkArgs`
|
||||
- `PrCreateArgs`
|
||||
- `PrListArgs`
|
||||
- `PrViewArgs`
|
||||
- `PrMergeArgs`
|
||||
- `PrCloseArgs`
|
||||
|
||||
Also simplify `DiffArgs`:
|
||||
|
||||
- remove `stat`
|
||||
- remove `shortstat`
|
||||
- update help text to describe stored diff output only
|
||||
|
||||
Resulting CLI contract:
|
||||
|
||||
- `fabro diff <run> --server http://127.0.0.1:3000/api/v1`
|
||||
- `fabro artifact list <run> --server /var/run/fabro.sock`
|
||||
- `fabro sandbox ssh <run> --server https://fabro.example.com/api/v1`
|
||||
- no `--storage-dir` on these commands
|
||||
- no public `FABRO_STORAGE_DIR` support on these commands
|
||||
|
||||
### 2. Narrow shared lookup helpers
|
||||
|
||||
In [server_runs.rs](lib/crates/fabro-cli/src/server_runs.rs):
|
||||
|
||||
- keep `ServerSummaryLookup` as the default user-facing selector path
|
||||
- add any missing helper methods needed for:
|
||||
- selector resolution
|
||||
- filtered summary listing
|
||||
- summary-to-state/event follow-up work
|
||||
- keep `ServerRunLookup` only for commands that remain explicitly local/admin-only
|
||||
|
||||
Do not try to finish that narrowing until the last in-scope migrated command is off `ServerRunLookup`.
|
||||
|
||||
In [server_client.rs](lib/crates/fabro-cli/src/server_client.rs):
|
||||
|
||||
- add thin wrappers for the server APIs the CLI now needs, split by phase:
|
||||
- Phase 1:
|
||||
- list stage artifacts
|
||||
- download stage artifact
|
||||
- Phase 2:
|
||||
- generate preview URL
|
||||
- create SSH access
|
||||
- sandbox file listing/download/upload
|
||||
|
||||
Do not introduce a parallel target-resolution stack. Reuse:
|
||||
|
||||
- `connect_server_only(...)`
|
||||
- `server_only_command_connection(...)`
|
||||
|
||||
If tests still need `FABRO_STORAGE_DIR` internally to steer the default local server instance, treat that as harness-only plumbing rather than user-facing behavior.
|
||||
|
||||
### 3. Repoint `resume` to the server-only lifecycle helpers
|
||||
|
||||
In [resume.rs](lib/crates/fabro-cli/src/commands/run/resume.rs):
|
||||
|
||||
- stop using `ServerRunLookup`
|
||||
- resolve the run via `ServerSummaryLookup`
|
||||
- call the existing direct-client start helper
|
||||
- for foreground resume:
|
||||
- attach through the existing direct-client attach helper
|
||||
- print the existing server-backed summary output with no local `run_dir`
|
||||
|
||||
This is intentionally a small mechanical repoint. It should make `resume` match the already-simplified `start`/`attach` contract without introducing new behavior.
|
||||
|
||||
### 4. Repoint `fork` and `rewind` to server-backed run state
|
||||
|
||||
In [fork.rs](lib/crates/fabro-cli/src/commands/run/fork.rs) and [rewind.rs](lib/crates/fabro-cli/src/commands/run/rewind.rs):
|
||||
|
||||
- stop using `ServerRunLookup`
|
||||
- resolve the run via `ServerSummaryLookup`
|
||||
- fetch events/state via the resolved `ServerStoreClient`
|
||||
- keep the local git/checkpoint mutation logic unchanged
|
||||
- before mutating the local repo, validate obvious identity against stored run metadata:
|
||||
- compare the current checkout’s detected repo identity against `RunRecord.repo_origin_url` when present
|
||||
- if they clearly do not match, fail with a targeted error instead of mutating the wrong checkout
|
||||
|
||||
In [rewind.rs](lib/crates/fabro-cli/src/commands/run/rewind.rs):
|
||||
|
||||
- remove dependence on `run.path` for rewound-state cleanup
|
||||
- if a small local run-dir cleanup is still required, compute it server-side or remove it
|
||||
- keep durable run-state restoration (`run.rewound`, restored checkpoint, `run.submitted`) server-backed
|
||||
|
||||
The point is to make rewind/fork depend on the local repo, not on local run-store layout.
|
||||
|
||||
### 5. Repoint `pr *` to server-backed run selection and record loading
|
||||
|
||||
In [pr/mod.rs](lib/crates/fabro-cli/src/commands/pr/mod.rs) and subcommands:
|
||||
|
||||
- remove `runs_base(...)` / `ServerRunLookup::connect_from_runs_base(...)`
|
||||
- resolve runs through `ServerSummaryLookup`
|
||||
- load pull-request state from `get_run_state(...)`
|
||||
|
||||
Specific changes:
|
||||
|
||||
- [pr/list.rs](lib/crates/fabro-cli/src/commands/pr/list.rs)
|
||||
- replace `scan_runs_with_summaries(...)` with summary iteration from `ServerSummaryLookup`
|
||||
- keep current GitHub detail-fetch fanout in the CLI
|
||||
|
||||
- [pr/create.rs](lib/crates/fabro-cli/src/commands/pr/create.rs)
|
||||
- rebuild run state from server events instead of local path lookup
|
||||
- keep local repo detection via `detect_repo_info(...)`
|
||||
- apply the same repo-mismatch guard used by `fork` / `rewind` before proceeding
|
||||
|
||||
- [pr/view.rs](lib/crates/fabro-cli/src/commands/pr/view.rs)
|
||||
- [pr/close.rs](lib/crates/fabro-cli/src/commands/pr/close.rs)
|
||||
- [pr/merge.rs](lib/crates/fabro-cli/src/commands/pr/merge.rs)
|
||||
- load the stored PR record from the target server only
|
||||
|
||||
### 6. Make `diff` fully server-backed and simpler
|
||||
|
||||
In [diff.rs](lib/crates/fabro-cli/src/commands/run/diff.rs):
|
||||
|
||||
- stop using `ServerRunLookup`
|
||||
- resolve via `ServerSummaryLookup`
|
||||
- load `RunProjection` from the target server
|
||||
- keep only two sources of diff output:
|
||||
- per-node `diff`
|
||||
- run-level `final_patch`
|
||||
- remove sandbox reconnect and live diff generation entirely
|
||||
|
||||
Behavior:
|
||||
|
||||
- `fabro diff <run>` prints `final_patch`
|
||||
- `fabro diff <run> --node <id>` prints the stored node diff
|
||||
- if no stored diff exists, error with a clear message
|
||||
|
||||
Because this pass intentionally simplifies the product surface:
|
||||
|
||||
- remove `--stat`
|
||||
- remove `--shortstat`
|
||||
- update docs/tests accordingly
|
||||
|
||||
Also remove dead speculative server API surface tied to the old diff shape:
|
||||
|
||||
- delete `/api/v1/runs/{id}/files` from [fabro-api.yaml](docs/api-reference/fabro-api.yaml)
|
||||
- remove the corresponding `not_implemented` route from [server.rs](lib/crates/fabro-server/src/server.rs)
|
||||
|
||||
This is a Phase 1 OpenAPI/spec change and should be treated as part of that phase explicitly.
|
||||
|
||||
That API is currently unimplemented and unused by the CLI. Keeping it around only adds drift.
|
||||
|
||||
### 7. Repoint `artifact list` and `artifact cp` to the existing server artifact API
|
||||
|
||||
In [artifact/list.rs](lib/crates/fabro-cli/src/commands/artifact/list.rs) and [artifact/cp.rs](lib/crates/fabro-cli/src/commands/artifact/cp.rs):
|
||||
|
||||
- stop using `ServerRunLookup` and `RuntimeState`
|
||||
- resolve the run via `ServerSummaryLookup`
|
||||
- fetch `RunProjection`
|
||||
- enumerate stage IDs from `RunProjection.nodes`
|
||||
- use the existing stage artifact routes for each relevant stage:
|
||||
- list artifact filenames
|
||||
- download artifact bytes
|
||||
|
||||
Keep filtering behavior in the CLI:
|
||||
|
||||
- `--node`
|
||||
- `--retry`
|
||||
- tree/no-tree output layout
|
||||
- filename collision handling
|
||||
|
||||
This preserves the current artifact UX while removing local artifact-dir reads.
|
||||
|
||||
### 8. Finish preview/SSH/file-transfer as real server-owned sandbox operations
|
||||
|
||||
This is the only part of the plan that needs new or completed server APIs.
|
||||
|
||||
#### 8a. Preview
|
||||
|
||||
The route already exists in [fabro-api.yaml](docs/api-reference/fabro-api.yaml) and [server.rs](lib/crates/fabro-server/src/server.rs), but the real handler is still `not_implemented`.
|
||||
|
||||
Implement it in [server.rs](lib/crates/fabro-server/src/server.rs):
|
||||
|
||||
- load the run’s sandbox record from store/state
|
||||
- reconnect server-side
|
||||
- for Daytona:
|
||||
- generate signed or unsigned preview URL as requested
|
||||
- return `409` if:
|
||||
- no active sandbox
|
||||
- sandbox provider does not support preview
|
||||
|
||||
Then repoint [preview.rs](lib/crates/fabro-cli/src/commands/run/preview.rs) to the server API instead of direct Daytona reconnect.
|
||||
|
||||
#### 8b. SSH
|
||||
|
||||
Add a new route to [fabro-api.yaml](docs/api-reference/fabro-api.yaml):
|
||||
|
||||
- `POST /api/v1/runs/{id}/ssh`
|
||||
|
||||
Recommended request/response shape:
|
||||
|
||||
- request:
|
||||
- `ttl_minutes`
|
||||
- response:
|
||||
- `command`
|
||||
|
||||
Implement the handler in [server.rs](lib/crates/fabro-server/src/server.rs):
|
||||
|
||||
- load sandbox record
|
||||
- reconnect server-side
|
||||
- generate SSH access for supported providers
|
||||
- return `409` when unsupported or unavailable
|
||||
|
||||
Then repoint [ssh.rs](lib/crates/fabro-cli/src/commands/run/ssh.rs):
|
||||
|
||||
- `--print` prints the returned command
|
||||
- non-`--print` locally `exec`s the returned command
|
||||
|
||||
That preserves current UX while removing direct CLI sandbox reconnect.
|
||||
|
||||
#### 8c. Sandbox file transfer (`fabro sandbox cp`)
|
||||
|
||||
Add a small server-owned file-transfer surface for sandboxes.
|
||||
|
||||
Recommended routes:
|
||||
|
||||
- `GET /api/v1/runs/{id}/sandbox/files`
|
||||
- query:
|
||||
- `path`
|
||||
- optional `depth`
|
||||
- returns directory entries
|
||||
|
||||
- `GET /api/v1/runs/{id}/sandbox/file`
|
||||
- query:
|
||||
- `path`
|
||||
- returns raw file bytes
|
||||
|
||||
- `PUT /api/v1/runs/{id}/sandbox/file`
|
||||
- query:
|
||||
- `path`
|
||||
- request body:
|
||||
- raw file bytes
|
||||
|
||||
Implementation in [server.rs](lib/crates/fabro-server/src/server.rs):
|
||||
|
||||
- load sandbox record
|
||||
- reconnect server-side
|
||||
- delegate to the existing `Sandbox` trait:
|
||||
- `list_directory`
|
||||
- `download_file_to_local` equivalent via temp file or direct read/write helper
|
||||
- `upload_file_from_local` equivalent via temp file or direct write helper
|
||||
|
||||
CLI changes in [cp.rs](lib/crates/fabro-cli/src/commands/run/cp.rs):
|
||||
|
||||
- stop reconnecting to sandboxes directly
|
||||
- resolve runs via `ServerSummaryLookup`
|
||||
- for recursive download:
|
||||
- list directory via server
|
||||
- download files one by one via server
|
||||
- for upload:
|
||||
- recursively walk local input
|
||||
- upload files one by one via server
|
||||
|
||||
This keeps the current UX and avoids inventing a tar/archive protocol.
|
||||
|
||||
### 9. Update docs/help text to match the new surface
|
||||
|
||||
Update:
|
||||
|
||||
- [docs/reference/cli.mdx](docs/reference/cli.mdx)
|
||||
- [docs/reference/user-configuration.mdx](docs/reference/user-configuration.mdx)
|
||||
- [docs/core-concepts/how-fabro-works.mdx](docs/core-concepts/how-fabro-works.mdx)
|
||||
|
||||
The docs should explicitly reflect:
|
||||
|
||||
- in-scope run-adjacent commands now use `--server`, not `--storage-dir`
|
||||
- `diff` is stored-output only
|
||||
- sandbox preview/SSH/file transfer are server-mediated
|
||||
- local storage-dir maintenance commands still exist, but they are not the normal user-facing run lifecycle
|
||||
|
||||
## Test Plan
|
||||
|
||||
### Help/parser coverage
|
||||
|
||||
Update snapshots in:
|
||||
|
||||
- [artifact_list.rs](lib/crates/fabro-cli/tests/it/cmd/artifact_list.rs)
|
||||
- [artifact_cp.rs](lib/crates/fabro-cli/tests/it/cmd/artifact_cp.rs)
|
||||
- [diff.rs](lib/crates/fabro-cli/tests/it/cmd/diff.rs)
|
||||
- [fork.rs](lib/crates/fabro-cli/tests/it/cmd/fork.rs)
|
||||
- [resume.rs](lib/crates/fabro-cli/tests/it/cmd/resume.rs)
|
||||
- [rewind.rs](lib/crates/fabro-cli/tests/it/cmd/rewind.rs)
|
||||
- [pr_create.rs](lib/crates/fabro-cli/tests/it/cmd/pr_create.rs)
|
||||
- [pr_list.rs](lib/crates/fabro-cli/tests/it/cmd/pr_list.rs)
|
||||
- [pr_view.rs](lib/crates/fabro-cli/tests/it/cmd/pr_view.rs)
|
||||
- [pr_close.rs](lib/crates/fabro-cli/tests/it/cmd/pr_close.rs)
|
||||
- [pr_merge.rs](lib/crates/fabro-cli/tests/it/cmd/pr_merge.rs)
|
||||
- [sandbox_cp.rs](lib/crates/fabro-cli/tests/it/cmd/sandbox_cp.rs)
|
||||
- [sandbox_preview.rs](lib/crates/fabro-cli/tests/it/cmd/sandbox_preview.rs)
|
||||
- [sandbox_ssh.rs](lib/crates/fabro-cli/tests/it/cmd/sandbox_ssh.rs)
|
||||
|
||||
Scenarios:
|
||||
|
||||
- help shows `--server`
|
||||
- help no longer shows `--storage-dir`
|
||||
- `diff --help` no longer shows `--stat` or `--shortstat`
|
||||
- no docs/help text implies these commands honor `FABRO_STORAGE_DIR`
|
||||
|
||||
Use the normal snapshot workflow:
|
||||
|
||||
1. `cargo insta pending-snapshots`
|
||||
2. inspect changes
|
||||
3. `cargo insta accept`
|
||||
|
||||
### CLI targeting behavior
|
||||
|
||||
Add or update CLI tests for each in-scope command family:
|
||||
|
||||
- explicit `--server` wins
|
||||
- configured `[server].target` is used when no flag is passed
|
||||
- no explicit target uses the default local server instance
|
||||
|
||||
Concrete tests:
|
||||
|
||||
- `resume` uses configured server target without local run-dir lookup
|
||||
- `artifact list` uses configured server target without local artifact-dir lookup
|
||||
- `artifact cp` uses configured server target and downloads through the server
|
||||
- `pr list` uses configured server target without scanning local runs/
|
||||
- `pr view`/`pr merge`/`pr close` resolve records from the server target
|
||||
- `sandbox preview` uses the server endpoint instead of direct Daytona reconnect
|
||||
- `sandbox ssh --print` uses the server endpoint and prints the returned command
|
||||
- `sandbox cp` upload/download works against a target server without CLI-side sandbox reconnect
|
||||
- when `[server].target` is configured, these commands use it by default
|
||||
- there is no separate local override path besides passing an explicit local `--server`
|
||||
|
||||
### Diff behavior coverage
|
||||
|
||||
In [diff.rs](lib/crates/fabro-cli/tests/it/cmd/diff.rs):
|
||||
|
||||
- completed run with stored final patch still prints patch
|
||||
- missing stored final patch errors cleanly
|
||||
- stored node diff still works
|
||||
- remove tests that depend on live diff fallback semantics
|
||||
|
||||
### Fork/rewind/resume behavior coverage
|
||||
|
||||
In:
|
||||
|
||||
- [fork.rs](lib/crates/fabro-cli/tests/it/cmd/fork.rs)
|
||||
- [rewind.rs](lib/crates/fabro-cli/tests/it/cmd/rewind.rs)
|
||||
- [resume.rs](lib/crates/fabro-cli/tests/it/cmd/resume.rs)
|
||||
|
||||
Add server-target coverage:
|
||||
|
||||
- configured `[server].target` works without local run-store lookup
|
||||
- explicit `--server` overrides configured target
|
||||
- rewind/fork/resume continue to mutate only the local repo, not local run-store metadata files
|
||||
- rewind/fork/pr-create fail fast when the selected run’s stored `repo_origin_url` clearly does not match the current checkout
|
||||
- rewind/fork/pr-create skip the guard cleanly when older runs do not have a stored durable repo identity yet
|
||||
|
||||
### Server API coverage
|
||||
|
||||
Add server tests in [server.rs](lib/crates/fabro-server/src/server.rs) or the server integration suite for:
|
||||
|
||||
- preview URL generation for a supported sandbox
|
||||
- preview rejects missing/unsupported sandboxes with `409`
|
||||
- SSH command generation for a supported sandbox
|
||||
- SSH rejects missing/unsupported sandboxes with `409`
|
||||
- sandbox file list/download/upload round-trip
|
||||
- stage artifact list/download continues to work for the CLI use case
|
||||
|
||||
### Full verification
|
||||
|
||||
- `cargo fmt --check --all`
|
||||
- `cargo clippy --workspace --all-targets -- -D warnings`
|
||||
- `cargo nextest run --workspace`
|
||||
|
||||
## Risks
|
||||
|
||||
- The biggest risk is accidentally preserving local run-path assumptions under a server-only CLI surface.
|
||||
- Mitigation: delete `--storage-dir` from in-scope commands and remove local lookup usage outright instead of trying to support both models.
|
||||
|
||||
- `fork`, `rewind`, and `pr create` still depend on the caller’s local repo matching the selected run closely enough.
|
||||
- Mitigation: keep that boundary, but add an explicit repo-mismatch guard using stored run metadata so obvious mistakes fail fast.
|
||||
|
||||
- `sandbox cp` is the largest unit because it needs a new server-owned file transfer surface.
|
||||
- Mitigation: keep the API thin and capability-shaped; do not design a generic virtual filesystem protocol.
|
||||
|
||||
- Preview/SSH capability is provider-specific.
|
||||
- Mitigation: standardize on `409` for unsupported or unavailable sandbox capability.
|
||||
|
||||
## Follow-on
|
||||
|
||||
After this lands, the remaining local/admin seam should be small and explicit:
|
||||
|
||||
- `store dump`
|
||||
- `system df`
|
||||
- `system prune`
|
||||
- any hidden/internal commands that truly operate on local storage
|
||||
|
||||
At that point, `ServerRunLookup` should either:
|
||||
|
||||
- be deleted entirely if those commands are also repointed later, or
|
||||
- be clearly renamed/documented as a local maintenance helper rather than a normal user-facing run abstraction
|
||||
|
|
@ -1,243 +0,0 @@
|
|||
# Run/Create Server Target Support
|
||||
|
||||
## Summary
|
||||
Make `fabro run` and `fabro create` targetable via `--server` / `[server].target` now that run submission is manifest-based and server-owned.
|
||||
|
||||
This pass should:
|
||||
|
||||
- add `--server` support to `fabro run` and `fabro create`
|
||||
- align their target-resolution semantics with `preflight`, `validate`, and `graph`
|
||||
- remove the last local-storage-only assumptions from the run submission path
|
||||
- keep local run behavior unchanged when a local server is selected
|
||||
|
||||
This is primarily cleanup/compaction, not a new subsystem. The manifest refactor already made remote submission possible; the CLI surface just has not caught up yet.
|
||||
|
||||
## Scope Boundaries
|
||||
In scope:
|
||||
- `fabro run`
|
||||
- `fabro create`
|
||||
- the internal start/attach/summary helpers required for `fabro run` to work against an explicit server target
|
||||
- docs/help/tests for the new targeting contract
|
||||
|
||||
Out of scope:
|
||||
- adding `--server` to top-level `fabro start`, `fabro attach`, `fabro wait`, `fabro logs`, `fabro inspect`, `fabro diff`, `fabro resume`, or `fabro rewind`
|
||||
- changing the HTTP API
|
||||
- changing manifest structure or workflow bundle persistence
|
||||
- changing server-side run ownership or execution topology
|
||||
|
||||
Accepted temporary asymmetry:
|
||||
- `fabro create --server ...` will be supported in this pass even though the standalone follow-up lifecycle commands remain local-only.
|
||||
- That is acceptable because `create` already prints only a run ID and is useful for automation. A later pass can broaden remote targeting across the rest of the run lifecycle surface.
|
||||
|
||||
## Problem Frame
|
||||
The CLI/server boundary is now inconsistent:
|
||||
|
||||
- `preflight`, `validate`, and `graph` already build manifests and target either a local auto-started server or an explicit remote `--server`
|
||||
- `run` and `create` already build manifests, but they still only flatten `--storage-dir` and then hard-wire submission to `connect_server(settings.storage_dir())`
|
||||
- `run` still assumes every submitted run has a meaningful local run directory for attach and final summary output
|
||||
|
||||
That is architectural drift. The system is already manifest-first and server-canonical. `run` and `create` are the remaining commands that still behave as if run submission is inherently local.
|
||||
|
||||
## Key Decisions
|
||||
- `RunArgs` should flatten `ServerConnectionArgs`, not `StorageDirArgs`.
|
||||
- `fabro create` inherits the same args because it already reuses `RunArgs`.
|
||||
- `run` and `create` should use the same connection contract as other server-backed commands:
|
||||
- explicit `--server` wins
|
||||
- explicit `--storage-dir` selects a local server and suppresses configured `[server].target`
|
||||
- otherwise configured `[server].target` may be used
|
||||
- otherwise the command defaults to the local server for the resolved storage dir
|
||||
- `fabro run` should use one resolved server connection end-to-end for:
|
||||
- manifest submission
|
||||
- `POST /runs/{id}/start`
|
||||
- live attach / polling
|
||||
- `fabro create` should remain run-ID-only output.
|
||||
- It should not pretend there is always a local `run_dir`.
|
||||
- foreground `fabro run` against a remote/configured server should attach successfully.
|
||||
- This requires decoupling attach from local run-dir inference.
|
||||
- remote foreground `run` should print a server-backed final summary that omits local-only fields.
|
||||
- Keep: run ID, status, duration, cost/tokens, failure reason, PR URL, final output
|
||||
- Omit: local run directory path and local artifact listing when there is no local run dir
|
||||
- local `run` behavior should remain unchanged.
|
||||
- If the resolved connection is local, keep the existing local run-dir summary and asset listing behavior.
|
||||
- No OpenAPI change is required.
|
||||
- This is CLI cleanup on top of the existing manifest-backed `POST /runs`.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Add target args to `run` / `create`
|
||||
In `lib/crates/fabro-cli/src/args.rs`:
|
||||
- change `RunArgs` to flatten `ServerConnectionArgs`
|
||||
- remove the dedicated `StorageDirArgs` field from `RunArgs`
|
||||
- keep all existing workflow/run override flags unchanged
|
||||
|
||||
This updates both:
|
||||
- `fabro run`
|
||||
- `fabro create`
|
||||
|
||||
Help/CLI contract to lock down:
|
||||
- `fabro run foo.fabro --server http://127.0.0.1:3000/api/v1`
|
||||
- `fabro create foo.fabro --server /var/run/fabro.sock`
|
||||
- `fabro run foo.fabro --storage-dir /tmp/fabro`
|
||||
- `fabro create foo.fabro` still defaults to local storage unless `[server].target` is configured
|
||||
|
||||
### 2. Resolve run/create connections the same way as other server-backed commands
|
||||
In `lib/crates/fabro-cli/src/commands/run/command.rs` and `lib/crates/fabro-cli/src/commands/run/create.rs`:
|
||||
- keep using local user-config resolution for manifest defaults
|
||||
- load settings with storage-dir override only, using the command-local `storage_dir` value if present
|
||||
- stop deriving the submission client from `settings.storage_dir()`
|
||||
- instead resolve the server connection with the existing server-backed connection logic in `lib/crates/fabro-cli/src/user_config.rs`
|
||||
- connect using the resolved connection, not a hard-coded local store path
|
||||
|
||||
Recommended shape:
|
||||
- let `create_run(...)` return a richer value than `(RunId, PathBuf)`, for example:
|
||||
- `CreatedRun { run_id, local_run_dir: Option<PathBuf>, connection: ServerConnection }`
|
||||
|
||||
Rationale:
|
||||
- `command::execute()` needs more than a run ID now
|
||||
- remote runs have no trustworthy local run dir
|
||||
- passing the resolved connection forward keeps the rest of the flow honest
|
||||
|
||||
In `lib/crates/fabro-cli/src/server_client.rs`:
|
||||
- add a small helper that returns a `ServerStoreClient` from a resolved `ServerConnection`
|
||||
- reuse the existing resolved API-client path rather than introducing parallel target parsing
|
||||
|
||||
### 3. Refactor `run` to start and attach through the resolved server connection
|
||||
In `lib/crates/fabro-cli/src/commands/run/start.rs`:
|
||||
- keep the current public/local helper for top-level `fabro start`
|
||||
- add a connection-agnostic helper that can start a run from an already-connected `ServerStoreClient`
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/run/attach.rs`:
|
||||
- preserve the existing top-level `attach_run(...)` entrypoint for local-storage workflows
|
||||
- extract the existing server-backed attach logic into a helper that accepts:
|
||||
- `&ServerStoreClient`
|
||||
- `&RunId`
|
||||
- `Option<&Path>` for a local run dir
|
||||
- existing `kill_on_detach`, `styles`, and `json_output` flags
|
||||
- make the current top-level local path delegate to that extracted helper after doing its storage-dir/run-id inference
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/run/command.rs`:
|
||||
- for `fabro run`, use the resolved connection returned by `create_run(...)`
|
||||
- if `--detach` is set:
|
||||
- print the run ID and exit exactly as today
|
||||
- otherwise:
|
||||
- start via the resolved server client
|
||||
- attach via the extracted direct-client attach helper
|
||||
- print the final run summary using the same resolved connection
|
||||
|
||||
This keeps `fabro run` coherent for both:
|
||||
- local auto-started server flows
|
||||
- explicit/configured remote server flows
|
||||
|
||||
### 4. Decouple final summary rendering from local run-dir assumptions
|
||||
In `lib/crates/fabro-cli/src/commands/run/output.rs`:
|
||||
- split summary fetching from summary rendering
|
||||
- make the renderer accept:
|
||||
- server-backed run state / conclusion / checkpoint
|
||||
- `Option<&Path>` for a local run dir
|
||||
|
||||
Concrete behavior:
|
||||
- when `local_run_dir` is present:
|
||||
- keep printing the local run path
|
||||
- keep printing local artifact listings
|
||||
- when `local_run_dir` is absent:
|
||||
- do not print a local run path line
|
||||
- do not attempt local artifact discovery
|
||||
- still print the rest of the run conclusion and final output
|
||||
|
||||
This is the smallest cleanup that makes remote foreground `run` feel intentional without broadening the whole remote lifecycle command surface.
|
||||
|
||||
### 5. Keep standalone follow-up lifecycle commands local for now
|
||||
Do **not** add `--server` to these commands in this pass:
|
||||
- `fabro start`
|
||||
- `fabro attach`
|
||||
- `fabro wait`
|
||||
- `fabro logs`
|
||||
- `fabro inspect`
|
||||
- `fabro diff`
|
||||
- `fabro resume`
|
||||
- `fabro rewind`
|
||||
|
||||
Rationale:
|
||||
- they form a larger remote lifecycle surface with selector semantics, replay UX, and local-path assumptions of their own
|
||||
- broadening them now would turn a cleanup pass into a larger capability expansion
|
||||
|
||||
But the plan should call the temporary boundary out explicitly in docs/help text where useful:
|
||||
- `fabro create --server ...` is valid, but follow-up manipulation of that run outside `fabro run` remains a later pass
|
||||
|
||||
### 6. Update docs and help text
|
||||
Update the user-facing references that describe server targeting:
|
||||
- `docs/reference/cli.mdx`
|
||||
- `docs/reference/user-configuration.mdx`
|
||||
- `docs/administration/deploy-server.mdx`
|
||||
|
||||
The docs should explicitly say:
|
||||
- `fabro run` and `fabro create` now honor `--server` / `[server].target`
|
||||
- `fabro exec` still requires explicit `--server`
|
||||
- top-level run lifecycle follow-up commands are still local-storage commands in this pass
|
||||
|
||||
## Test Plan
|
||||
|
||||
### CLI help / parser surface
|
||||
Update snapshots in:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/run.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/create.rs`
|
||||
|
||||
Scenarios:
|
||||
- `run --help` shows both `--storage-dir` and `--server`
|
||||
- `create --help` shows both `--storage-dir` and `--server`
|
||||
|
||||
### `create` targeting behavior
|
||||
In `lib/crates/fabro-cli/tests/it/cmd/create.rs`:
|
||||
- `create --server <http-target>` submits to the explicit server and prints the created run ID
|
||||
- configured `[server].target` reroutes `create` when no explicit target args are passed
|
||||
- explicit `--storage-dir` suppresses configured `[server].target`
|
||||
- explicit `--server` overrides configured `[server].target`
|
||||
- remote-targeted `create` does not require local run-dir inspection to succeed
|
||||
|
||||
### `run` targeting behavior
|
||||
In `lib/crates/fabro-cli/tests/it/cmd/run.rs`:
|
||||
- `run --server <http-target> --detach ...` submits and prints a run ID without relying on a local run dir
|
||||
- foreground `run --server <http-target> ...` creates, starts, attaches, and exits successfully
|
||||
- configured `[server].target` reroutes `run` when no explicit target args are passed
|
||||
- explicit `--storage-dir` suppresses configured `[server].target`
|
||||
- explicit `--server` overrides configured `[server].target`
|
||||
- remote foreground `run` prints a final summary without a local run-directory line
|
||||
- local `run --storage-dir ...` still prints the local run-directory line and local artifact section exactly as today
|
||||
|
||||
### Test infrastructure
|
||||
Prefer a real TCP-bound fabro test server over `httpmock` for `run`.
|
||||
|
||||
Reason:
|
||||
- `run` needs multiple real endpoints (`POST /runs`, `POST /runs/{id}/start`, event replay, run-state polling, question polling)
|
||||
- mocking all of that would verify request wiring but not the actual remote run lifecycle
|
||||
|
||||
If the current CLI integration helpers do not already provide this, add a small reusable helper in:
|
||||
- `lib/crates/fabro-cli/tests/it/support.rs`
|
||||
or
|
||||
- `lib/crates/fabro-test/src/lib.rs`
|
||||
|
||||
That helper should:
|
||||
- launch a real fabro server bound to loopback TCP
|
||||
- return a usable `http://127.0.0.1:PORT/api/v1` target string
|
||||
- keep fixture storage isolated from the invoking CLI’s local storage dir
|
||||
|
||||
## Risks
|
||||
- The biggest risk is hidden local-run-dir assumptions in attach/summary code.
|
||||
- Mitigation: refactor those surfaces explicitly rather than trying to fake a local path for remote runs.
|
||||
- Config-target defaulting could surprise users if docs are not updated.
|
||||
- Mitigation: update CLI docs and help snapshots in the same pass.
|
||||
- Supporting `create --server` before the broader remote lifecycle commands is intentionally asymmetric.
|
||||
- Mitigation: call it out in the plan/docs instead of pretending the whole run lifecycle is remote-ready.
|
||||
|
||||
## Follow-on
|
||||
After this lands, the next logical cleanup is a dedicated remote run-lifecycle plan for:
|
||||
- `start`
|
||||
- `attach`
|
||||
- `wait`
|
||||
- `logs`
|
||||
- `inspect`
|
||||
- `diff`
|
||||
- `resume`
|
||||
- `rewind`
|
||||
|
||||
That should be a separate pass, not folded into this one.
|
||||
|
|
@ -1,842 +0,0 @@
|
|||
# Run Manifest and Preflight
|
||||
|
||||
## Summary
|
||||
|
||||
Replace the current `POST /runs` request — which sends a filesystem path and relies on the server reading workflow definition files from disk — with a self-contained **run manifest**. The CLI gathers all workflow-definition inputs (DOT source, TOML configs, referenced prompt files, imported graphs, child workflows) into a single JSON payload. The server owns all interpretation: config merging, variable expansion, transforms, validation.
|
||||
|
||||
This also introduces `POST /api/v1/preflight`, which accepts the same manifest and returns a structured health report without creating a run.
|
||||
|
||||
After this change, the server no longer reads workflow/config/prompt/import files from the CLI's filesystem. It still uses the manifest `cwd` / resolved working directory for execution context (for example local sandbox and repo-aware behavior). The path-based `workflow_path` submission mode is removed.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
In scope:
|
||||
- define the `RunManifest` schema in the OpenAPI spec
|
||||
- CLI-side manifest builder that walks the workflow tree and bundles all referenced files
|
||||
- file resolver abstraction for transforms (bundle-backed instead of disk-backed)
|
||||
- refactor `FileInliningTransform` and `ImportTransform` to use file resolver
|
||||
- server-side config resolution from manifest layers (args, workflow TOML, project TOML, user TOML)
|
||||
- child workflow resolution from the manifest's workflow map
|
||||
- replace `POST /api/v1/runs` request body with the manifest
|
||||
- new `POST /api/v1/preflight` endpoint using the same manifest
|
||||
- update `fabro run`, `fabro create`, `fabro preflight` to build and send manifests
|
||||
- demo mode for preflight and updated run creation
|
||||
|
||||
Out of scope:
|
||||
- changes to run execution, checkpointing, or resume
|
||||
- changes to sandbox creation or the execution engine
|
||||
- changes to `fabro exec`
|
||||
- encrypted or compressed manifests
|
||||
- manifest size limits or streaming upload
|
||||
|
||||
## Manifest Shape
|
||||
|
||||
```json
|
||||
{
|
||||
"version": 1,
|
||||
"run_id": "01HV6D7S5YF4Z4B2M7K4N0Q6T9",
|
||||
"cwd": "/Users/user/p/my-project",
|
||||
"git": {
|
||||
"origin_url": "https://github.com/acme/my-app.git",
|
||||
"branch": "feature/foo",
|
||||
"sha": "abc123",
|
||||
"clean": true
|
||||
},
|
||||
"goal": {
|
||||
"type": "file",
|
||||
"path": "goal.md",
|
||||
"text": "Build and test the app..."
|
||||
},
|
||||
"args": {
|
||||
"model": "claude-opus-4-6",
|
||||
"sandbox": "local"
|
||||
},
|
||||
"target": {
|
||||
"identifier": "smoke",
|
||||
"path": "fabro/workflows/smoke/workflow.fabro"
|
||||
},
|
||||
"configs": [
|
||||
{ "type": "project", "path": "fabro.toml", "source": "[fabro]\nroot = \"fabro/\"\n..." },
|
||||
{ "type": "user", "path": "/Users/user/.fabro/user.toml", "source": "..." }
|
||||
],
|
||||
"workflows": {
|
||||
"fabro/workflows/smoke/workflow.fabro": {
|
||||
"source": "digraph { ... }",
|
||||
"config": {
|
||||
"path": "fabro/workflows/smoke/workflow.toml",
|
||||
"source": "version = 1\n[vars]\nlanguage = \"rust\""
|
||||
},
|
||||
"files": {
|
||||
"prompts/review.md": {
|
||||
"content": "You are a code reviewer...",
|
||||
"ref": { "type": "file_inline", "original": "@prompts/review.md", "from": "workflow.fabro" }
|
||||
},
|
||||
"validate.fabro": {
|
||||
"content": "digraph { ... }",
|
||||
"ref": { "type": "import", "original": "./validate.fabro", "from": "workflow.fabro" }
|
||||
}
|
||||
}
|
||||
},
|
||||
"fabro/workflows/implement-plan/workflow.fabro": {
|
||||
"source": "digraph { ... }",
|
||||
"files": {
|
||||
"prompts/simplify.md": {
|
||||
"content": "...",
|
||||
"ref": { "type": "file_inline", "original": "@prompts/simplify.md", "from": "workflow.fabro" }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Field semantics:
|
||||
- `version` — manifest schema version, currently `1`
|
||||
- `run_id` — optional pre-generated run ID. Used by detached/local create flows that allocate the run ID in the CLI before submission
|
||||
- `cwd` — the CLI's working directory at invocation time
|
||||
- `git` — optional, observable git state from the CLI's working directory. Omitted if not in a git repo
|
||||
- `origin_url` — remote origin URL, **sanitized** (credentials stripped from HTTPS URLs to prevent token leakage)
|
||||
- `branch` — current branch name
|
||||
- `sha` — current commit SHA
|
||||
- `clean` — whether the working tree has uncommitted changes
|
||||
- `goal` — resolved goal with provenance, always includes `text` (the content) and `type` (`"value"` for literal string, `"file"` for file-sourced, `"graph"` for graph-attribute-sourced). When `type` is `"file"`, includes `path` (original file path from TOML or CLI `--goal-file`). The server uses `text` directly and clears any merged `goal_file` path
|
||||
- `args` — command-local run/preflight args that affect run settings. Sparse: omitted flags are absent. This is not a generic env layer or a dump of global CLI flags
|
||||
- `target.identifier` — what the user typed (slug like `"smoke"` or path like `"./custom.fabro"`)
|
||||
- `target.path` — resolved path, keys into the `workflows` map
|
||||
- `configs` — non-workflow config sources, each with `type` (`"project"` or `"user"`), `path`, and raw TOML `source`
|
||||
- `workflows` — flat map of all workflows (root + children), keyed by resolved path
|
||||
- `source` — raw DOT source (unexpanded, pre-transform)
|
||||
- `config` — optional, the workflow's TOML config with `path` and `source`
|
||||
- `files` — map of normalized logical path (relative to that workflow's root directory) to file entry, each with `content` (file content) and `ref` (discovery metadata: `type`, `original` reference string, and optional `from` logical path for nested imports). Types: `file_inline` (`@file`), `import`, `dockerfile`. Note: `goal_file` no longer appears here — goals are in the top-level `goal` object
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- **CLI gathers, server transforms.** The CLI's only job is reading files from disk and bundling them. All interpretation — TOML parsing, config merging, variable expansion, graph transforms, validation — happens server-side.
|
||||
- **Detached/create flows keep CLI-allocated run IDs.** The manifest carries an optional `run_id`, preserving the current `run -d` / `create` behavior where the CLI can pre-generate the run ID before submission.
|
||||
- **Flat workflow map.** All workflows (root and children, at any nesting depth) are in a single flat `workflows` map. Relationships are implicit via `stack.child_workflow` attributes in the DOT source. This avoids deep nesting and naturally deduplicates shared children.
|
||||
- **Inline child workflows stay inline.** `stack.child_dot_source` continues to work exactly as it does today and does not need manifest bundling. Manifest child-workflow support is specifically for `stack.child_workflow` / `stack.child_dotfile`.
|
||||
- **Child workflows don't have their own settings.** Today `parse_child_graph()` passes `Settings::default()` to children and never loads their TOML. The manifest preserves this — child workflow entries carry their DOT source and files but no separate config layers. If a child has a `workflow.toml`, it can optionally be included in `config` for future use, but the server does not merge it today.
|
||||
- **Config resolution moves to the server.** The CLI currently merges `cli_args.combine(workflow_config).combine(project_config).combine(user_config).resolve()`. The manifest ships the raw layers and the server performs the merge. Merge precedence is determined by the server based on config `type`, not by array order.
|
||||
- **Server merge precedence:** `args` > workflow `config` > `project` config > `user` config > server defaults. There is no separate manifest `env` layer. Server-owned operational settings such as `storage_dir`, `[server]`, `api`, `web`, `features`, `log`, and `exec` are ignored from manifest configs; the active server instance owns those.
|
||||
- **File resolution must stay contextual.** Transforms currently resolve relative paths based on the current graph/file location. The manifest refactor cannot collapse that to `resolve("foo.md") -> content`; the resolver must accept the current logical directory so nested imports like `subflow/imported.fabro -> @prompts/foo.md` still resolve correctly.
|
||||
- **Goal is resolved by the CLI and travels as a top-level object.** The CLI resolves the final goal using the current precedence rules (`--goal` / `--goal-file` over merged config `goal` / `goal_file`, otherwise graph-level `goal`) and sends it as `manifest.goal`. The server applies `manifest.goal.text` after config merge and clears `goal_file`, so goal handling never requires filesystem reads server-side.
|
||||
- **Git state travels in the manifest.** The CLI captures origin URL (sanitized — credentials stripped from HTTPS URLs), current branch, commit SHA, and clean/dirty status. This replaces the server's need to run git commands or access the repo filesystem. Credential sanitization is mandatory to prevent token leakage in HTTPS URLs with embedded PATs or installation tokens.
|
||||
- **`workflow_path` mode is removed.** After migration, the server only accepts manifests. The `dot_source` / `workflow_path` fields in `CreateRunRequest` are replaced by the manifest.
|
||||
- **Preflight uses the same manifest.** `POST /api/v1/preflight` accepts a `RunManifest` and returns a `PreflightResponse` with workflow diagnostics plus the rendered checks payload. No validated manifest round-trip.
|
||||
- **Manifest discovery walks the DOT AST.** The CLI must parse the DOT source enough to find `@file` references (in `prompt` and `goal` attributes), `import` attributes, and `stack.child_workflow` / `stack.child_dotfile` attributes. It does NOT run the full transform pipeline — just scans for file references.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. File resolver abstraction
|
||||
|
||||
Create `lib/crates/fabro-workflow/src/file_resolver.rs`.
|
||||
|
||||
```rust
|
||||
pub trait FileResolver: Send + Sync {
|
||||
/// Resolve a logical reference string relative to the current logical directory.
|
||||
/// Returns the normalized logical path plus file content.
|
||||
fn resolve(&self, current_dir: &Path, reference: &str) -> Option<ResolvedFile>;
|
||||
}
|
||||
|
||||
pub struct ResolvedFile {
|
||||
pub logical_path: PathBuf,
|
||||
pub content: String,
|
||||
}
|
||||
```
|
||||
|
||||
One implementation:
|
||||
|
||||
**`BundleFileResolver`** — reads from a manifest's files map:
|
||||
```rust
|
||||
pub struct BundleFileResolver {
|
||||
files: HashMap<PathBuf, String>,
|
||||
}
|
||||
```
|
||||
The resolver normalizes `current_dir.join(reference)` into a workflow-relative logical path (strip leading `./`, collapse `.` / `..`) and looks up that normalized key. This preserves the current import/file-inlining semantics without any filesystem access. The `files` map is built from the manifest's `ManifestFileEntry` objects (extracting `content` by normalized logical path key).
|
||||
|
||||
No `DiskFileResolver` is needed — this is a hard cutover. The existing filesystem-based resolution logic in the transforms is replaced entirely.
|
||||
|
||||
Add `pub mod file_resolver;` to `lib/crates/fabro-workflow/src/lib.rs`.
|
||||
|
||||
Tests:
|
||||
- `BundleFileResolver` with test data, verify exact key lookup works
|
||||
- Verify `None` for missing files
|
||||
- Verify path normalization handles `./` prefix stripping and nested `..`
|
||||
- Verify nested import scoping resolves relative to the imported file's logical directory
|
||||
|
||||
### 2. Refactor FileInliningTransform
|
||||
|
||||
In `lib/crates/fabro-workflow/src/transforms/file_inlining.rs`:
|
||||
|
||||
Change the struct to hold a resolver instead of paths:
|
||||
```rust
|
||||
pub struct FileInliningTransform {
|
||||
resolver: Arc<dyn FileResolver>,
|
||||
}
|
||||
|
||||
impl FileInliningTransform {
|
||||
pub fn new(resolver: Arc<dyn FileResolver>) -> Self {
|
||||
Self { resolver }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Update `resolve_file_ref` to use the resolver:
|
||||
- strip the `@` prefix to get the relative path
|
||||
- call `self.resolver.resolve(current_dir, path_str)` instead of `std::fs::read_to_string`
|
||||
- thread the current logical directory through the transform so imported files can inline their own relative references correctly
|
||||
- remove tilde expansion and `canonicalize` logic (the CLI resolved all paths during bundling)
|
||||
|
||||
The `apply()` method stays structurally the same — it iterates node prompts and graph goal, calling the updated resolution logic.
|
||||
|
||||
### 3. Refactor ImportTransform
|
||||
|
||||
In `lib/crates/fabro-workflow/src/transforms/import.rs`:
|
||||
|
||||
Same pattern — hold a resolver:
|
||||
```rust
|
||||
pub struct ImportTransform {
|
||||
resolver: Arc<dyn FileResolver>,
|
||||
}
|
||||
```
|
||||
|
||||
Update `resolve_import_path` and `prepare_import`:
|
||||
- `resolve_import_path` uses `self.resolver.resolve(current_dir, path_str)` instead of filesystem canonicalize
|
||||
- `prepare_import` gets the file content from the resolver instead of `std::fs::read_to_string`
|
||||
- when applying `FileInliningTransform` to imported content, pass the same resolver plus the imported file's logical parent directory
|
||||
|
||||
The recursive import expansion and circular import detection stay the same.
|
||||
|
||||
### 4. Update transform pipeline
|
||||
|
||||
In `lib/crates/fabro-workflow/src/pipeline/transform.rs`:
|
||||
|
||||
Change `TransformOptions` to carry a resolver:
|
||||
```rust
|
||||
pub struct TransformOptions {
|
||||
pub file_resolver: Option<Arc<dyn FileResolver>>,
|
||||
pub custom_transforms: Vec<Box<dyn Transform>>,
|
||||
}
|
||||
```
|
||||
|
||||
Update the `transform` function:
|
||||
- where it currently checks `options.base_dir.is_some()` to gate `ImportTransform` and `FileInliningTransform`, check `options.file_resolver.is_some()` instead
|
||||
- construct the transforms with the resolver
|
||||
|
||||
### 5. Manifest schema in OpenAPI
|
||||
|
||||
In `docs/api-reference/fabro-api.yaml`, add schemas:
|
||||
|
||||
```yaml
|
||||
RunManifest:
|
||||
description: Self-contained workflow run manifest.
|
||||
type: object
|
||||
required:
|
||||
- version
|
||||
- cwd
|
||||
- target
|
||||
- workflows
|
||||
properties:
|
||||
version:
|
||||
type: integer
|
||||
description: Manifest schema version.
|
||||
example: 1
|
||||
run_id:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Optional pre-generated run ID to use instead of allocating a new ULID.
|
||||
example: "01HV6D7S5YF4Z4B2M7K4N0Q6T9"
|
||||
cwd:
|
||||
type: string
|
||||
description: CLI working directory at invocation time.
|
||||
git:
|
||||
$ref: "#/components/schemas/ManifestGit"
|
||||
goal:
|
||||
$ref: "#/components/schemas/ManifestGoal"
|
||||
args:
|
||||
$ref: "#/components/schemas/ManifestArgs"
|
||||
target:
|
||||
$ref: "#/components/schemas/ManifestTarget"
|
||||
configs:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/ManifestConfig"
|
||||
workflows:
|
||||
type: object
|
||||
additionalProperties:
|
||||
$ref: "#/components/schemas/ManifestWorkflow"
|
||||
|
||||
ManifestGit:
|
||||
description: Observable git state from the CLI working directory.
|
||||
type: object
|
||||
required:
|
||||
- origin_url
|
||||
- branch
|
||||
- sha
|
||||
- clean
|
||||
properties:
|
||||
origin_url:
|
||||
type: string
|
||||
description: >
|
||||
Remote origin URL, sanitized (credentials stripped from HTTPS URLs).
|
||||
e.g. https://user:token@github.com/acme/app.git becomes https://github.com/acme/app.git
|
||||
example: "https://github.com/acme/my-app.git"
|
||||
branch:
|
||||
type: string
|
||||
description: Current branch name.
|
||||
example: feature/foo
|
||||
sha:
|
||||
type: string
|
||||
description: Current commit SHA.
|
||||
example: abc123def
|
||||
clean:
|
||||
type: boolean
|
||||
description: Whether the working tree has uncommitted changes.
|
||||
|
||||
ManifestGoal:
|
||||
description: Resolved goal with provenance.
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- text
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- value
|
||||
- file
|
||||
- graph
|
||||
description: >
|
||||
How the goal was sourced: "value" (literal from TOML goal field or --goal flag),
|
||||
"file" (resolved from goal_file), "graph" (from graph-level goal attribute in DOT).
|
||||
text:
|
||||
type: string
|
||||
description: The resolved goal content. Server uses this directly.
|
||||
path:
|
||||
type: string
|
||||
description: Original file path (only present when type is "file").
|
||||
|
||||
ManifestTarget:
|
||||
type: object
|
||||
required:
|
||||
- identifier
|
||||
- path
|
||||
properties:
|
||||
identifier:
|
||||
type: string
|
||||
description: What the user typed (slug or path).
|
||||
example: smoke
|
||||
path:
|
||||
type: string
|
||||
description: Resolved path, keys into the workflows map.
|
||||
example: fabro/workflows/smoke/workflow.fabro
|
||||
|
||||
ManifestConfig:
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- project
|
||||
- user
|
||||
path:
|
||||
type: string
|
||||
description: Filesystem path to the config file.
|
||||
source:
|
||||
type: string
|
||||
description: Raw TOML source of the config file.
|
||||
|
||||
ManifestWorkflowConfig:
|
||||
type: object
|
||||
required:
|
||||
- path
|
||||
- source
|
||||
properties:
|
||||
path:
|
||||
type: string
|
||||
description: Path to the workflow TOML file.
|
||||
source:
|
||||
type: string
|
||||
description: Raw TOML source.
|
||||
|
||||
ManifestArgs:
|
||||
description: Command-local run/preflight flags that affect run settings. All fields optional (sparse).
|
||||
type: object
|
||||
properties:
|
||||
model:
|
||||
type: string
|
||||
provider:
|
||||
type: string
|
||||
sandbox:
|
||||
type: string
|
||||
verbose:
|
||||
type: boolean
|
||||
dry_run:
|
||||
type: boolean
|
||||
auto_approve:
|
||||
type: boolean
|
||||
no_retro:
|
||||
type: boolean
|
||||
preserve_sandbox:
|
||||
type: boolean
|
||||
label:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
|
||||
ManifestFileEntry:
|
||||
description: A bundled file with discovery metadata.
|
||||
type: object
|
||||
required:
|
||||
- content
|
||||
- ref
|
||||
properties:
|
||||
content:
|
||||
type: string
|
||||
description: File content.
|
||||
ref:
|
||||
$ref: "#/components/schemas/ManifestFileRef"
|
||||
|
||||
ManifestFileRef:
|
||||
description: How this file was discovered.
|
||||
type: object
|
||||
required:
|
||||
- type
|
||||
- original
|
||||
properties:
|
||||
type:
|
||||
type: string
|
||||
enum:
|
||||
- file_inline
|
||||
- import
|
||||
- dockerfile
|
||||
description: Discovery type.
|
||||
original:
|
||||
type: string
|
||||
description: The reference string as it appeared in the DOT/TOML.
|
||||
example: "@prompts/review.md"
|
||||
from:
|
||||
type: string
|
||||
description: Optional logical path of the file/graph that referenced this entry.
|
||||
|
||||
ManifestWorkflow:
|
||||
type: object
|
||||
required:
|
||||
- source
|
||||
properties:
|
||||
source:
|
||||
type: string
|
||||
description: Raw DOT source (unexpanded, pre-transform).
|
||||
config:
|
||||
$ref: "#/components/schemas/ManifestWorkflowConfig"
|
||||
files:
|
||||
type: object
|
||||
additionalProperties:
|
||||
$ref: "#/components/schemas/ManifestFileEntry"
|
||||
description: >
|
||||
Map of normalized logical path to file entry with content and discovery metadata.
|
||||
```
|
||||
|
||||
Replace the `CreateRunRequest` schema with `RunManifest` on `POST /api/v1/runs`.
|
||||
|
||||
Add `POST /api/v1/preflight`:
|
||||
```yaml
|
||||
/api/v1/preflight:
|
||||
post:
|
||||
operationId: runPreflight
|
||||
tags: [Runs]
|
||||
summary: Validate a workflow manifest without creating a run.
|
||||
description: >
|
||||
Accepts the same manifest as POST /runs. Validates the workflow,
|
||||
checks sandbox availability, LLM provider access, and GitHub token
|
||||
minting. Returns a structured pass/fail report.
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/RunManifest"
|
||||
responses:
|
||||
"200":
|
||||
description: Preflight report.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/PreflightResponse"
|
||||
```
|
||||
|
||||
The preflight response should preserve the current CLI JSON contract:
|
||||
- `workflow` summary/diagnostics from validation
|
||||
- `checks` as the rendered report payload
|
||||
|
||||
So add:
|
||||
```yaml
|
||||
PreflightResponse:
|
||||
type: object
|
||||
required:
|
||||
- workflow
|
||||
- checks
|
||||
properties:
|
||||
workflow:
|
||||
$ref: "#/components/schemas/PreflightWorkflowSummary"
|
||||
checks:
|
||||
$ref: "#/components/schemas/DiagnosticsReport"
|
||||
```
|
||||
|
||||
Rebuild `fabro-api`:
|
||||
```
|
||||
cargo build -p fabro-api
|
||||
```
|
||||
|
||||
### 6. Server-side config resolution from manifest
|
||||
|
||||
Create `lib/crates/fabro-server/src/manifest.rs`.
|
||||
|
||||
This module:
|
||||
|
||||
1. **Parses run-relevant config layers from the manifest:**
|
||||
- `args` → converted to a `ConfigLayer` (map CLI arg names to `ConfigLayer` fields, similar to `TryFrom<&RunArgs>` in `overrides.rs`)
|
||||
- workflow `config.source` → parsed as TOML via `fabro_config` and converted to `ConfigLayer`
|
||||
- each `configs[]` entry → parsed as TOML and converted to `ConfigLayer`
|
||||
- strip or ignore non-run fields from uploaded configs (`storage_dir`, `[server]`, `api`, `web`, `features`, `log`, `exec`, `max_concurrent_runs`)
|
||||
|
||||
2. **Merges in server-determined precedence:**
|
||||
```rust
|
||||
pub fn resolve_settings(manifest: &RunManifest, server_defaults: &Settings) -> Result<Settings> {
|
||||
let args_layer = parse_args_layer(&manifest.args)?;
|
||||
let workflow_layer = parse_workflow_config(manifest)?;
|
||||
let project_layer = find_config_layer(manifest, "project")?;
|
||||
let user_layer = find_config_layer(manifest, "user")?;
|
||||
|
||||
args_layer
|
||||
.combine(workflow_layer)
|
||||
.combine(project_layer)
|
||||
.combine(user_layer)
|
||||
.resolve()
|
||||
}
|
||||
```
|
||||
|
||||
3. **Applies the top-level goal after merge.**
|
||||
- if `manifest.goal` is present, set `settings.goal = Some(manifest.goal.text.clone())`
|
||||
- clear `settings.goal_file` so server-side goal handling never tries to read the filesystem
|
||||
|
||||
4. **Builds a `BundleFileResolver`** from the target workflow's `files` map.
|
||||
|
||||
5. **Constructs a `CreateRunInput`** with:
|
||||
- `WorkflowInput::DotSource { source, base_dir: None }` — using the raw DOT from the manifest
|
||||
- resolved `Settings`
|
||||
- `cwd` from the manifest
|
||||
- a `file_resolver` for the transform pipeline
|
||||
|
||||
The `parse_args_layer` function maps manifest `args` keys to `ConfigLayer` fields. The mapping mirrors the current `TryFrom<&RunArgs>` / `TryFrom<&PreflightArgs>` logic in `overrides.rs`, but without `goal` / `goal_file` because those are represented by the top-level `goal` object. The keys are the same field names: `model`, `provider`, `sandbox`, `verbose`, `dry_run`, `auto_approve`, `no_retro`, `preserve_sandbox`, `label`.
|
||||
|
||||
### 7. Update POST /runs handler
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
|
||||
Replace the current `create_run` handler. The new handler:
|
||||
|
||||
1. Deserializes the request body as `RunManifest`.
|
||||
2. Validates manifest version is supported.
|
||||
3. Calls `manifest::resolve_settings(&manifest, &state.settings)` to merge configs.
|
||||
4. Looks up the root workflow in `manifest.workflows` using `manifest.target.path`.
|
||||
5. Builds a `BundleFileResolver` from the root workflow's `files` map.
|
||||
6. Parses `manifest.run_id` when present, preserving the current detached/local create behavior.
|
||||
7. Constructs `CreateRunInput`:
|
||||
```rust
|
||||
CreateRunInput {
|
||||
workflow: WorkflowInput::DotSource {
|
||||
source: root_workflow.source.clone(),
|
||||
base_dir: None,
|
||||
},
|
||||
settings,
|
||||
cwd: PathBuf::from(&manifest.cwd),
|
||||
workflow_slug: Some(manifest.target.identifier.clone()),
|
||||
run_id: Some(run_id),
|
||||
host_repo_path: None,
|
||||
base_branch: None,
|
||||
}
|
||||
```
|
||||
8. Passes the manifest's workflow map to `operations::create()` so child workflows can be resolved later.
|
||||
|
||||
The `operations::create()` and `validate()` paths in `fabro-workflow` need to accept the file resolver (via `TransformOptions`) and the workflow map (for child resolution). This requires updating `CreateRunInput`, `ValidateInput`, or shared workflow-resolution state:
|
||||
|
||||
```rust
|
||||
pub struct CreateRunInput {
|
||||
pub workflow: WorkflowInput,
|
||||
pub settings: Settings,
|
||||
pub cwd: PathBuf,
|
||||
pub workflow_slug: Option<String>,
|
||||
pub run_id: Option<RunId>,
|
||||
pub host_repo_path: Option<String>,
|
||||
pub base_branch: Option<String>,
|
||||
pub file_resolver: Option<Arc<dyn FileResolver>>,
|
||||
pub workflow_bundle: Option<HashMap<String, ManifestWorkflow>>,
|
||||
}
|
||||
```
|
||||
|
||||
In `operations::create()` (`create.rs`) and `validate()` (`validate.rs`), when `file_resolver` is `Some`, use it in `TransformOptions` instead of relying on `base_dir`.
|
||||
|
||||
### 8. Child workflow resolution from manifest
|
||||
|
||||
In `lib/crates/fabro-workflow/src/handler/manager_loop.rs`:
|
||||
|
||||
`parse_child_graph()` currently resolves `stack.child_workflow` as `WorkflowInput::Path` and reads from disk. Update it to check for a workflow bundle first:
|
||||
|
||||
```rust
|
||||
fn parse_child_graph(node: &Node, services: &EngineServices) -> Result<...> {
|
||||
// ... existing stack.child_dot_source handling ...
|
||||
|
||||
if let Some(path) = node.attr("stack.child_workflow").or(node.attr("stack.child_dotfile")) {
|
||||
let bundle = services.workflow_bundle.as_ref()
|
||||
.ok_or_else(|| anyhow!("no workflow bundle available"))?;
|
||||
let child = bundle.get(path)
|
||||
.ok_or_else(|| anyhow!("child workflow not found in manifest: {path}"))?;
|
||||
let resolver = BundleFileResolver::new(child.files.clone());
|
||||
// Pass resolver plus the child's logical root to validate()
|
||||
Ok(WorkflowInput::DotSource {
|
||||
source: child.source.clone(),
|
||||
base_dir: None,
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Add `workflow_bundle: Option<Arc<HashMap<String, ManifestWorkflow>>>` to `EngineServices` so it is accessible during execution.
|
||||
|
||||
When the child workflow is resolved from the bundle, its own `files` map provides a scoped `BundleFileResolver` for that child's transforms (`@file` refs, imports within the child).
|
||||
|
||||
### 9. CLI manifest builder
|
||||
|
||||
Create `lib/crates/fabro-cli/src/manifest_builder.rs`.
|
||||
|
||||
This module builds a `RunManifest` from CLI inputs:
|
||||
|
||||
```rust
|
||||
pub struct ManifestBuilder;
|
||||
|
||||
impl ManifestBuilder {
|
||||
pub fn build_for_run(cwd: PathBuf, args: &RunArgs) -> Result<RunManifest> { ... }
|
||||
pub fn build_for_preflight(cwd: PathBuf, args: &PreflightArgs) -> Result<RunManifest> { ... }
|
||||
}
|
||||
```
|
||||
|
||||
The build process:
|
||||
|
||||
1. **Resolve workflow path**: call `project_config::resolve_workflow_path(&args.workflow, &cwd)` to get the `.fabro` file path and optional `.toml` config path.
|
||||
|
||||
2. **Read the root workflow**:
|
||||
- read the `.fabro` file: `std::fs::read_to_string(&dot_path)`
|
||||
- if a `.toml` exists, read it: `std::fs::read_to_string(&toml_path)`
|
||||
|
||||
3. **Discover file references in the DOT source**:
|
||||
- parse the DOT source with `parser::parse(&source)`
|
||||
- scan all nodes for `prompt` attributes starting with `@` → collect file paths
|
||||
- scan graph-level `goal` attribute for `@` prefix → collect file path
|
||||
- scan all nodes for `import` attributes → collect file paths
|
||||
- scan all nodes for `stack.child_workflow` / `stack.child_dotfile` attributes → collect child workflow paths
|
||||
|
||||
4. **Resolve the final goal**:
|
||||
- compute the final goal using the current precedence rules (`--goal` / `--goal-file` over merged config `goal` / `goal_file`, otherwise graph-level `goal`)
|
||||
- store it in top-level `manifest.goal`
|
||||
- do **not** add `goal_file` to the workflow `files` map
|
||||
|
||||
5. **Resolve file references from the TOML config**:
|
||||
- if the TOML has `sandbox.daytona.snapshot.dockerfile.path`, read the Dockerfile and add to `files`
|
||||
|
||||
6. **Read all discovered files** into the `files` map, keyed by normalized logical path relative to the workflow root. Resolve relative to the `.fabro` file's parent directory, with `~/.fabro` as fallback (matching current `resolve_file_ref` logic).
|
||||
|
||||
7. **Recursively process child workflows** (step 3-6 for each child). Children go into the flat `workflows` map. Detect circular references via a visited set.
|
||||
|
||||
8. **Process imported `.fabro` files**: imports also go into the workflow's `files` map (they are read and their content is stored under workflow-relative logical paths). Imported files may themselves contain `@file` refs and nested imports — the builder must recursively discover these too.
|
||||
|
||||
9. **Gather configs**:
|
||||
- read `fabro.toml` via `project_config::discover_project_config()`
|
||||
- read `~/.fabro/user.toml` via the user config path
|
||||
- for each, record `type`, `path`, and raw `source`
|
||||
|
||||
10. **Gather args**: serialize the command-local args that affect run settings. Use the same field names as `ConfigLayer` (`model`, `provider`, `sandbox`, etc.) but exclude `goal` / `goal_file` because those are represented by top-level `manifest.goal`. Only include fields that the user actually set (sparse).
|
||||
|
||||
11. **Carry the optional run ID** from `RunArgs.run_id` when present.
|
||||
|
||||
12. **Assemble and return** the `RunManifest`.
|
||||
|
||||
The DOT parser is already available in `fabro-workflow`. The CLI already depends on `fabro-workflow` (it calls `validate()`). The manifest builder reuses the parser for discovery but does NOT run transforms.
|
||||
|
||||
### 10. Update CLI commands
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/run/create.rs`:
|
||||
|
||||
Replace the current flow:
|
||||
```rust
|
||||
// Before (sends path + pre-resolved settings):
|
||||
let settings = cli_args_config.combine(workflow_config).combine(cli_defaults).resolve()?;
|
||||
client.create_run_from_workflow_path(workflow_path, &cwd, &settings, run_id)
|
||||
|
||||
// After (sends manifest):
|
||||
let manifest = ManifestBuilder::build_for_run(cwd, &args)?;
|
||||
client.create_run_from_manifest(&manifest)
|
||||
```
|
||||
|
||||
Remove `create_run_from_workflow_path` from `server_client.rs`. Add `create_run_from_manifest` that POSTs the manifest JSON.
|
||||
|
||||
The optional local validation step (lines 39-51) can be removed — the server validates as part of run creation. Or it can stay as a fast-fail with a note that it won't catch everything the server checks.
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/run/overrides.rs`:
|
||||
|
||||
The `TryFrom<&RunArgs> for ConfigLayer` conversion is no longer needed for the settings merge (the server does it). But the args serialization for the manifest's `args` field needs similar logic. Consider:
|
||||
- keeping the conversion as a helper for building the manifest's `args` object
|
||||
- or writing a new `RunArgs::to_manifest_args()` method that produces a JSON map
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/preflight.rs`:
|
||||
|
||||
Replace the current flow:
|
||||
```rust
|
||||
// Before (runs all checks CLI-side):
|
||||
let settings = cli_args_config.combine(workflow_config).combine(cli_defaults).resolve()?;
|
||||
validate(ValidateInput { ... })?;
|
||||
run_preflight(&settings, ...)?;
|
||||
|
||||
// After (sends manifest to server):
|
||||
let manifest = ManifestBuilder::build_for_preflight(cwd, &args)?;
|
||||
let cli_settings = load_user_settings_with_storage_dir(args.storage_dir.as_deref())?;
|
||||
let client = server_client::connect_server(&cli_settings.storage_dir()).await?;
|
||||
let response = client.run_preflight().body(manifest).send().await?;
|
||||
render_report(&response.checks);
|
||||
```
|
||||
|
||||
Remove all local preflight check functions. The CLI becomes a thin client that builds the manifest, sends it, and renders the response.
|
||||
|
||||
### 11. Preflight handler on server
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
|
||||
```rust
|
||||
async fn run_preflight(
|
||||
_auth: AuthenticatedService,
|
||||
State(state): State<Arc<AppState>>,
|
||||
Json(manifest): Json<RunManifest>,
|
||||
) -> Response {
|
||||
let report = preflight::run_preflight(&state, &manifest).await;
|
||||
(StatusCode::OK, Json(report)).into_response()
|
||||
}
|
||||
```
|
||||
|
||||
Create `lib/crates/fabro-server/src/preflight.rs`.
|
||||
|
||||
This module adapts the checks from the current CLI-side `preflight.rs`:
|
||||
|
||||
1. **Resolve settings** from manifest via `manifest::resolve_settings()`.
|
||||
2. **Validate the workflow** — parse, transform (using `BundleFileResolver`), validate.
|
||||
3. **Check sandbox** — resolve sandbox provider from settings, attempt to create/initialize a test sandbox.
|
||||
4. **Check LLM providers** — for each model used by the graph, verify the provider is configured (secret exists in secret store) and reachable.
|
||||
5. **Check GitHub token** — if the workflow has `github.permissions`, attempt to mint a test installation access token.
|
||||
|
||||
Each check produces a `CheckResult`. The function returns a `PreflightResponse` with:
|
||||
- `workflow` summary (`name`, node/edge counts, goal, diagnostics)
|
||||
- `checks` as the `DiagnosticsReport` payload
|
||||
|
||||
Add route in `real_routes()`:
|
||||
```rust
|
||||
.route("/preflight", post(run_preflight))
|
||||
```
|
||||
|
||||
### 12. Demo mode
|
||||
|
||||
In `lib/crates/fabro-server/src/demo/mod.rs`:
|
||||
|
||||
**Run creation demo**: The demo handler already exists for `POST /runs`. Update it to accept the manifest schema. The demo can ignore the manifest contents and return a canned run response as it does today.
|
||||
|
||||
**Preflight demo**: Return an all-passing preflight report:
|
||||
```rust
|
||||
pub(crate) async fn run_preflight(
|
||||
_auth: AuthenticatedService,
|
||||
State(_state): State<Arc<AppState>>,
|
||||
Json(_manifest): Json<RunManifest>,
|
||||
) -> Response {
|
||||
(StatusCode::OK, Json(serde_json::json!({
|
||||
"workflow": {
|
||||
"name": "demo",
|
||||
"nodes": 3,
|
||||
"edges": 2,
|
||||
"goal": "Demo",
|
||||
"diagnostics": []
|
||||
},
|
||||
"checks": {
|
||||
"version": fabro_util::version::FABRO_VERSION,
|
||||
"sections": [
|
||||
{
|
||||
"title": "Workflow",
|
||||
"checks": [
|
||||
{ "name": "Parse & Validate", "status": "pass", "summary": "3 nodes, 2 edges, goal set", "details": [] },
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Sandbox",
|
||||
"checks": [
|
||||
{ "name": "Provider", "status": "pass", "summary": "local sandbox available", "details": [] },
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "LLM",
|
||||
"checks": [
|
||||
{ "name": "Providers", "status": "pass", "summary": "Anthropic, OpenAI reachable", "details": [] },
|
||||
]
|
||||
},
|
||||
]
|
||||
}
|
||||
}))).into_response()
|
||||
}
|
||||
```
|
||||
|
||||
Wire in `demo_routes()`:
|
||||
```rust
|
||||
.route("/preflight", post(demo::run_preflight))
|
||||
```
|
||||
|
||||
### 13. Cleanup
|
||||
|
||||
After the manifest is working:
|
||||
|
||||
- **Remove `workflow_path` mode** from the `POST /runs` handler. Remove the `workflow_path`, `cwd`, `settings_json` fields from the request schema. Remove `CreateRunRequest` from the OpenAPI spec and replace with `RunManifest`.
|
||||
- **Keep `WorkflowInput::Path` for local-only CLI commands.** Do not remove it from `source.rs`; commands like `validate` and `graph` still use local path resolution. The cleanup is server-specific: remove the server's path-based submission path, not the workflow crate's local path input abstraction.
|
||||
- **No `DiskFileResolver` to remove** — it was never created (hard cutover).
|
||||
- **Remove `create_run_from_workflow_path`** from `server_client.rs`.
|
||||
- **Remove `ConfigLayer::for_workflow()`** usage from CLI run/preflight commands (the server does config resolution now). The function itself may still be useful for other CLI code paths.
|
||||
- **Remove CLI-side preflight check functions** from `preflight.rs`.
|
||||
- **Remove `TryFrom<&RunArgs> for ConfigLayer`** if replaced by manifest args serialization.
|
||||
|
||||
## Implementation Order
|
||||
|
||||
```
|
||||
1 File resolver trait + BundleFileResolver (no deps)
|
||||
2 Refactor FileInliningTransform to use resolver (depends on 1)
|
||||
3 Refactor ImportTransform to use resolver (depends on 1)
|
||||
4 Update transform pipeline (TransformOptions) (depends on 2, 3)
|
||||
5 Manifest schema in OpenAPI + rebuild fabro-api (no deps, parallel with 1-4)
|
||||
6 Server-side config resolution (manifest.rs) (depends on 5)
|
||||
7 CLI manifest builder (depends on 5)
|
||||
8 Update POST /runs handler to accept manifest (depends on 4, 6)
|
||||
9 Child workflow resolution from manifest (depends on 8)
|
||||
10 Update CLI run/create to send manifest (depends on 7, 8)
|
||||
11 Preflight server handler (depends on 4, 6)
|
||||
12 Update CLI preflight to send manifest (depends on 7, 11)
|
||||
13 Demo mode (depends on 5)
|
||||
14 Cleanup: remove workflow_path mode + dead code (depends on 10, 12)
|
||||
```
|
||||
|
||||
Steps 1-4 (resolver refactor) and 5 (schema) can proceed in parallel. Step 7 (CLI builder) and 6 (server config) can proceed in parallel once the schema exists.
|
||||
|
||||
## Resolved Questions
|
||||
|
||||
1. **`args` field schema**: **Typed and limited to run settings.** The OpenAPI schema defines explicit fields matching the command-local run/preflight overrides (model, provider, sandbox, verbose, dry_run, auto_approve, no_retro, preserve_sandbox, label). `goal` / `goal_file` are excluded because the final goal is represented by top-level `manifest.goal`. All fields are optional (sparse — only set fields are present).
|
||||
|
||||
2. **Import path scoping**: **Workflow-relative logical paths plus contextual resolution.** All file paths in a workflow's `files` map are normalized logical paths relative to that workflow's root directory. Each file entry carries `ref` metadata with `type`, `original`, and optional `from`. The server resolves nested imports and `@file` references by passing the current logical directory into the resolver; it does not use metadata fields for lookup.
|
||||
|
||||
3. **Backward compatibility**: **Hard cutover.** The old `CreateRunRequest` (workflow_path/dot_source) is removed when the manifest lands. CLI and local server are the same binary, so they upgrade together. Remote servers need coordinated upgrade.
|
||||
|
||||
4. **DOT parser for discovery**: **Full parse.** The CLI uses the existing `fabro-workflow` parser (already a dependency). It's fast, handles all edge cases (quoted strings, comments, escapes), and is more reliable than regex scanning.
|
||||
|
||||
5. **No manifest `env` layer**: the current CLI does not have a separate run-settings env layer like `FABRO_MODEL` or `FABRO_PROVIDER`. Manifest config precedence is `args` > workflow config > project config > user config > server defaults, with server-owned operational settings stripped from uploaded configs.
|
||||
|
|
@ -1,984 +0,0 @@
|
|||
# Server-Canonical Secrets, Doctor, and Repo Init
|
||||
|
||||
## Summary
|
||||
|
||||
Migrate five CLI command families from local-only to server-canonical:
|
||||
|
||||
- **secrets** — move from `~/.fabro/.env` to server-owned JSON store with write-only API
|
||||
- **provider login** — keep validation in CLI, save credentials via server API
|
||||
- **repo init** — call server to verify repo access after scaffolding
|
||||
- **doctor** — replace local probing with a single server diagnostics endpoint
|
||||
- **health** — add server version to `GET /health` for CLI/server parity checks
|
||||
|
||||
After this pass, the CLI has no direct file I/O for secrets and no direct probing of external services for health checks. The server is the single owner of credentials and the single source of diagnostic truth.
|
||||
|
||||
This plan deliberately excludes the run manifest (server-canonical `POST /runs` body). That is a separate, larger effort.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
In scope:
|
||||
- add `version` to `GET /health`
|
||||
- server-side secret store (JSON file, in-memory cache, store-backed secret accessors)
|
||||
- `PUT /api/v1/secrets/{name}`, `DELETE /api/v1/secrets/{name}`, `GET /api/v1/secrets`
|
||||
- rewrite `fabro secret set`, `fabro secret list`, `fabro secret rm` as API clients
|
||||
- remove `fabro secret get` (secrets are write-only)
|
||||
- rewrite `fabro provider login` to save credentials via the server
|
||||
- update `fabro install` to save GitHub App secrets via the local server and print restart guidance when needed
|
||||
- `GET /api/v1/repos/github/{owner}/{name}` for repo access checks
|
||||
- update `fabro repo init` to call repo endpoint
|
||||
- `POST /api/v1/health/diagnostics` with server-side health probing
|
||||
- rewrite `fabro doctor` as API client + version parity check + retained local config warning
|
||||
- demo mode handlers for all new endpoints
|
||||
- add shared `--server <target>` support for these server-canonical CLI commands, where `<target>` is either an HTTP(S) base URL or an absolute Unix socket path
|
||||
|
||||
Out of scope:
|
||||
- run manifest / workflow packaging
|
||||
- changes to `fabro exec` credential handling (`OPENAI_API_KEY=secret fabro exec ...` is the intended path)
|
||||
- remote server auth (mTLS, JWT) — endpoints follow existing auth patterns
|
||||
- encrypted-at-rest secret storage — JSON file with filesystem permissions is sufficient for now
|
||||
- openssl system dependency check (being removed soon)
|
||||
- broader CLI target cleanup outside the command families touched by this plan
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- Secrets are **write-only**. No endpoint exposes secret values after they are stored. `GET /api/v1/secrets` returns names and timestamps only. `fabro secret get` is removed.
|
||||
- Secret storage is a JSON file at `<data_dir>/secrets.json` under the active server data dir.
|
||||
- The server does **not** mutate process env vars on secret writes. Server-side secret consumers read through a shared store-backed adapter so updated secrets take effect immediately for request-time flows.
|
||||
- Startup-time components that only initialize once at server boot are allowed to require restart after credential changes. `fabro install` should print that restart requirement when it detects the server was already running.
|
||||
- `GET /health` gains a `version` field. The CLI checks version parity before rendering diagnostics.
|
||||
- `POST /api/v1/health/diagnostics` (not GET) because it triggers expensive external probes (LLM providers, GitHub, sandbox). The response reuses the shape of the existing `CheckReport` struct.
|
||||
- `GET /api/v1/repos/github/{owner}/{name}` is intentionally GitHub-specific in the URL. Another segment can be added for other providers later.
|
||||
- `provider login` keeps its interactive prompting and OAuth flow on the CLI side. After obtaining credentials, it saves them via `PUT /api/v1/secrets/{name}`.
|
||||
- `doctor` keeps one local CLI check for user config files and legacy `.env` warning, then requires a connected server for everything else. There is no fast/offline mode.
|
||||
- `dot` system dependency check moves server-side. `openssl` check is dropped. `node` check is dropped (build-time dependency only).
|
||||
- The `--show-values` flag on `fabro secret list` is removed as a consequence of the write-only secret model.
|
||||
- `PUT /api/v1/secrets/{name}` accepts any env-var-like key name and rejects invalid names with `400`.
|
||||
- These server-canonical CLI commands use one explicit override flag, `--server <target>`, where `<target>` is either an HTTP(S) URL or an absolute Unix socket path. When omitted, they connect to the local server for the active storage dir, starting it if necessary.
|
||||
- `[server].base_url` is replaced by `[server].target`, using the same string syntax as `--server`.
|
||||
- `fabro install` is local-only. It never targets a remote server.
|
||||
- All new endpoints have demo mode handlers.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Add version to `GET /health`
|
||||
|
||||
In `docs/api-reference/fabro-api.yaml`:
|
||||
- add `version` field to `HealthResponse` schema:
|
||||
```yaml
|
||||
HealthResponse:
|
||||
description: Service health check response.
|
||||
type: object
|
||||
required:
|
||||
- status
|
||||
- version
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
description: Health status indicator.
|
||||
example: ok
|
||||
version:
|
||||
type: string
|
||||
description: Server version string.
|
||||
example: "0.176.2"
|
||||
```
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
- update the `health` handler to include the version:
|
||||
```rust
|
||||
async fn health() -> Response {
|
||||
Json(serde_json::json!({
|
||||
"status": "ok",
|
||||
"version": fabro_util::version::FABRO_VERSION,
|
||||
}))
|
||||
.into_response()
|
||||
}
|
||||
```
|
||||
|
||||
Rebuild `fabro-api` to pick up the schema change:
|
||||
```
|
||||
cargo build -p fabro-api
|
||||
```
|
||||
|
||||
Add a test in `server.rs` inline tests:
|
||||
- send `GET /health`, assert status 200, assert `version` field is a non-empty string, assert `status` is `"ok"`.
|
||||
|
||||
### 2. Server-side secret store
|
||||
|
||||
Create `lib/crates/fabro-server/src/secret_store.rs`.
|
||||
|
||||
This module owns a JSON file and an in-memory cache:
|
||||
|
||||
```rust
|
||||
pub struct SecretEntry {
|
||||
pub value: String,
|
||||
pub created_at: String, // ISO 8601
|
||||
pub updated_at: String, // ISO 8601
|
||||
}
|
||||
|
||||
pub struct SecretMetadata {
|
||||
pub name: String,
|
||||
pub created_at: String,
|
||||
pub updated_at: String,
|
||||
}
|
||||
|
||||
pub struct SecretStore {
|
||||
path: PathBuf,
|
||||
entries: HashMap<String, SecretEntry>,
|
||||
}
|
||||
```
|
||||
|
||||
Public API:
|
||||
- `SecretStore::load(path: PathBuf) -> Result<Self>` — reads JSON file (or creates empty if missing), parses into `entries`.
|
||||
- `store.set(name: &str, value: &str) -> Result<SecretMetadata>` — validates the key name, upserts entry with current timestamp, writes atomically (write to temp file, rename to `secrets.json`), returns metadata.
|
||||
- `store.remove(name: &str) -> Result<()>` — validates the key name, removes entry (error if not found), writes atomically (write to temp file, rename).
|
||||
- `store.list() -> Vec<SecretMetadata>` — returns names + timestamps, sorted by name. No values.
|
||||
- `store.get(name: &str) -> Option<&str>` — reads a single secret value for server-side consumers.
|
||||
- `store.snapshot() -> HashMap<String, String>` — clones the current key/value map for request-time consumers that need a full view.
|
||||
- `SecretStore::validate_name(name: &str) -> Result<()>` — accept only env-var-like keys (`[A-Za-z_][A-Za-z0-9_]*`).
|
||||
|
||||
The JSON file format:
|
||||
```json
|
||||
{
|
||||
"ANTHROPIC_API_KEY": {
|
||||
"value": "sk-ant-...",
|
||||
"created_at": "2026-04-05T10:30:00Z",
|
||||
"updated_at": "2026-04-05T10:30:00Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
File permissions: `0o600` on Unix (same as current `.env`).
|
||||
|
||||
Inline tests in `secret_store.rs`:
|
||||
- `load` from empty/missing file returns empty store
|
||||
- `set` creates entry, verify file written
|
||||
- `set` existing key updates `updated_at`, preserves `created_at`
|
||||
- `remove` deletes entry, verify file written
|
||||
- `remove` missing key returns error
|
||||
- `list` returns sorted metadata without values
|
||||
- invalid names are rejected
|
||||
- use `tempdir` for file paths in tests
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
- add `pub secret_store: tokio::sync::RwLock<SecretStore>` to `AppState`
|
||||
- update `build_app_state` to derive `secrets.json` from the active server data dir and call `SecretStore::load(path)?`
|
||||
- update `create_app_state` (test helper) to use a temp path
|
||||
|
||||
In `lib/crates/fabro-server/src/lib.rs`:
|
||||
- add `pub mod secret_store;`
|
||||
|
||||
Also in the server layer:
|
||||
- add small store-backed adapters for the server-side secret consumers touched by this plan instead of continuing to call `std::env::var(...)` / `from_env()`
|
||||
- the adapters only need to cover the flows touched by this plan:
|
||||
- LLM client construction for diagnostics/model probing
|
||||
- GitHub App credentials for repo checks
|
||||
- GitHub client secret and session secret reads in web auth
|
||||
- diagnostics secret presence/probe checks
|
||||
- request-time server flows should read from the current `SecretStore` snapshot so new credentials take effect immediately
|
||||
- startup-time flows may continue to require restart if they only read credentials during boot
|
||||
|
||||
### 3. Secret CRUD API endpoints
|
||||
|
||||
In `docs/api-reference/fabro-api.yaml`:
|
||||
- add schemas:
|
||||
```yaml
|
||||
SetSecretRequest:
|
||||
description: Request to store a secret value.
|
||||
type: object
|
||||
required:
|
||||
- value
|
||||
properties:
|
||||
value:
|
||||
type: string
|
||||
description: The secret value to store.
|
||||
|
||||
SecretMetadata:
|
||||
description: Metadata for a stored secret (value is never exposed).
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- created_at
|
||||
- updated_at
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
description: Secret key name.
|
||||
example: ANTHROPIC_API_KEY
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: When the secret was first stored.
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: When the secret was last updated.
|
||||
|
||||
SecretListResponse:
|
||||
description: List of stored secret metadata.
|
||||
type: object
|
||||
required:
|
||||
- data
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/SecretMetadata"
|
||||
```
|
||||
|
||||
- add paths:
|
||||
```yaml
|
||||
/api/v1/secrets:
|
||||
get:
|
||||
operationId: listSecrets
|
||||
tags: [Secrets]
|
||||
summary: List stored secrets (names and timestamps only).
|
||||
responses:
|
||||
"200":
|
||||
description: Secret metadata list.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SecretListResponse"
|
||||
|
||||
/api/v1/secrets/{name}:
|
||||
put:
|
||||
operationId: setSecret
|
||||
tags: [Secrets]
|
||||
summary: Store or update a secret.
|
||||
parameters:
|
||||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SetSecretRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: Secret stored.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/SecretMetadata"
|
||||
"400":
|
||||
description: Invalid secret name or request body.
|
||||
delete:
|
||||
operationId: deleteSecret
|
||||
tags: [Secrets]
|
||||
summary: Delete a stored secret.
|
||||
parameters:
|
||||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"204":
|
||||
description: Secret deleted.
|
||||
"400":
|
||||
description: Invalid secret name.
|
||||
"404":
|
||||
description: Secret not found.
|
||||
"500":
|
||||
description: Secret store write failed.
|
||||
```
|
||||
|
||||
Rebuild `fabro-api`:
|
||||
```
|
||||
cargo build -p fabro-api
|
||||
```
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
- add handlers:
|
||||
|
||||
```rust
|
||||
async fn list_secrets(
|
||||
_auth: AuthenticatedService,
|
||||
State(state): State<Arc<AppState>>,
|
||||
) -> Response {
|
||||
let store = state.secret_store.read().await;
|
||||
let data = store.list();
|
||||
(StatusCode::OK, Json(serde_json::json!({ "data": data }))).into_response()
|
||||
}
|
||||
|
||||
async fn set_secret(
|
||||
_auth: AuthenticatedService,
|
||||
State(state): State<Arc<AppState>>,
|
||||
Path(name): Path<String>,
|
||||
Json(body): Json<types::SetSecretRequest>,
|
||||
) -> Response {
|
||||
let mut store = state.secret_store.write().await;
|
||||
match store.set(&name, &body.value) {
|
||||
Ok(meta) => (StatusCode::OK, Json(meta)).into_response(),
|
||||
Err(SecretStoreError::InvalidName(_)) => {
|
||||
ApiError::new(StatusCode::BAD_REQUEST, "invalid secret name").into_response()
|
||||
}
|
||||
Err(e) => ApiError::new(StatusCode::INTERNAL_SERVER_ERROR, e).into_response(),
|
||||
}
|
||||
}
|
||||
|
||||
async fn delete_secret(
|
||||
_auth: AuthenticatedService,
|
||||
State(state): State<Arc<AppState>>,
|
||||
Path(name): Path<String>,
|
||||
) -> Response {
|
||||
let mut store = state.secret_store.write().await;
|
||||
match store.remove(&name) {
|
||||
Ok(()) => StatusCode::NO_CONTENT.into_response(),
|
||||
Err(SecretStoreError::InvalidName(_)) => StatusCode::BAD_REQUEST.into_response(),
|
||||
Err(SecretStoreError::NotFound(_)) => StatusCode::NOT_FOUND.into_response(),
|
||||
Err(_) => StatusCode::INTERNAL_SERVER_ERROR.into_response(),
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
- update the `axum::routing` import to include `put` and `delete`
|
||||
- ensure request-body logging/redaction treats `PUT /secrets/{name}` values as sensitive and never logs the raw secret
|
||||
- add routes in `real_routes()`:
|
||||
```rust
|
||||
.route("/secrets", get(list_secrets))
|
||||
.route("/secrets/{name}", put(set_secret).delete(delete_secret))
|
||||
```
|
||||
|
||||
- add routes in `demo_routes()` pointing to demo handlers (see §10).
|
||||
|
||||
Tests in `server.rs` inline tests:
|
||||
- `PUT /secrets/TEST_KEY` with `{"value": "test-val"}` → 200, response has `name`, `created_at`, `updated_at`
|
||||
- `GET /secrets` → 200, `data` array contains the key just set, no `value` field present
|
||||
- `PUT` same key again → 200, `updated_at` changes
|
||||
- `PUT /secrets/NOT-VALID` → 400
|
||||
- `DELETE /secrets/TEST_KEY` → 204
|
||||
- `DELETE /secrets/NONEXISTENT` → 404
|
||||
- `GET /secrets` after delete → empty `data`
|
||||
|
||||
### 4. Rewrite `fabro secret` CLI commands as API clients
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/secret/mod.rs`:
|
||||
- remove `SecretCommand::Get` variant
|
||||
- make `execute` async (it currently dispatches to sync functions)
|
||||
- each subcommand uses the shared explicit server-target helper, then the generated `fabro_api::Client`
|
||||
|
||||
In `lib/crates/fabro-cli/src/args.rs`:
|
||||
- add `ServerTargetArgs`:
|
||||
```rust
|
||||
#[derive(Args, Debug, Clone, Default)]
|
||||
pub(crate) struct ServerTargetArgs {
|
||||
/// Fabro server target: http(s) URL or absolute Unix socket path
|
||||
#[arg(long = "server", env = "FABRO_SERVER")]
|
||||
pub(crate) target: Option<String>,
|
||||
}
|
||||
```
|
||||
- flatten `ServerTargetArgs` into:
|
||||
- `SecretNamespace`
|
||||
- `ProviderLoginArgs`
|
||||
- `DoctorArgs` (convert the inline `Doctor { ... }` variant to a named args struct)
|
||||
- `RepoInitArgs` (convert the inline `RepoCommand::Init { ... }` variant to a named args struct)
|
||||
- do **not** add `ServerTargetArgs` to `InstallArgs`; `install` stays local-only
|
||||
|
||||
In `lib/crates/fabro-cli/src/user_config.rs`:
|
||||
- replace `[server].base_url` support with `[server].target`
|
||||
- add a shared parser/resolver for explicit server targets used by these command families:
|
||||
- `http://...` or `https://...` => remote HTTP target
|
||||
- absolute path => Unix socket target
|
||||
- anything else => clear parse error
|
||||
- when `ServerTargetArgs` is absent, fall back to the local storage-dir/default-storage-dir server and auto-start it if necessary
|
||||
- use this helper from `secret`, `provider login`, `repo init`, and `doctor`
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/secret/set.rs`:
|
||||
- replace the body with:
|
||||
```rust
|
||||
pub(super) async fn set_command(
|
||||
args: &SecretSetArgs,
|
||||
server: &ServerTargetArgs,
|
||||
globals: &GlobalArgs,
|
||||
) -> Result<()> {
|
||||
let client = secret_client(server).await?;
|
||||
let meta = client.set_secret()
|
||||
.name(&args.key)
|
||||
.body(types::SetSecretRequest { value: args.value.clone() })
|
||||
.send()
|
||||
.await?;
|
||||
if globals.json {
|
||||
print_json_pretty(&meta)?;
|
||||
} else {
|
||||
eprintln!("Set {}", args.key);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/secret/list.rs`:
|
||||
- remove `--show-values` flag from `SecretListArgs`
|
||||
- replace the body with:
|
||||
```rust
|
||||
pub(super) async fn list_command(
|
||||
args: &SecretListArgs,
|
||||
server: &ServerTargetArgs,
|
||||
globals: &GlobalArgs,
|
||||
) -> Result<()> {
|
||||
let client = secret_client(server).await?;
|
||||
let resp = client.list_secrets().send().await?;
|
||||
if globals.json {
|
||||
print_json_pretty(&resp.data)?;
|
||||
} else {
|
||||
for secret in &resp.data {
|
||||
println!("{}\t{}", secret.name, secret.updated_at);
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/secret/rm.rs`:
|
||||
- replace the body with:
|
||||
```rust
|
||||
pub(super) async fn rm_command(
|
||||
args: &SecretRmArgs,
|
||||
server: &ServerTargetArgs,
|
||||
globals: &GlobalArgs,
|
||||
) -> Result<()> {
|
||||
let client = secret_client(server).await?;
|
||||
client.delete_secret().name(&args.key).send().await?;
|
||||
if globals.json {
|
||||
print_json_pretty(&serde_json::json!({ "key": args.key }))?;
|
||||
} else {
|
||||
eprintln!("Removed {}", args.key);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
Delete `lib/crates/fabro-cli/src/commands/secret/get.rs`.
|
||||
|
||||
In `lib/crates/fabro-cli/src/args.rs`:
|
||||
- remove `SecretCommand::Get` and `SecretGetArgs`
|
||||
|
||||
Update any integration tests that test `fabro secret get` — remove them.
|
||||
|
||||
### 5. Rewrite `fabro provider login` to save via server
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/provider/login.rs`:
|
||||
- after obtaining validated `env_pairs` (the `Vec<(String, String)>` of env var name → key value), replace the `provider_auth::write_env_file(...)` call with API calls:
|
||||
```rust
|
||||
let client = provider_secret_client(&args.server).await?;
|
||||
for (env_var, key) in &env_pairs {
|
||||
client.set_secret()
|
||||
.name(env_var)
|
||||
.body(types::SetSecretRequest { value: key.clone() })
|
||||
.send()
|
||||
.await
|
||||
.with_context(|| format!("failed to save {env_var} to server"))?;
|
||||
}
|
||||
```
|
||||
- remove the `provider_auth::write_env_file` call
|
||||
- add a temporary warning if a legacy `.env` file exists under the active local storage dir:
|
||||
```
|
||||
Warning: ~/.fabro/.env is no longer read by fabro server. Re-enter credentials with `fabro provider login` or `fabro secret set`.
|
||||
```
|
||||
|
||||
In `lib/crates/fabro-cli/src/shared/provider_auth.rs`:
|
||||
- `write_env_file` may become dead code after this change. If no other callers exist, delete it.
|
||||
- `validate_api_key` currently calls `std::env::set_var` temporarily to validate. This still works because validation happens before saving. However, consider whether the validation should instead construct the LLM client explicitly with the key rather than mutating process env. This is a follow-up concern — for now the existing validation approach is fine since the CLI process is single-threaded for this flow.
|
||||
|
||||
### 5a. Update `fabro install` to save GitHub App secrets via the local server
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/install.rs`:
|
||||
- keep `install` local-only. It should always operate on the local server for the active storage dir and never accept `--server`
|
||||
- after writing `server.toml` / `user.toml` and producing GitHub App secret env pairs, persist those secret values via the local server's `PUT /secrets/{name}` API instead of writing `.env`
|
||||
- detect whether the local server was already running before `install`
|
||||
- if the server was not running, letting the local client auto-start it is fine
|
||||
- if the server was already running, print a clear restart warning after saving secrets:
|
||||
```
|
||||
Fabro server was already running. Restart it to pick up startup-time credential changes (for example webhook listener configuration).
|
||||
```
|
||||
- remove the `.env` reload
|
||||
- update the final doctor invocation to the new signature / args shape
|
||||
|
||||
This is intentionally a hard break from `.env`, but `install` should print a temporary migration warning if it sees a legacy `.env` file in the local storage dir.
|
||||
|
||||
### 6. `GET /api/v1/repos/github/{owner}/{name}` endpoint
|
||||
|
||||
In `docs/api-reference/fabro-api.yaml`:
|
||||
- add schema:
|
||||
```yaml
|
||||
RepoCheckResponse:
|
||||
description: Repository access check result.
|
||||
type: object
|
||||
required:
|
||||
- owner
|
||||
- name
|
||||
- accessible
|
||||
properties:
|
||||
owner:
|
||||
type: string
|
||||
description: GitHub repository owner.
|
||||
example: acme-corp
|
||||
name:
|
||||
type: string
|
||||
description: GitHub repository name.
|
||||
example: my-app
|
||||
accessible:
|
||||
type: boolean
|
||||
description: Whether the server has read-write access to this repository.
|
||||
default_branch:
|
||||
type: string
|
||||
nullable: true
|
||||
description: Default branch name, if accessible.
|
||||
example: main
|
||||
private:
|
||||
type: boolean
|
||||
nullable: true
|
||||
description: Whether the repository is private, if accessible.
|
||||
permissions:
|
||||
type: object
|
||||
nullable: true
|
||||
description: Detected permission levels.
|
||||
properties:
|
||||
pull:
|
||||
type: boolean
|
||||
push:
|
||||
type: boolean
|
||||
admin:
|
||||
type: boolean
|
||||
install_url:
|
||||
type: string
|
||||
nullable: true
|
||||
description: GitHub App installation URL when the repo is not yet accessible.
|
||||
```
|
||||
|
||||
- add path:
|
||||
```yaml
|
||||
/api/v1/repos/github/{owner}/{name}:
|
||||
get:
|
||||
operationId: getGithubRepo
|
||||
tags: [Repos]
|
||||
summary: Check server access to a GitHub repository.
|
||||
parameters:
|
||||
- name: owner
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
- name: name
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: Repository access details.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/RepoCheckResponse"
|
||||
```
|
||||
|
||||
Rebuild `fabro-api`:
|
||||
```
|
||||
cargo build -p fabro-api
|
||||
```
|
||||
|
||||
In `lib/crates/fabro-server/Cargo.toml`:
|
||||
- add `fabro-github` as a dependency if not already present
|
||||
|
||||
In `lib/crates/fabro-server/src/server.rs`:
|
||||
- add handler:
|
||||
```rust
|
||||
async fn get_github_repo(
|
||||
_auth: AuthenticatedService,
|
||||
State(state): State<Arc<AppState>>,
|
||||
Path((owner, name)): Path<(String, String)>,
|
||||
) -> Response
|
||||
```
|
||||
The handler:
|
||||
1. Reads non-secret GitHub App config (`app_id`, `slug`) from `Settings`. Reads `GITHUB_APP_PRIVATE_KEY` from `SecretStore`.
|
||||
2. Signs a JWT via `fabro_github::sign_app_jwt`.
|
||||
3. Calls `GET /repos/{owner}/{name}/installation` to check if the App is installed.
|
||||
4. If installed, mints an installation token and calls `GET /repos/{owner}/{name}` to get repo details (default branch, private flag, permissions).
|
||||
5. If not installed, returns `accessible: false` with null optional fields and, when possible, an `install_url`.
|
||||
6. Returns `RepoCheckResponse`.
|
||||
|
||||
If GitHub App credentials are not configured (missing from settings or secret store), return `accessible: false` with a descriptive error or a 503.
|
||||
|
||||
- add route in `real_routes()`:
|
||||
```rust
|
||||
.route("/repos/github/{owner}/{name}", get(get_github_repo))
|
||||
```
|
||||
- add route in `demo_routes()` pointing to demo handler (see §10).
|
||||
|
||||
Tests:
|
||||
- Testing the real handler requires mocking the GitHub API or the `HttpClient` trait. Use a unit test that exercises the response shape with a mock `AppState` that has a test GitHub client, or test at the integration level with the demo handler.
|
||||
- At minimum, test the demo handler returns 200 with the expected shape.
|
||||
|
||||
### 7. Update `fabro repo init` to call repo endpoint
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/repo/init.rs`:
|
||||
- replace `check_github_app_installation()` with a server call:
|
||||
```rust
|
||||
async fn check_repo_access(owner: &str, name: &str, args: &RepoInitArgs) -> Result<()> {
|
||||
let client = repo_client(&args.server).await?;
|
||||
let resp = client.get_github_repo()
|
||||
.owner(owner)
|
||||
.name(name)
|
||||
.send()
|
||||
.await?;
|
||||
if resp.accessible {
|
||||
println!(" {} GitHub repo {}/{} is accessible", green_check, owner, name);
|
||||
if let Some(branch) = &resp.default_branch {
|
||||
println!(" Default branch: {branch}");
|
||||
}
|
||||
} else {
|
||||
println!(" {} GitHub repo {}/{} is not accessible", yellow_warn, owner, name);
|
||||
println!(" Install the GitHub App to enable PR creation and webhook triggers.");
|
||||
if let Some(url) = &resp.install_url {
|
||||
println!(" Install at: {url}");
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
- The function still parses the git remote to extract `owner`/`name` — that stays CLI-side since it reads the local git config.
|
||||
- Remove the direct `fabro_github::sign_app_jwt`, `fabro_github::check_app_installed`, `build_github_app_credentials` calls.
|
||||
- Keep the `fabro-github` dependency in `fabro-cli/Cargo.toml` — it has many other callers (pr/*, preflight.rs, shared/github.rs).
|
||||
- preserve the current interactive UX:
|
||||
- when the repo is not yet accessible and stdin is a terminal, print the install URL, wait for Enter, then call the repo endpoint again
|
||||
- print the second check result after the re-check
|
||||
|
||||
### 8. `POST /api/v1/health/diagnostics` endpoint
|
||||
|
||||
In `docs/api-reference/fabro-api.yaml`:
|
||||
- add schemas:
|
||||
```yaml
|
||||
DiagnosticsReport:
|
||||
description: Server health diagnostics report.
|
||||
type: object
|
||||
required:
|
||||
- version
|
||||
- sections
|
||||
properties:
|
||||
version:
|
||||
type: string
|
||||
description: Server version.
|
||||
sections:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/DiagnosticsSection"
|
||||
|
||||
DiagnosticsSection:
|
||||
type: object
|
||||
required:
|
||||
- title
|
||||
- checks
|
||||
properties:
|
||||
title:
|
||||
type: string
|
||||
checks:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/DiagnosticsCheck"
|
||||
|
||||
DiagnosticsCheck:
|
||||
type: object
|
||||
required:
|
||||
- name
|
||||
- status
|
||||
- summary
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
status:
|
||||
type: string
|
||||
enum:
|
||||
- pass
|
||||
- warning
|
||||
- error
|
||||
summary:
|
||||
type: string
|
||||
details:
|
||||
type: array
|
||||
items:
|
||||
$ref: "#/components/schemas/DiagnosticsDetail"
|
||||
remediation:
|
||||
type: string
|
||||
nullable: true
|
||||
|
||||
DiagnosticsDetail:
|
||||
type: object
|
||||
required:
|
||||
- text
|
||||
- warn
|
||||
properties:
|
||||
text:
|
||||
type: string
|
||||
warn:
|
||||
type: boolean
|
||||
```
|
||||
|
||||
- add path:
|
||||
```yaml
|
||||
/api/v1/health/diagnostics:
|
||||
post:
|
||||
operationId: runDiagnostics
|
||||
tags: [Discovery]
|
||||
summary: Run server health diagnostics.
|
||||
description: Probes external services (LLM providers, GitHub, sandbox) and checks server configuration. May be slow.
|
||||
responses:
|
||||
"200":
|
||||
description: Diagnostics report.
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/DiagnosticsReport"
|
||||
```
|
||||
|
||||
Rebuild `fabro-api`:
|
||||
```
|
||||
cargo build -p fabro-api
|
||||
```
|
||||
|
||||
Create `lib/crates/fabro-server/src/diagnostics.rs`.
|
||||
|
||||
This module contains the server-side check functions. Many can be adapted from the existing `doctor.rs` in `fabro-cli`. The key checks, grouped into sections:
|
||||
|
||||
**Section "Credentials":**
|
||||
- `check_llm_providers` — for each provider in `Provider::ALL`, check if a secret exists in the store and probe connectivity by sending a test message.
|
||||
- `check_github_app` — check that `GITHUB_APP_ID`, `GITHUB_APP_PRIVATE_KEY`, etc. exist in settings/store, validate JWT signing, and probe `GET /app` on GitHub API.
|
||||
- `check_sandbox` — check `DAYTONA_API_KEY` exists. Probe Daytona API.
|
||||
- `check_brave_search` — check `BRAVE_SEARCH_API_KEY` exists. Probe Brave API.
|
||||
|
||||
**Section "System":**
|
||||
- `check_system_dep_dot` — check `dot` is in PATH and version ≥ 2.0.0.
|
||||
|
||||
**Section "Configuration":**
|
||||
- `check_crypto` — validate mTLS certs/keys, JWT keys, session secret (same checks as current doctor).
|
||||
|
||||
Dropped from diagnostics (compared to current doctor):
|
||||
- `check_api` / `check_web` — the CLI's ability to call the diagnostics endpoint is itself the connectivity check. No circular self-check.
|
||||
- `check_system_dep_node` — node is a build-time dependency only, not needed at server runtime.
|
||||
- `check_system_dep_openssl` — being removed soon.
|
||||
|
||||
The handler:
|
||||
|
||||
```rust
|
||||
async fn run_diagnostics(
|
||||
_auth: AuthenticatedService,
|
||||
State(state): State<Arc<AppState>>,
|
||||
) -> Response {
|
||||
let report = diagnostics::run_all(&state).await;
|
||||
(StatusCode::OK, Json(report)).into_response()
|
||||
}
|
||||
```
|
||||
|
||||
`diagnostics::run_all` runs all checks concurrently (where possible) and returns a `DiagnosticsReport`. The probes (LLM, GitHub, Daytona, Brave) should be run concurrently via `tokio::join!` or `futures::join!`.
|
||||
- apply explicit timeouts to the live probes so `doctor` cannot hang indefinitely
|
||||
- keep concurrency bounded to this fixed set of checks; do not allow unbounded fan-out
|
||||
|
||||
Each check function returns a `DiagnosticsCheck` struct that maps 1:1 to the API schema. The existing `CheckResult` from `fabro_util::check_report` is very close — consider either:
|
||||
- reusing `CheckResult` directly and serializing it (it already has `Serialize`)
|
||||
- or mapping to the generated `fabro_api` types
|
||||
|
||||
For the wire contract, prefer an explicit conversion step rather than assuming `CheckResult` serialization is automatically stable enough for the API surface.
|
||||
|
||||
Add route in `real_routes()`:
|
||||
```rust
|
||||
.route("/health/diagnostics", post(run_diagnostics))
|
||||
```
|
||||
|
||||
Add route in `demo_routes()` pointing to demo handler (see §10).
|
||||
|
||||
Tests:
|
||||
- test that `POST /health/diagnostics` returns 200 with a `version` field and a non-empty `sections` array
|
||||
- test that each section has a `title` and `checks` array
|
||||
- test the demo handler returns the same shape
|
||||
|
||||
### 9. Rewrite `fabro doctor` as API client
|
||||
|
||||
In `lib/crates/fabro-cli/src/commands/doctor.rs`:
|
||||
- replace `run_doctor` with a thin client:
|
||||
```rust
|
||||
pub async fn run_doctor(args: &DoctorArgs, globals: &GlobalArgs) -> Result<()> {
|
||||
let client = doctor_client(&args.server).await?;
|
||||
|
||||
// Local config warning block
|
||||
let local_checks = render_local_config_checks()?;
|
||||
|
||||
// Version parity check
|
||||
let health = client.get_health().send().await?;
|
||||
let server_version = &health.version;
|
||||
let cli_version = fabro_util::version::FABRO_VERSION;
|
||||
|
||||
// Run diagnostics
|
||||
let report = client.run_diagnostics().send().await?;
|
||||
|
||||
if globals.json {
|
||||
print_json_pretty(&report)?;
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// Version parity
|
||||
if server_version != cli_version {
|
||||
eprintln!(
|
||||
"⚠ Version mismatch: CLI={cli_version} Server={server_version}"
|
||||
);
|
||||
}
|
||||
|
||||
// Render the retained local config warnings first, then the server diagnostics report.
|
||||
render_local_checks(&local_checks);
|
||||
render_diagnostics(&report);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
- the rendering logic from `CheckReport::render()` can be reused. Either:
|
||||
- convert the API response into a `CheckReport` and call `render()`
|
||||
- or extract the rendering logic into a function that takes the diagnostics fields directly
|
||||
- remove the local dry-run / offline mode flag
|
||||
- keep the local user-config and legacy `.env` checks
|
||||
- remove the other local check functions (`check_llm_providers`, `check_github_app`, `check_sandbox`, `check_brave_search`, `check_system_deps`, `check_api`, `check_web`, `check_crypto`)
|
||||
- remove the corresponding test functions if they only tested the removed local checks
|
||||
- keep the `CheckReport`/`CheckResult` rendering code in `fabro_util::check_report` — it is still useful for rendering the server's response
|
||||
|
||||
If the server client connection fails (server unreachable), the error message should be clear:
|
||||
```
|
||||
Error: could not connect to fabro server. Run `fabro server start` or check `fabro server status`.
|
||||
```
|
||||
|
||||
Also:
|
||||
- if a legacy local `.env` file exists, print a temporary warning that the server no longer reads it
|
||||
- `doctor` should still succeed in rendering that local warning even when the diagnostics call later fails
|
||||
|
||||
### 10. Demo mode handlers
|
||||
|
||||
In `lib/crates/fabro-server/src/demo/mod.rs`:
|
||||
|
||||
**Secrets demo:**
|
||||
- maintain a static in-memory `HashMap` with pre-populated fake secrets:
|
||||
```rust
|
||||
pub(crate) async fn list_secrets(...) -> Response {
|
||||
let data = vec![
|
||||
serde_json::json!({
|
||||
"name": "ANTHROPIC_API_KEY",
|
||||
"created_at": "2026-01-15T09:00:00Z",
|
||||
"updated_at": "2026-03-20T14:30:00Z",
|
||||
}),
|
||||
serde_json::json!({
|
||||
"name": "OPENAI_API_KEY",
|
||||
"created_at": "2026-01-15T09:05:00Z",
|
||||
"updated_at": "2026-02-10T11:00:00Z",
|
||||
}),
|
||||
serde_json::json!({
|
||||
"name": "GITHUB_APP_PRIVATE_KEY",
|
||||
"created_at": "2026-01-15T09:10:00Z",
|
||||
"updated_at": "2026-01-15T09:10:00Z",
|
||||
}),
|
||||
];
|
||||
(StatusCode::OK, Json(serde_json::json!({ "data": data }))).into_response()
|
||||
}
|
||||
|
||||
pub(crate) async fn set_secret(...) -> Response {
|
||||
// return fake metadata with current timestamps
|
||||
}
|
||||
|
||||
pub(crate) async fn delete_secret(...) -> Response {
|
||||
StatusCode::NO_CONTENT.into_response()
|
||||
}
|
||||
```
|
||||
|
||||
**Repo demo:**
|
||||
- return a fake accessible repo:
|
||||
```rust
|
||||
pub(crate) async fn get_github_repo(
|
||||
...,
|
||||
Path((owner, name)): Path<(String, String)>,
|
||||
) -> Response {
|
||||
(StatusCode::OK, Json(serde_json::json!({
|
||||
"owner": owner,
|
||||
"name": name,
|
||||
"accessible": true,
|
||||
"default_branch": "main",
|
||||
"private": false,
|
||||
"permissions": { "pull": true, "push": true, "admin": false },
|
||||
}))).into_response()
|
||||
}
|
||||
```
|
||||
|
||||
**Diagnostics demo:**
|
||||
- return an all-passing report:
|
||||
```rust
|
||||
pub(crate) async fn run_diagnostics(...) -> Response {
|
||||
(StatusCode::OK, Json(serde_json::json!({
|
||||
"version": fabro_util::version::FABRO_VERSION,
|
||||
"sections": [
|
||||
{
|
||||
"title": "Credentials",
|
||||
"checks": [
|
||||
{ "name": "LLM Providers", "status": "pass", "summary": "Anthropic, OpenAI configured", "details": [], "remediation": null },
|
||||
{ "name": "GitHub App", "status": "pass", "summary": "JWT signing OK", "details": [], "remediation": null },
|
||||
{ "name": "Sandbox", "status": "pass", "summary": "Daytona reachable", "details": [], "remediation": null },
|
||||
{ "name": "Brave Search", "status": "pass", "summary": "API key configured", "details": [], "remediation": null },
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "System",
|
||||
"checks": [
|
||||
{ "name": "dot", "status": "pass", "summary": "dot 12.1.2", "details": [], "remediation": null },
|
||||
]
|
||||
},
|
||||
{
|
||||
"title": "Configuration",
|
||||
"checks": [
|
||||
{ "name": "Crypto", "status": "pass", "summary": "All keys valid", "details": [], "remediation": null },
|
||||
]
|
||||
},
|
||||
]
|
||||
}))).into_response()
|
||||
}
|
||||
```
|
||||
|
||||
Wire all demo handlers in `demo_routes()`:
|
||||
```rust
|
||||
.route("/secrets", get(demo::list_secrets))
|
||||
.route("/secrets/{name}", put(demo::set_secret).delete(demo::delete_secret))
|
||||
.route("/repos/github/{owner}/{name}", get(demo::get_github_repo))
|
||||
.route("/health/diagnostics", post(demo::run_diagnostics))
|
||||
```
|
||||
|
||||
## Implementation Order
|
||||
|
||||
```
|
||||
1 Health version (no deps, small)
|
||||
2 Secret store + adapters (no deps)
|
||||
3 Secret CRUD API (depends on 2)
|
||||
4 Shared server target plumbing (parallel with 2-3)
|
||||
5 Secret CLI migration (depends on 3, 4)
|
||||
6 Provider login migration (depends on 3, 4)
|
||||
7 Install migration (depends on 3)
|
||||
8 Repo check API (depends on 2)
|
||||
9 Repo init migration (depends on 4, 8)
|
||||
10 Diagnostics API (depends on 2)
|
||||
11 Doctor CLI migration (depends on 1, 4, 10)
|
||||
```
|
||||
|
||||
Steps 1, 2, and 4 can start in parallel. Steps 5 and 6 can run in parallel once 3 and 4 are done.
|
||||
|
||||
## Resolved Questions
|
||||
|
||||
1. **Secret store path**: `<data_dir>/secrets.json` under the active server data dir. Credentials are owned by the server instance, not by a global shared file.
|
||||
|
||||
2. **Migration from existing `.env`**: no auto-import. Hard break. Users must re-enter credentials via `fabro provider login` or `fabro secret set`, and the CLI/server should emit a temporary warning when they detect a legacy `.env`.
|
||||
|
||||
3. **GitHub App credentials for repo check**: non-secret config (`app_id`, `slug`) goes in server settings (not mixed with secrets). Secret values (`GITHUB_APP_PRIVATE_KEY`) go in the secret store. The repo check handler reads `app_id`/`slug` from `Settings` and `GITHUB_APP_PRIVATE_KEY` from `SecretStore`.
|
||||
|
||||
4. **Diagnostics: `check_api` and `check_web`**: dropped. The CLI's ability to call the diagnostics endpoint *is* the API connectivity check — if the server is unreachable, the CLI gets a connection error before any diagnostics run. No circular self-check needed. The one retained local CLI check is user config / legacy `.env`.
|
||||
|
||||
5. **`node` dependency**: dropped from diagnostics. The web app is an SPA served by the Rust server; `node` is a build-time dependency only, not needed at server runtime.
|
||||
|
||||
6. **`dot` dependency**: moves server-side. `openssl` dependency: dropped (being removed soon).
|
||||
|
||||
7. **Server targeting**: server-canonical admin commands use `--server <target>` and `[server].target`, where `<target>` is either an HTTP(S) base URL or an absolute Unix socket path.
|
||||
|
||||
8. **`fabro install` targeting**: `install` is local-only and writes config plus secrets for the local server host. If the server was already running, `install` prints that a restart is required for startup-time features to pick up new secrets.
|
||||
|
|
@ -1,231 +0,0 @@
|
|||
# CLI Config, Socket, And Storage Separation
|
||||
|
||||
## Summary
|
||||
Separate machine config, server target, and server storage so the CLI no longer conflates:
|
||||
|
||||
- config path: `~/.fabro/settings.toml`
|
||||
- default socket target: `~/.fabro/fabro.sock`
|
||||
- default storage dir: `~/.fabro/storage`
|
||||
|
||||
Normal user-facing commands should always talk to a server target. A Unix socket target may auto-start the daemon. An HTTP target may not. Serverless/direct-storage command behavior should be removed from normal commands in this pass.
|
||||
|
||||
## Scope Boundaries
|
||||
In scope:
|
||||
- add `FABRO_CONFIG` support for machine settings loading
|
||||
- default the server target to `~/.fabro/fabro.sock`
|
||||
- default server storage to `~/.fabro/storage`
|
||||
- decouple socket-path resolution from storage-dir resolution
|
||||
- keep daemon auto-start only for Unix socket targets
|
||||
- remove normal-command fallback to direct storage-based targeting
|
||||
- keep `fabro server *`, hidden `fabro __runner`, and `fabro install` as storage-owning commands
|
||||
- keep user-facing `--server` on server-targeted commands
|
||||
- remove user-facing `--storage-dir` from server-targeted commands
|
||||
|
||||
Out of scope:
|
||||
- `fabro exec`
|
||||
- `fabro system df`
|
||||
- `fabro system prune`
|
||||
- `fabro store dump`
|
||||
- new remote maintenance endpoints for deferred commands
|
||||
|
||||
## Problem Frame
|
||||
The current CLI still mixes together two different ideas:
|
||||
|
||||
- a local daemon reached over a Unix socket
|
||||
- serverless behavior where the CLI uses `storage_dir` as the command target
|
||||
|
||||
That has produced the wrong defaults and the wrong abstractions:
|
||||
|
||||
- the socket path is currently derived from `storage_dir`
|
||||
- many commands still model targeting as "server or storage dir"
|
||||
- normal commands can still fall back to a storage-driven local connection shape
|
||||
- autostart is keyed off the local/storage connection path instead of the actual server target type
|
||||
|
||||
The intended model is simpler:
|
||||
|
||||
- normal commands always resolve a server target
|
||||
- the default server target is a Unix socket in `~/.fabro`
|
||||
- Unix socket targets may auto-start a daemon
|
||||
- HTTP targets may not auto-start a daemon
|
||||
- storage is server-owned runtime state, not the primary targeting mechanism for normal commands
|
||||
|
||||
## Key Decisions
|
||||
- `FABRO_CONFIG` selects the active machine settings file.
|
||||
- For server lifecycle commands and daemon auto-start, precedence is: explicit `--config` where supported, then `FABRO_CONFIG`, then `~/.fabro/settings.toml`.
|
||||
- Normal user-facing commands do not gain a new `--config` flag in this pass; they resolve settings from `FABRO_CONFIG` or the default path.
|
||||
- `FABRO_SERVER` selects the effective server target for normal commands.
|
||||
- It accepts either an absolute Unix socket path or an `http(s)` URL.
|
||||
- If unset, use `settings.server.target`.
|
||||
- If that is unset, default to `~/.fabro/fabro.sock`.
|
||||
- Server-targeted commands keep `--server` as the standard one-off override.
|
||||
- `FABRO_SERVER` remains the env-var equivalent.
|
||||
- `FABRO_STORAGE_DIR` is no longer a normal command-targeting mechanism.
|
||||
- It remains an override for storage-owning commands only.
|
||||
- Precedence for storage-owning commands: explicit `--storage-dir` where still supported, then `FABRO_STORAGE_DIR`, then `settings.storage_dir`, then `~/.fabro/storage`.
|
||||
- `settings.server.target` remains the durable place to configure the machine's server target.
|
||||
- `settings.storage_dir` remains the durable place to configure where the local server stores data.
|
||||
- `fabro server start` keeps `--config` and `--bind`.
|
||||
- Its default bind is `~/.fabro/fabro.sock`, not `<storage_dir>/fabro.sock`.
|
||||
- `fabro server stop` and `fabro server status` remain storage-owning commands and continue to resolve the local server instance from storage-owned records.
|
||||
- `fabro settings` is a local config-inspection command, not a server-targeted command.
|
||||
- It keeps its current local settings-resolution behavior in this pass.
|
||||
- `fabro exec` is unchanged in this pass.
|
||||
|
||||
## Command Classification
|
||||
### Storage-owning commands
|
||||
These commands continue to resolve and use local storage directly:
|
||||
|
||||
- `fabro server start`
|
||||
- `fabro server stop`
|
||||
- `fabro server status`
|
||||
- hidden `fabro server __serve`
|
||||
- hidden `fabro run __runner`
|
||||
- `fabro install`
|
||||
|
||||
### Local config-inspection commands
|
||||
These commands stay outside the server-targeting cleanup in this pass:
|
||||
|
||||
- `fabro settings`
|
||||
|
||||
### Server-targeted commands
|
||||
These commands should resolve a `ServerTarget` only and should not use storage-dir fallback semantics:
|
||||
|
||||
- `fabro run`
|
||||
- `fabro create`
|
||||
- `fabro preflight`
|
||||
- `fabro validate`
|
||||
- `fabro graph`
|
||||
- `fabro model list`
|
||||
- `fabro model test`
|
||||
- `fabro doctor`
|
||||
- `fabro repo init`
|
||||
- `fabro provider login`
|
||||
- `fabro secret list`
|
||||
- `fabro secret rm`
|
||||
- `fabro secret set`
|
||||
- `fabro ps`
|
||||
- `fabro rm`
|
||||
- `fabro inspect`
|
||||
- `fabro run start`
|
||||
- `fabro run attach`
|
||||
- `fabro run logs`
|
||||
- `fabro run resume`
|
||||
- `fabro run rewind`
|
||||
- `fabro run fork`
|
||||
- `fabro run wait`
|
||||
- hidden `fabro run diff`
|
||||
- `fabro artifact list`
|
||||
- `fabro artifact cp`
|
||||
- `fabro sandbox cp`
|
||||
- `fabro sandbox preview`
|
||||
- `fabro sandbox ssh`
|
||||
- `fabro pr create`
|
||||
- `fabro pr list`
|
||||
- `fabro pr view`
|
||||
- `fabro pr merge`
|
||||
- `fabro pr close`
|
||||
|
||||
### Deferred local-maintenance commands
|
||||
These remain unchanged in this pass:
|
||||
|
||||
- `fabro system df`
|
||||
- `fabro system prune`
|
||||
- `fabro store dump`
|
||||
|
||||
These deferred commands continue to use `StorageDirArgs` and the existing hybrid `ServerRunLookup::connect(storage_dir)` path in this pass, and should keep working against the new default storage dir without being reclassified as server-targeted commands yet.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Shared settings and path resolution
|
||||
- Add a shared helper for the active settings path used by CLI and server code.
|
||||
- This helper must honor `FABRO_CONFIG`.
|
||||
- Add a shared helper for the default socket path: `~/.fabro/fabro.sock`.
|
||||
- Change the default storage dir helper to return `~/.fabro/storage`.
|
||||
- Stop deriving the socket path from `storage_dir`.
|
||||
|
||||
### 2. Target resolution model
|
||||
- Refactor CLI target resolution so normal commands resolve a `ServerTarget`, not a "local vs target" union.
|
||||
- Remove `ServerConnection::Local` as a normal command-routing concept.
|
||||
- Split helpers into two categories:
|
||||
- server-target resolution for normal commands
|
||||
- storage-dir resolution for storage-owning commands
|
||||
- Keep TLS handling attached to `HttpUrl` targets exactly as today.
|
||||
|
||||
### 3. Connection and auto-start behavior
|
||||
- Update the server client helpers so they accept or derive a `ServerTarget`.
|
||||
- If the resolved target is `UnixSocket(path)`:
|
||||
- attempt to connect to that socket
|
||||
- if unavailable, auto-start the daemon
|
||||
- auto-start the daemon bound to that exact socket path
|
||||
- If the resolved target is `HttpUrl(url)`:
|
||||
- attempt to connect once
|
||||
- if unavailable, fail with a clean reachability error
|
||||
- do not auto-start anything
|
||||
- Auto-start must pass the active config path through to the spawned server with `--config`.
|
||||
- The auto-start helper should take the resolved active config path, resolved Unix socket path, and resolved local storage dir as explicit inputs.
|
||||
- It should not rediscover config via environment variables or reload settings internally during daemon launch.
|
||||
- Auto-start may also pass the resolved storage dir for the local server process, but only as runtime/server lifecycle plumbing, not as the command target abstraction.
|
||||
- Any active-server record lookup used by `server stop`, `server status`, `install`, or daemon auto-start should temporarily fall back to the legacy implicit storage root `~/.fabro` when no explicit storage location is provided and no record exists under the new default `~/.fabro/storage`.
|
||||
- This is only to find already-running daemons started before the default-storage change.
|
||||
|
||||
### 4. CLI arg surface cleanup
|
||||
- Keep user-facing `--server` on all server-targeted commands listed above.
|
||||
- Remove user-facing `--storage-dir` from all server-targeted commands listed above.
|
||||
- Remove the `storage_dir_explicit` conflict plumbing for those commands.
|
||||
- Remove the custom `--server` / `--storage-dir` conflict detection in `main.rs` once no supported command still accepts both flags together.
|
||||
- Keep `--storage-dir` only on storage-owning commands in this pass.
|
||||
- Keep `--config` only where already appropriate for server lifecycle.
|
||||
- Update help text and parser tests so normal commands still advertise `--server` but no longer imply that storage-dir is a general targeting control.
|
||||
|
||||
### 5. Run/create local run-dir handling
|
||||
- `run` / `create` currently thread a synthesized local run dir through the result object to print asset paths after completion.
|
||||
- Preserve that behavior only when the effective target is the machine's local Unix socket and the effective local storage dir is known.
|
||||
- For HTTP targets, do not synthesize a local run dir.
|
||||
- This should be derived from "effective target is local socket" plus resolved storage dir, not from a `ServerConnection::Local` enum variant.
|
||||
|
||||
### 6. Docs and user-visible messaging
|
||||
- Rewrite docs and examples so:
|
||||
- normal commands use config-driven target resolution by default
|
||||
- temporary overrides use `FABRO_SERVER=... fabro ...`
|
||||
- config-file overrides use `FABRO_CONFIG=... fabro ...`
|
||||
- Update language to avoid "local mode" as a user-facing concept.
|
||||
- Use "Unix socket target" or "HTTP target".
|
||||
- Use "serverless" only for the behavior being removed.
|
||||
- Make `doctor` and `settings` print:
|
||||
- active config path
|
||||
- effective server target
|
||||
- effective storage dir
|
||||
- any active env-var overrides
|
||||
|
||||
## Test Plan
|
||||
- Unit tests for path and precedence helpers:
|
||||
- active config path honors `FABRO_CONFIG`
|
||||
- default socket path is `~/.fabro/fabro.sock`
|
||||
- default storage dir is `~/.fabro/storage`
|
||||
- `FABRO_SERVER` overrides `settings.server.target`
|
||||
- `FABRO_STORAGE_DIR` overrides `settings.storage_dir` for storage-owning commands only
|
||||
- `FABRO_CONFIG=/custom/path/settings.toml` loads that file's contents and the resolved `server.target` / `storage_dir` from that file actually take effect
|
||||
- Unit tests for target resolution:
|
||||
- normal commands default to a Unix socket target when nothing is configured
|
||||
- normal commands no longer resolve a storage-dir fallback connection
|
||||
- HTTP targets never route into autostart code
|
||||
- Integration tests for daemon behavior:
|
||||
- `fabro server start` defaults to binding `~/.fabro/fabro.sock`
|
||||
- auto-start for socket-targeted commands binds the requested socket, not `<storage_dir>/fabro.sock`
|
||||
- auto-start passes the active config path through to the daemon
|
||||
- HTTP-targeted commands fail cleanly when unreachable
|
||||
- `server stop` / `server status` still find an already-running daemon whose record lives under the legacy implicit storage root
|
||||
- Parser/help tests:
|
||||
- server-targeted commands still accept `--server`
|
||||
- server-targeted commands no longer accept `--storage-dir`
|
||||
- storage-owning commands still accept `--storage-dir` where intended
|
||||
- `fabro settings` keeps its existing local settings override surface in this pass
|
||||
- Workflow behavior tests:
|
||||
- `run`, `create`, `model`, `doctor`, `ps`, and `secret` work via the default socket target
|
||||
- local Unix socket runs still print local asset/run-dir info when appropriate
|
||||
- HTTP-targeted runs do not print synthesized local run-dir paths
|
||||
|
||||
## Assumptions
|
||||
- This is a hard cut for CLI targeting semantics. No deprecation period for removed normal-command flags.
|
||||
- `FABRO_SERVER` is the single override for user-facing command targeting; no separate `FABRO_SOCKET` env var is added.
|
||||
- `server.target` remains the canonical durable target field in `settings.toml`.
|
||||
- Deferred commands will be handled in a later pass rather than forced into this refactor.
|
||||
|
|
@ -1,73 +0,0 @@
|
|||
# Object-Backed Artifact Uploads
|
||||
|
||||
## Summary
|
||||
- Make `ArtifactStore` the durable source of truth for all stage artifacts, backed by a configurable object store that can be local filesystem or S3.
|
||||
- Keep the server as the only durable artifact writer. Worker subprocesses upload artifacts to the server over the existing stage-artifacts POST route; they do not write `ArtifactStore` directly and do not use the run scratch directory as IPC.
|
||||
- Ship both upload modes on `POST /api/v1/runs/{id}/stages/{stageId}/artifacts`:
|
||||
- `application/octet-stream` for single-file upload
|
||||
- `multipart/form-data` for batch upload on the same path
|
||||
- Default artifact-upload failure policy is non-fatal: after bounded retries, the worker emits a warning notice and the run continues.
|
||||
- Multipart uploads are a strict wire format: the `manifest` part must arrive first so the server can validate the batch before accepting file bytes.
|
||||
|
||||
## Key Changes
|
||||
- Add artifact storage configuration separate from the main run-store path:
|
||||
- default backend: local object store rooted under the existing storage directory
|
||||
- optional backend: S3 with bucket, region, prefix, optional endpoint override, and path-style toggle
|
||||
- Refactor server startup so `ArtifactStore` is constructed from artifact-storage config instead of being hardwired to `LocalFileSystem` in `serve.rs`.
|
||||
- Extend `ArtifactStore` with streaming writes:
|
||||
- add `put_stream(...)` that writes directly to the configured object store using `object_store::buffered::BufWriter`
|
||||
- use the same deterministic object key layout as today so retries are idempotent
|
||||
- Replace the buffered server artifact upload handler with a streaming implementation:
|
||||
- `application/octet-stream`: requires `filename` query param, streams request body into `ArtifactStore`
|
||||
- `multipart/form-data`: requires a JSON `manifest` part first, followed by file parts; the manifest is the canonical source of artifact paths and optional checksums/content types
|
||||
- Add multipart request types to the OpenAPI spec:
|
||||
- `ArtifactBatchUploadManifest`
|
||||
- `ArtifactBatchUploadEntry`
|
||||
- one entry per file part, keyed by part name and relative artifact path
|
||||
- Validate both octet-stream `filename` query params and multipart manifest paths with the existing relative-path rules; reject traversal, empty segments, duplicate manifest paths, duplicate part names, missing parts, and unexpected parts.
|
||||
- Compute and verify `sha256` during upload when provided by the client. If omitted, accept the upload without checksum enforcement. Native backend checksum features such as S3-specific checksum headers are optional optimizations, not part of the v1 contract.
|
||||
- Enforce explicit server-side limits:
|
||||
- maximum single artifact size
|
||||
- maximum artifacts per multipart request
|
||||
- maximum total multipart request bytes
|
||||
- reject uploads that exceed these limits before durable commit when possible, and abort active multipart writes when the limit is crossed mid-stream
|
||||
- For multipart requests, return non-2xx on the first failed file and leave already-written objects in place. Retries are safe because object keys are deterministic; v1 does not attempt cross-object rollback.
|
||||
- Treat concurrent uploads to the same `{run_id, stage_id, path}` as idempotent-safe retries. Deterministic object keys mean duplicate concurrent uploads may race, but the final durable object must be equivalent regardless of which writer wins.
|
||||
- Update worker subprocess behavior:
|
||||
- after a stage captures artifacts locally, the worker uploads them to the server over the internal artifact route
|
||||
- single-file uploads may use raw octet-stream; batch upload should use multipart when multiple artifacts exist for the stage
|
||||
- the worker emits `artifact.captured` only after the server confirms durable upload
|
||||
- on repeated upload failure, the worker emits a warning-style run notice and continues
|
||||
- Update read paths so `ArtifactStore` is the only source for list/download; no run-scratch fallback is required.
|
||||
- Extend the worker spawn contract so the server provides:
|
||||
- internal server address or Unix-socket target
|
||||
- a short-lived bearer token scoped to artifact upload routes for that run
|
||||
- Accept that interrupted multipart uploads may leave orphaned objects in v1. Record this as operational debt and add a later cleanup pass or age-based GC policy for abandoned artifact objects.
|
||||
|
||||
## Public Interfaces
|
||||
- `POST /api/v1/runs/{id}/stages/{stageId}/artifacts` accepts both `application/octet-stream` and `multipart/form-data`.
|
||||
- Multipart wire format:
|
||||
- one `manifest` JSON part first
|
||||
- one file part per manifest entry
|
||||
- manifest fields: `part`, `path`, optional `sha256`, optional `expected_bytes`, optional `content_type`
|
||||
- Settings gain artifact object-store configuration, with local as the default and S3 as an explicit opt-in backend.
|
||||
|
||||
## Test Plan
|
||||
- Server integration: single-file octet-stream upload stores objects in local object store and returns `204`.
|
||||
- Server integration: multipart batch upload with manifest stores every artifact under the expected object keys and returns `204`.
|
||||
- Validation: invalid artifact path, invalid octet-stream `filename`, duplicate path, duplicate part name, missing file part, unexpected file part, malformed manifest, and manifest-not-first all return `400`.
|
||||
- Integrity: checksum mismatch returns error and does not mark the artifact as captured.
|
||||
- Limits: oversized single artifact, oversized batch byte total, and too many multipart entries all fail with the configured limit response and abort the active upload.
|
||||
- Retry behavior: partial multipart failure can be retried safely and produces the correct final artifact set.
|
||||
- Concurrency: concurrent uploads to the same run/stage/path converge safely to one correct durable object.
|
||||
- Read path: list/download returns artifacts only from `ArtifactStore`.
|
||||
- Worker integration: worker uploads captured artifacts through the server route and emits `artifact.captured` only after success.
|
||||
- Failure behavior: repeated upload failure emits a warning notice and the run completes without failing.
|
||||
- Backend coverage: large artifact upload works against an S3-compatible backend such as MinIO and uses streaming/multipart object-store writes without buffering the full file in memory.
|
||||
|
||||
## Assumptions
|
||||
- Scope is limited to `ArtifactStore` stage artifacts. Large run blobs written by `RunDatabase::write_blob()` are unchanged.
|
||||
- Runs are expected to have durable artifacts in object storage; scratch copies are only local cache/state.
|
||||
- The server remains the sole durable artifact writer and owns all artifact object-store credentials.
|
||||
- Non-fatal artifact-upload failure is the chosen default for v1; if strict durability becomes required later, it can be added as a separate policy change.
|
||||
- The artifact object key remains scoped by run id, stage id, and relative artifact path, so same-key retries are naturally idempotent.
|
||||
|
|
@ -1,147 +0,0 @@
|
|||
# Settings Command Server/Local Merge Plan
|
||||
|
||||
## Summary
|
||||
Refactor `fabro settings` so it answers “what settings will actually be used?” instead of only dumping locally merged config.
|
||||
|
||||
The command contract becomes:
|
||||
|
||||
- `fabro settings`
|
||||
- show the effective merged settings for the selected server target plus local config
|
||||
- `fabro settings --local`
|
||||
- show only locally resolved settings, with no server call
|
||||
- `fabro settings WORKFLOW`
|
||||
- show the effective merged settings for that workflow after server defaults are applied
|
||||
- `fabro settings --local WORKFLOW`
|
||||
- show the local-only merged settings for that workflow, with no server call
|
||||
|
||||
This plan is intentionally separate from the broader config/socket/storage cleanup. It can land independently as long as the command reuses the current shared target-resolution behavior that exists at implementation time.
|
||||
|
||||
## Problem Frame
|
||||
The current `fabro settings` command is purely local. It resolves project/workflow config plus local machine settings and prints the result in YAML or JSON.
|
||||
|
||||
That is no longer the most useful answer for users, because workflows run on a server and the final settings are not purely local. The server already applies its own defaults and runtime adjustments during manifest preparation, so the current output is only a partial picture.
|
||||
|
||||
The goal of this pass is to make `fabro settings` answer two distinct questions clearly:
|
||||
|
||||
- what would the CLI resolve locally without talking to a server?
|
||||
- what settings will actually be used when this workflow runs on the selected server?
|
||||
|
||||
## Key Decisions
|
||||
- `fabro settings` becomes server-targeted by default.
|
||||
- It should fetch server settings and merge them with local config using the same merge logic the server uses for real runs.
|
||||
- `fabro settings --local` skips the server entirely and preserves the current local inspection behavior.
|
||||
- `fabro settings` keeps the optional positional `WORKFLOW`.
|
||||
- With no workflow argument, it shows the effective baseline settings for the current repo/config context.
|
||||
- With a workflow argument, it shows the effective run settings for that workflow.
|
||||
- `fabro settings` should support `--server` as the normal one-off server-target override.
|
||||
- `fabro settings --local` conflicts with `--server`.
|
||||
- `fabro settings` should no longer take `--storage-dir`.
|
||||
- Storage targeting is not the purpose of this command.
|
||||
- Output format stays the same:
|
||||
- default: YAML `Settings`
|
||||
- `--json`: JSON `Settings`
|
||||
- The command should return only the resolved `Settings` object, not extra metadata fields.
|
||||
- Effective target/config-path diagnostics belong in `doctor` or other output, not in the `settings` payload itself.
|
||||
- Bare `fabro settings` should use the same server-target resolution behavior as other server-targeted commands at the time this plan lands.
|
||||
- If the resolved target is a Unix socket, it may use the normal socket/autostart path.
|
||||
- If the resolved target is an HTTP target and the server is unreachable, the command should fail clearly.
|
||||
- It should not silently fall back to `--local`.
|
||||
- The `/api/v1/settings` endpoint should return the full effective runtime `Settings` object from the server.
|
||||
- The shared merge helper remains responsible for precedence and for preserving the existing distinction between full server defaults and local-daemon-only overrides.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. CLI surface
|
||||
- Change `SettingsArgs` in [`lib/crates/fabro-cli/src/args.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/args.rs) to:
|
||||
- add `ServerTargetArgs`
|
||||
- add `--local`
|
||||
- keep optional `WORKFLOW`
|
||||
- remove `StorageDirArgs`
|
||||
- Update help text and parser tests in [`lib/crates/fabro-cli/tests/it/cmd/config.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/tests/it/cmd/config.rs) accordingly.
|
||||
|
||||
### 2. Shared merge logic
|
||||
- Extract the server/default merge logic currently embedded in [`lib/crates/fabro-server/src/run_manifest.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/run_manifest.rs) into a shared helper in `fabro-config` that both the server and CLI can call.
|
||||
- The helper should live in `fabro-config` because both `fabro-cli` and `fabro-server` already depend on it, while `fabro-cli` should not depend on `fabro-server` merge internals.
|
||||
- The shared helper should accept:
|
||||
- the local config layers already resolved by the CLI side
|
||||
- server settings fetched from the target server
|
||||
- a mode flag matching current manifest preparation semantics
|
||||
- The helper must preserve the current distinction between:
|
||||
- normal remote/server merge behavior
|
||||
- local-daemon merge behavior
|
||||
- The helper must make the precedence explicit:
|
||||
- `fabro settings`: `project + user + server_defaults`
|
||||
- `fabro settings WORKFLOW`: `workflow + project + user + server_defaults`
|
||||
- `fabro settings --local`: `project + user`
|
||||
- `fabro settings --local WORKFLOW`: `workflow + project + user`
|
||||
- In server-targeted mode, the helper must apply `strip_server_owned_fields` to local layers (workflow, project, user) before combining with server defaults, matching `prepare_manifest_with_mode` semantics. Without this, fields like `exec` or `server` set in a local workflow config would override the server's values, which doesn't match actual run behavior.
|
||||
- The helper should continue to apply the same server-side rules that exist today:
|
||||
- normal mode uses the full `server_defaults_layer()`
|
||||
- local-daemon mode uses `local_daemon_server_overrides_layer()`
|
||||
- any required post-resolution overrides, such as forcing `storage_dir` from the active server settings, remain in the shared helper rather than being reimplemented by the CLI
|
||||
- The CLI determines the mode from the resolved `ServerTarget` type: `ServerTarget::UnixSocket` → local-daemon mode, `ServerTarget::HttpUrl` → remote mode.
|
||||
- The shared helper's scope is layer combination + resolution + post-resolution overrides. `prepare_manifest_with_mode` continues to handle manifest-specific work (parsing workflow bundles, building `args_layer` from `ManifestArgs`, applying `manifest.goal`) and delegates to the shared helper for the combine/resolve step.
|
||||
- The server should be switched to use the shared helper so `fabro settings` cannot drift from actual run semantics.
|
||||
|
||||
### 3. Server settings source
|
||||
- Implement the real `/api/v1/settings` route in [`lib/crates/fabro-server/src/server.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/server.rs), matching the existing OpenAPI contract in [`docs/api-reference/fabro-api.yaml`](/Users/bhelmkamp/p/fabro-sh/fabro/docs/api-reference/fabro-api.yaml).
|
||||
- The route should return the server’s current effective runtime settings from `AppState`, not just a raw disk parse.
|
||||
- The route should return the full runtime `Settings` object, not a reduced server-owned subset.
|
||||
- The CLI settings command should call this route when `--local` is not set.
|
||||
|
||||
### 4. Command behavior
|
||||
- In [`lib/crates/fabro-cli/src/commands/config/mod.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/commands/config/mod.rs):
|
||||
- preserve the existing local merge path for `--local`
|
||||
- add a server-targeted path for the default behavior
|
||||
- Local-only resolution should keep the current semantics:
|
||||
- no workflow: project config from cwd + local settings
|
||||
- workflow: workflow config + project config + local settings
|
||||
- Server-targeted resolution should:
|
||||
- resolve the server target using the normal shared target-resolution helpers
|
||||
- fetch server settings from `/api/v1/settings`
|
||||
- build the same local layers the command already knows how to build
|
||||
- combine them with fetched server settings using the shared merge helper
|
||||
- If the server is unreachable:
|
||||
- Unix socket targets should follow the same socket/autostart behavior normal server-targeted commands use at the time this plan lands
|
||||
- HTTP targets should fail clearly
|
||||
- the command should not fall back to local-only mode unless the user explicitly asked for `--local`
|
||||
- For `WORKFLOW`, the command should not call `preflight` or create a run.
|
||||
- It should compute and print the resolved settings only.
|
||||
|
||||
### 5. Separation from broader targeting cleanup
|
||||
- This plan should not block on the larger config/socket/storage refactor.
|
||||
- If the broader refactor lands first, `fabro settings` should reuse the new target-resolution helpers.
|
||||
- If it lands first, `fabro settings` should reuse the current `--server` / configured server-target behavior and keep its implementation scoped to this command.
|
||||
- This plan does not change `exec`, `system df`, `system prune`, or `store dump`.
|
||||
|
||||
## Test Plan
|
||||
- CLI parser/help coverage in [`lib/crates/fabro-cli/tests/it/cmd/config.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/tests/it/cmd/config.rs):
|
||||
- `fabro settings --help` shows `--local` and `--server`
|
||||
- `fabro settings --local --server ...` is rejected
|
||||
- `--storage-dir` is no longer accepted
|
||||
- Local behavior tests:
|
||||
- `fabro settings --local` preserves current merged local output
|
||||
- `fabro settings --local WORKFLOW` resolves workflow + project + local settings only
|
||||
- Server-targeted behavior tests:
|
||||
- `fabro settings` fetches server settings and merges them with local config
|
||||
- `fabro settings WORKFLOW` merges workflow + project + local + server settings
|
||||
- `fabro settings --server http://...` uses the explicit target
|
||||
- socket-targeted settings resolution behaves the same way normal commands do at the time this plan lands
|
||||
- unreachable HTTP targets fail clearly and do not fall back to local-only output
|
||||
- Shared merge helper tests:
|
||||
- `prepare_manifest_with_mode()` delegates to the shared helper for the merge/defaults path
|
||||
- helper tests directly cover the layer precedence for:
|
||||
- `project + user`
|
||||
- `workflow + project + user`
|
||||
- `project + user + server_defaults`
|
||||
- `workflow + project + user + server_defaults`
|
||||
- local-daemon merge semantics remain distinct from remote-server merge semantics where that distinction already exists
|
||||
- server-owned fields in local layers (workflow, project, user) are stripped before merging in server-targeted mode, matching `prepare_manifest_with_mode` behavior
|
||||
- Server route tests:
|
||||
- real `/api/v1/settings` returns the structured settings shape from the OpenAPI contract
|
||||
- route reflects effective runtime settings, including active storage-dir/runtime overrides
|
||||
|
||||
## Assumptions
|
||||
- Returning the raw `Settings` payload is sufficient; no new wrapper response is needed for the CLI command.
|
||||
- Reusing the existing `/api/v1/settings` contract is preferable to adding a second settings-resolution endpoint in this pass.
|
||||
- `fabro settings WORKFLOW` may perform local workflow/project discovery exactly as the command does today; the only new remote input is the selected server’s settings.
|
||||
- This pass is command-focused and does not attempt to solve all settings introspection use cases elsewhere in the API.
|
||||
|
|
@ -1,237 +0,0 @@
|
|||
# Subprocess Run Workers And Signal Control
|
||||
|
||||
## Summary
|
||||
- Move workflow execution out of `fabro server` into one hidden worker subprocess per run.
|
||||
- Use Unix signals for lifecycle control, but keep the server as the sole durable writer for run events, projections, and summaries.
|
||||
- Stream canonical worker events back to the server over the worker stdout pipe so the event log, SSE, and API status stay coherent without multi-process append races.
|
||||
|
||||
## Scope Boundaries
|
||||
In scope:
|
||||
- replace in-process run execution with supervised worker subprocesses
|
||||
- repurpose hidden `fabro __runner` into hidden `fabro __run-worker`
|
||||
- use signals for `cancel`, `pause`, and `unpause`
|
||||
- make the server the only writer to a run's durable event stream
|
||||
- define a worker spawn contract, stdout/stderr contract, and control priority rules
|
||||
- add request and effect events for run control
|
||||
- phase delivery so subprocess cancel lands before pause and procline polish
|
||||
|
||||
Out of scope:
|
||||
- non-Unix parity for worker supervision
|
||||
- crash-time worker reattachment in the first delivery
|
||||
- changing the current public control routes away from `/runs/{id}/cancel`, `/pause`, and `/unpause`
|
||||
- changing terminal cancellation away from durable `status=failed` with `status_reason=cancelled`
|
||||
|
||||
## Problem Frame
|
||||
The intended architecture is server-supervised subprocess workers, not server-local async tasks. The current plan also assumed both server and worker could append to the same run event stream, but the current `RunDatabase` writer is process-local: sequence allocation, event cache, and watch fanout are held in per-process memory. That makes multi-process writes and cross-process `watch_events_from()` unsafe as a foundation for this refactor.
|
||||
|
||||
The revised plan therefore needs to solve four things explicitly:
|
||||
|
||||
- control delivery without shared in-process primitives
|
||||
- durable event ordering without multi-process writers
|
||||
- server observation of worker state transitions
|
||||
- clear priority and override rules when multiple control requests arrive
|
||||
|
||||
## Key Decisions
|
||||
- Hidden worker command
|
||||
- Rename hidden `fabro __runner` to hidden `fabro __run-worker`.
|
||||
- `__run-worker` executes a single run locally and does not call back into the server API.
|
||||
- Single-writer rule
|
||||
- The server is the only process that appends durable run events, updates run projections, and drives SSE.
|
||||
- The worker must not open a write-capable `RunDatabase`.
|
||||
- The worker may open the run store read-only for manifest and checkpoint reads only.
|
||||
- Worker-to-server event path
|
||||
- Worker stdout is reserved for newline-delimited canonical `RunEvent` JSON objects.
|
||||
- The worker builds canonical events once, using the existing event model, and writes them to stdout.
|
||||
- The server reads stdout, validates each event, appends it to the run store, and fans it out to SSE and any in-process listeners.
|
||||
- This replaces the current assumption that the worker writes directly to the run store.
|
||||
- Worker stderr and logs
|
||||
- Worker stderr is not part of the event stream.
|
||||
- The server captures worker stderr, writes it to a per-run log file under the run scratch directory, and mirrors lines into server tracing with the run id attached.
|
||||
- Worker spawn contract
|
||||
- The server spawns `fabro __run-worker --run-id <id> --mode <start|resume> --storage-dir <dir>`.
|
||||
- If the active config path is required to reproduce local runtime behavior, pass `--config <path>` as well.
|
||||
- The worker does not need a server address because it does not talk HTTP to the server.
|
||||
- Control delivery
|
||||
- `cancel` sends `SIGTERM` to the worker process.
|
||||
- After the grace timeout, the server sends `SIGKILL` to the worker process group.
|
||||
- `pause` sends `SIGUSR1`.
|
||||
- `unpause` sends `SIGUSR2`.
|
||||
- Do not use `SIGSTOP` / `SIGCONT` for API pause and unpause.
|
||||
- Control priority and conflict rules
|
||||
- Priority is `cancel > pause > unpause`.
|
||||
- `pending_control` remains a single value and later accepted requests overwrite lower-priority pending requests.
|
||||
- `cancel` is accepted from `submitted`, `runnable`, `starting`, `running`, or `paused`.
|
||||
- A `cancel` request overwrites a pending `pause` or `unpause`.
|
||||
- `pause` is accepted only when observed status is `running` and `pending_control` is `null`.
|
||||
- `unpause` is accepted only when observed status is `paused` and `pending_control` is `null`.
|
||||
- A lower-priority request while a higher-priority request is pending returns `409`.
|
||||
- If `pause` is pending and `cancel` arrives before the worker reaches a safe point, the worker must skip `run.paused` and terminate through the normal cancel path.
|
||||
- If the run is already paused and `cancel` arrives, the worker must exit the pause wait and cancel immediately.
|
||||
- Signal handling in the worker
|
||||
- `SIGTERM` requests cooperative cancellation.
|
||||
- `SIGUSR1` requests cooperative pause.
|
||||
- `SIGUSR2` requests cooperative unpause.
|
||||
- Pause takes effect only at safe points such as between stages, before retry sleeps, before entering or resuming human waits, and at existing cancellation checkpoints.
|
||||
- Event naming
|
||||
- Use `run.cancel.requested`, `run.pause.requested`, and `run.unpause.requested` for accepted control requests.
|
||||
- Use `run.paused` and `run.unpaused` for observed worker transitions.
|
||||
- Keep terminal cancellation on `run.failed` with `reason=cancelled`.
|
||||
- Avoid `run.resumed` because `resume` already means resume-from-checkpoint elsewhere in the system.
|
||||
- Restart behavior in the first delivery
|
||||
- Do not attempt PID-based worker reattachment in the first delivery.
|
||||
- On graceful server shutdown, terminate active workers before exit.
|
||||
- On server startup, any non-terminal run with stale worker metadata from a prior server process is marked interrupted or terminated and its worker metadata is cleared.
|
||||
- Robust crash-time reattachment is deferred to a later phase and must include process identity verification before any signal delivery.
|
||||
- API shape
|
||||
- Keep the current control routes and verbs.
|
||||
- Extend `RunStatusResponse` with `status_reason` and `pending_control`.
|
||||
- Extend durable `StoreRunSummary` with `pending_control`.
|
||||
- Control endpoints return the current observed status plus `pending_control`; they do not report the requested action as completed until the worker emits the corresponding effect event.
|
||||
- Process titles
|
||||
- Server titles:
|
||||
- `fabro server boot`
|
||||
- `fabro server unix:/path/to/socket`
|
||||
- `fabro server tcp:127.0.0.1:3000`
|
||||
- `fabro server stopping`
|
||||
- Worker titles use the existing 12-character short run-id convention:
|
||||
- `fabro <short-id> start`
|
||||
- `fabro <short-id> resume`
|
||||
- `fabro <short-id> init`
|
||||
- `fabro <short-id> running`
|
||||
- `fabro <short-id> waiting`
|
||||
- `fabro <short-id> paused`
|
||||
- `fabro <short-id> cancelling`
|
||||
- `fabro <short-id> succeeded`
|
||||
- `fabro <short-id> failed`
|
||||
- `fabro <short-id> cancelled`
|
||||
|
||||
## Delivery Plan
|
||||
### Phase 1: Subprocess execution and signal cancel
|
||||
- Spawn one worker subprocess per started run.
|
||||
- Make the server the sole event-store writer.
|
||||
- Stream canonical worker events over stdout into the server.
|
||||
- Route worker stderr into per-run log files and server tracing.
|
||||
- Implement signal-based `cancel` only.
|
||||
- Do not support crash-time worker reattachment in this phase.
|
||||
|
||||
### Phase 2: Control request events and API status enrichment
|
||||
- Add `run.cancel.requested` and `pending_control`.
|
||||
- Extend `RunStatusResponse` and `StoreRunSummary` with `status_reason` and `pending_control`.
|
||||
- Update status projections so accepted cancel requests surface immediately without pretending the run has already terminated.
|
||||
|
||||
### Phase 3: Pause and unpause
|
||||
- Add `SIGUSR1` and `SIGUSR2` handling.
|
||||
- Add `run.pause.requested`, `run.unpause.requested`, `run.paused`, and `run.unpaused`.
|
||||
- Implement the priority and overwrite rules defined above.
|
||||
|
||||
### Phase 4: Procline polish and optional crash-time recovery
|
||||
- Add title helpers and short-id process titles.
|
||||
- If crash-time worker recovery is still wanted, design it as a separate pass with explicit worker identity verification before any PID-based signaling.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Server supervision and worker pipes
|
||||
- Replace the current `tokio::spawn(execute_run(...))` path in `lib/crates/fabro-server/src/server.rs` with worker subprocess spawning.
|
||||
- Introduce a server-side supervisor record for live runs that stores:
|
||||
- observed status
|
||||
- created time
|
||||
- local error text
|
||||
- worker PID
|
||||
- worker PGID
|
||||
- worker mode (`start` or `resume`)
|
||||
- current `pending_control`
|
||||
- handles for worker stdout and stderr tasks
|
||||
- On worker spawn:
|
||||
- set process-group isolation
|
||||
- capture stdout and stderr
|
||||
- start one task that parses stdout into canonical `RunEvent`s and appends them to the run store
|
||||
- start one task that drains stderr into a per-run log file and tracing
|
||||
- set observed status to `starting`
|
||||
- On worker exit:
|
||||
- if the worker already produced a terminal run event, clear live worker metadata only
|
||||
- if no terminal run event was appended, append a terminal failure with `reason=terminated`
|
||||
|
||||
### 2. Workflow engine event sink refactor
|
||||
- Refactor run execution so the worker path no longer depends on direct run-store writes from inside `fabro-workflow`.
|
||||
- Introduce a run-event sink abstraction used by workflow execution, retro, pull-request creation, and any remaining bypass paths that currently append directly to the run store.
|
||||
- For worker execution, the sink serializes canonical `RunEvent` JSON lines to stdout.
|
||||
- Preserve the current event-strategy rule that the canonical `RunEvent` is built exactly once and reused for all downstream sinks.
|
||||
|
||||
### 3. Worker execution and safe-point control
|
||||
- Rewrite `lib/crates/fabro-cli/src/commands/run/runner.rs` into the `__run-worker` entrypoint that:
|
||||
- loads the run manifest and checkpoint state read-only from storage
|
||||
- executes `operations::start` or `operations::resume`
|
||||
- owns the workflow `Emitter`
|
||||
- translates OS signals into local cooperative control flags
|
||||
- At safe points:
|
||||
- if cancel is requested, terminate through the existing cancellation path
|
||||
- if pause is requested and cancel is not pending, emit `run.paused`, block until unpause or cancel, then emit `run.unpaused` when execution continues
|
||||
- Make cancel override a paused state immediately.
|
||||
|
||||
### 4. Event model and projection updates
|
||||
- Extend `fabro-workflow` event types and `fabro-types` `EventBody` with:
|
||||
- `run.cancel.requested`
|
||||
- `run.pause.requested`
|
||||
- `run.unpause.requested`
|
||||
- `run.paused`
|
||||
- `run.unpaused`
|
||||
- Keep request events server-originated and effect events worker-originated.
|
||||
- Update `lib/crates/fabro-store/src/run_state.rs` so projections:
|
||||
- track `pending_control`
|
||||
- do not let request events overwrite observed status
|
||||
- apply `run.paused` and `run.unpaused` to observed status
|
||||
- continue projecting terminal cancellation as `status=failed` and `status_reason=cancelled`
|
||||
- Extend durable `RunSummary` with `pending_control`.
|
||||
|
||||
### 5. API and client updates
|
||||
- Update `docs/api-reference/fabro-api.yaml` with:
|
||||
- a new `RunControlAction` schema using `cancel`, `pause`, and `unpause`
|
||||
- `pending_control` on `RunStatusResponse`
|
||||
- `status_reason` on `RunStatusResponse`
|
||||
- `pending_control` on `StoreRunSummary`
|
||||
- Define control endpoint behavior as:
|
||||
- validate whether the action is currently allowed
|
||||
- apply the priority and overwrite rules above
|
||||
- append the corresponding request event
|
||||
- update `pending_control`
|
||||
- send the signal if a live worker exists
|
||||
- return the current observed status response
|
||||
- Regenerate both generated API clients after the OpenAPI change.
|
||||
|
||||
### 6. Process title cleanup
|
||||
- Keep using `fabro_proc::title_init()` and `fabro_proc::title_set()`.
|
||||
- Add helpers for server title updates by bind and lifecycle phase, and worker title updates by short run id and worker phase.
|
||||
- Keep procline verification lightweight; do not build brittle exact-string end-to-end assertions around process titles.
|
||||
|
||||
## Test Plan
|
||||
- Single-writer and event-path tests
|
||||
- worker execution path opens the run store read-only only
|
||||
- worker stdout emits valid newline-delimited canonical `RunEvent` payloads
|
||||
- server appends worker-streamed events in order and SSE reflects the appended stream
|
||||
- worker stderr is captured into the per-run log file
|
||||
- Cancel tests
|
||||
- starting a runnable run spawns a worker subprocess and records PID and PGID
|
||||
- `POST /runs/{id}/cancel` appends `run.cancel.requested`, sets `pending_control=cancel`, sends `SIGTERM`, and later converges to durable `failed` with `status_reason=cancelled`
|
||||
- cancelling a submitted or runnable run reaches durable `failed/cancelled` without spawning a worker
|
||||
- an unresponsive worker is escalated from worker `SIGTERM` to process-group `SIGKILL`
|
||||
- Pause and unpause tests
|
||||
- `POST /runs/{id}/pause` on a running worker appends `run.pause.requested`, sets `pending_control=pause`, and later projects `paused`
|
||||
- `POST /runs/{id}/unpause` on a paused worker appends `run.unpause.requested`, sets `pending_control=unpause`, and later projects `running`
|
||||
- pause followed by cancel before a safe point never produces `run.paused`
|
||||
- cancel while paused exits the pause wait and converges to durable `failed/cancelled`
|
||||
- lower-priority actions while a higher-priority action is pending return `409` and append no request event
|
||||
- Startup behavior tests
|
||||
- graceful server shutdown terminates active workers
|
||||
- startup clears stale worker metadata and marks prior non-terminal runs interrupted or terminated
|
||||
- Verification commands
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo nextest run -p fabro-workflow`
|
||||
- `cargo nextest run -p fabro-store`
|
||||
- `cargo nextest run -p fabro-cli`
|
||||
- `cargo fmt --check --all`
|
||||
- `cargo clippy --workspace -- -D warnings`
|
||||
|
||||
## Assumptions
|
||||
- This refactor is Unix-first and may explicitly reject or defer non-Unix worker supervision behavior.
|
||||
- The first delivery optimizes for correct subprocess supervision and durable event ordering, not crash-time worker survival across server restarts.
|
||||
- `pause` and `unpause` are cooperative safe-point transitions, not immediate OS-level stop and continue.
|
||||
- The short run id remains the first 12 characters of the ULID, matching current CLI presentation.
|
||||
|
|
@ -1,204 +0,0 @@
|
|||
---
|
||||
title: "fix: make attach streams terminal-authoritative"
|
||||
type: fix
|
||||
status: active
|
||||
date: 2026-04-07
|
||||
---
|
||||
|
||||
# fix: make attach streams terminal-authoritative
|
||||
|
||||
## Overview
|
||||
|
||||
Remove `ATTACH_FINAL_STATUS_GRACE` by making `GET /api/v1/runs/{id}/attach` the authoritative source of terminal completion for `fabro attach`.
|
||||
|
||||
After this change:
|
||||
|
||||
- the server streams ordered events starting at `since_seq`
|
||||
- if a terminal event is reached, the server emits it and closes the stream immediately
|
||||
- the CLI exits as soon as it sees `run.completed` or `run.failed`
|
||||
- the CLI no longer waits for quiet time or polls run state after attach completes
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Current behavior is split across the server and CLI in a way that creates a completion race:
|
||||
|
||||
- the server treats `/attach` as a live-only event tail and returns `410 Gone` when the run is no longer live
|
||||
- the CLI lists historical events first, then opens `/attach?since_seq=next_seq`
|
||||
- if the run finishes between those two steps, the CLI can miss the terminal event and has to rely on `ATTACH_FINAL_STATUS_GRACE`
|
||||
- even when the CLI does receive a terminal event, the server-side live stream does not close on that event, so the CLI waits for a grace period before deciding the stream is done
|
||||
|
||||
The desired contract is simpler: `attach` should trust the stream. If the stream ends before a terminal event, that is an error, not a case for client-side repair logic.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. `GET /api/v1/runs/{id}/attach` must serve ordered events beginning at `since_seq`, whether the run is still live or already terminal.
|
||||
- R2. If the stream reaches `run.completed` or `run.failed`, the server must emit that event and close the stream immediately.
|
||||
- R3. `fabro attach` must derive completion and exit status from streamed events, not from grace periods or follow-up state polling.
|
||||
- R4. `GET /api/v1/runs/{id}/attach` must stop returning `410 Gone` for completed runs.
|
||||
- R5. The existing bare-attach API behavior when `since_seq` is omitted remains unchanged: the endpoint starts at the current tail, so attaching after a completed run with no unread events may produce an empty stream that closes immediately.
|
||||
- R6. The CLI must not interpret R5 as a protocol success path. `fabro attach` still short-circuits terminal runs via its initial state-and-history replay, so its premature-EOF error handling applies only to the live-stream path entered after the initial terminal check.
|
||||
- R7. The run-specific SSE attach stream must send keepalives during idle periods so long-running quiet stages do not surface as transport EOFs.
|
||||
- R8. Interview handling and Ctrl-C detach behavior remain unchanged.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- The server owns the completion contract.
|
||||
The CLI stays simple and exits immediately on terminal events.
|
||||
|
||||
- Premature EOF is a protocol error.
|
||||
If the live attach stream ends before a terminal event is observed, `fabro attach` exits non-zero with a clear error instead of performing a repair lookup. This does not conflict with R5 because the CLI does not enter the live-stream path for already-terminal runs.
|
||||
|
||||
- `/attach` becomes replay-capable for completed runs.
|
||||
The endpoint no longer uses “run is live” as a gate for whether unread events can be served.
|
||||
|
||||
- No new durable storage primitive is required, but the live-watch helper must be hardened.
|
||||
`open_run_reader()` already returns the shared active `RunDatabase` for live runs, but the current `watch_events_from()` handoff is not strong enough for this contract because it snapshots recent events before subscribing. The implementation must make the replay-to-watch transition seq-complete.
|
||||
|
||||
- Keepalive is in scope for run-specific attach.
|
||||
The new fail-fast EOF contract is only acceptable if the run-specific SSE stream gets the same idle keepalive treatment as the existing global attach endpoint.
|
||||
|
||||
## Public API / Interface Changes
|
||||
|
||||
- Update `docs/api-reference/fabro-api.yaml` for `GET /api/v1/runs/{id}/attach`:
|
||||
- change the description from “live run” SSE to “ordered event stream starting at `since_seq`, replaying persisted events and continuing with live updates while the run remains active”
|
||||
- remove the `410 Run is not live on this server` response
|
||||
|
||||
- Regenerate generated clients after the spec update:
|
||||
- `cargo build -p fabro-api`
|
||||
- `cd lib/packages/fabro-api-client && bun run generate`
|
||||
|
||||
- Remove the CLI’s `RunAttachStreamError::Gone` branch from the Rust server client.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
### [ ] Unit 1: Make server attach replay terminal-safe
|
||||
|
||||
**Goal**
|
||||
|
||||
Change the server attach endpoint so it can always deliver unread terminal events and self-close on terminal completion.
|
||||
|
||||
**Files**
|
||||
|
||||
- `lib/crates/fabro-server/src/server.rs`
|
||||
- `lib/crates/fabro-store/src/slate/run_store.rs`
|
||||
- `docs/api-reference/fabro-api.yaml`
|
||||
|
||||
**Approach**
|
||||
|
||||
- Replace the current “live run only” guard in `attach_run_events()`.
|
||||
- Open the run reader first and return `404` only when the run truly does not exist.
|
||||
- Compute `start_seq` exactly as today.
|
||||
- Replay persisted events from `start_seq` using `list_events_from_with_limit` in bounded batches, converting them through the existing `sse_event_from_store()` helper.
|
||||
- Detect terminal events during replay. If replay emits `run.completed` or `run.failed`, close the SSE stream immediately after that event.
|
||||
- Before using live watch for attach, harden `watch_events_from()` so it is seq-complete for handoff:
|
||||
- subscribe to `event_tx` before snapshotting `recent_events`
|
||||
- snapshot and emit cached events at or after the requested seq
|
||||
- then drain broadcast events, discarding any seq lower than the next expected seq
|
||||
This closes the snapshot-to-subscribe gap that exists in the current helper.
|
||||
- If replay reaches the current tail without hitting a terminal event and the run is still active, switch to the hardened `watch_events_from(next_seq)` on the shared `RunDatabase`.
|
||||
- In the live phase, stream events until the first terminal event, then close immediately.
|
||||
- Add `.keep_alive(KeepAlive::default())` to the run-specific SSE response so idle stages do not turn into transport EOFs.
|
||||
|
||||
**Patterns to follow**
|
||||
|
||||
- Existing event serialization helpers in `lib/crates/fabro-server/src/server.rs`
|
||||
- Existing event listing behavior in `list_run_events()`
|
||||
- Global attach keepalive behavior in `lib/crates/fabro-server/src/server.rs`
|
||||
- Updated `watch_events_from()` semantics in `lib/crates/fabro-store/src/slate/run_store.rs`
|
||||
|
||||
**Test scenarios**
|
||||
|
||||
- Attach to a live run and confirm the stream includes stage events, then a terminal event, then EOF.
|
||||
- Attach after the run has already completed with `since_seq` before the terminal event and confirm replay includes the terminal event, then EOF.
|
||||
- Attach after completion with `since_seq` after the last event and confirm the stream returns `200` and closes cleanly with no events.
|
||||
- Attach during the race where the run completes after the client reads history but before it opens `/attach`, and confirm the terminal event is still delivered.
|
||||
Use a barrier or oneshot to hold terminal completion until after the history read returns and release it before the `/attach` request starts, so the race is deterministic rather than sleep-based.
|
||||
- Attach to a nonexistent run and confirm `404` remains unchanged.
|
||||
- Attach to a run with a deliberately quiet stage and confirm the SSE response stays open via keepalive until later events arrive.
|
||||
|
||||
**Verification**
|
||||
|
||||
- Server tests prove `200` is returned for completed runs with unread events.
|
||||
- Server tests prove the stream terminates immediately after a terminal event.
|
||||
|
||||
### [ ] Unit 2: Simplify CLI attach around terminal events
|
||||
|
||||
**Goal**
|
||||
|
||||
Remove timer-based completion handling from `fabro attach` and make the command trust streamed terminal events.
|
||||
|
||||
**Files**
|
||||
|
||||
- `lib/crates/fabro-cli/src/commands/run/attach.rs`
|
||||
- `lib/crates/fabro-cli/src/server_client.rs`
|
||||
|
||||
**Approach**
|
||||
|
||||
- Delete `ATTACH_FINAL_STATUS_GRACE`.
|
||||
- Delete `determine_exit_code_with_server()`.
|
||||
- Remove `RunAttachStreamError::Gone` and its special handling.
|
||||
- Keep the initial replay path: if the initial event list or run state already shows the run is terminal, replay and exit as today.
|
||||
- In the live attach path, emit events and return immediately when `event_exit_code()` sees `run.completed` or `run.failed`.
|
||||
- If the live attach stream ends before a terminal event is observed, return a non-zero protocol error instead of polling server state.
|
||||
- Document in code that this EOF rule applies only after the command has already ruled out the R5 completed-run replay case via the initial terminal check.
|
||||
- Leave interview prompting and Ctrl-C behavior unchanged.
|
||||
|
||||
**Patterns to follow**
|
||||
|
||||
- Existing `event_exit_code()` extraction in `lib/crates/fabro-cli/src/commands/run/attach.rs`
|
||||
- Existing replay behavior in `replay_run_with_client()`
|
||||
|
||||
**Test scenarios**
|
||||
|
||||
- Successful attach on a live run exits `0` immediately after `run.completed`.
|
||||
- Failed attach on a live run exits `1` immediately after `run.failed`.
|
||||
- Completed run replay still exits with the correct code without opening a live stream.
|
||||
- Premature EOF before any terminal event produces a non-zero exit and clear error text.
|
||||
|
||||
**Verification**
|
||||
|
||||
- CLI tests no longer depend on grace-period timing.
|
||||
- No attach code path polls run state after a live stream finishes.
|
||||
|
||||
### [ ] Unit 3: Align tests, demo behavior, and generated API artifacts
|
||||
|
||||
**Goal**
|
||||
|
||||
Update repo expectations so they match the new terminal-authoritative attach contract.
|
||||
|
||||
**Files**
|
||||
|
||||
- `lib/crates/fabro-server/tests/it/scenario/run_completion.rs`
|
||||
- `lib/crates/fabro-server/tests/it/scenario/sse.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/attach.rs`
|
||||
- `lib/crates/fabro-server/src/demo/mod.rs`
|
||||
- generated Rust and TypeScript API artifacts
|
||||
|
||||
**Approach**
|
||||
|
||||
- Replace current `200 or 410` attach assertions with `200`-only expectations where applicable.
|
||||
- Update the server unit/integration test near the current `StatusCode::GONE` assertion to verify replay-and-close semantics instead.
|
||||
- Update the demo attach stub to return a short SSE response that ends cleanly, rather than `410`.
|
||||
- Regenerate Rust and TypeScript clients after the OpenAPI change.
|
||||
|
||||
**Test scenarios**
|
||||
|
||||
- Server scenario tests verify completed-run attach no longer returns `410`.
|
||||
- CLI mock-server attach tests verify the command exits from streamed terminal events rather than fallback logic.
|
||||
- Demo-mode attach still behaves coherently for callers expecting an attach response.
|
||||
|
||||
**Verification**
|
||||
|
||||
- Spec, generated clients, and tests all describe the same `attach` contract.
|
||||
|
||||
## Test Plan
|
||||
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo nextest run -p fabro-cli`
|
||||
- Target the attach-specific server and CLI tests first while iterating, then run the crate suites before landing.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- `fabro logs` and `FOLLOW_TERMINAL_GRACE` are out of scope for this change.
|
||||
- Every valid terminal run should emit a persisted terminal event (`run.completed` or `run.failed`); any gap found during implementation should be treated as a server bug to fix, not a reason to reintroduce client grace timing.
|
||||
- The user preference for attach simplicity is authoritative: premature EOF is an error, not a repairable condition.
|
||||
|
|
@ -1,209 +0,0 @@
|
|||
# Global CAS Blob Refs Plan
|
||||
|
||||
## Summary
|
||||
|
||||
Replace durable offload pointers with global content-addressed blob refs and keep file paths as an execution-only concern.
|
||||
|
||||
- Automatic large-value offload should persist `blob://sha256/<hex>` refs instead of `file://...` paths.
|
||||
- Blob bytes should be stored in a global CAS namespace rather than under per-run keys.
|
||||
- Handlers and preamble generation should continue to see file references, but those files should be materialized only in the execution-local environment.
|
||||
- Host scratch blob cache files should stop being part of the durable contract.
|
||||
- Garbage collection is explicitly deferred in this pass.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Large context values are currently offloaded by writing the serialized JSON bytes to the run store, materializing a host-side cache file, and replacing the original value with a `file://` pointer to that file.
|
||||
|
||||
That shape creates the wrong durable boundary:
|
||||
|
||||
- persisted checkpoints and checkpoint-completed events contain host- or sandbox-specific file paths instead of stable storage references
|
||||
- resume seeds those path strings back into runtime state verbatim
|
||||
- remote sandbox sync rewrites durable context into sandbox-local `file://` paths
|
||||
- fork semantics are awkward because the same logical content becomes tied to a specific run and a specific materialized file path
|
||||
|
||||
The durable source of truth should be the blob bytes addressed by content hash. File paths should only exist as a temporary execution detail for agents and command handlers.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- Use `blob://sha256/<blob_id>` as the only new durable blob reference format.
|
||||
- `RunBlobId` remains the existing SHA-256 hex content hash type in this pass.
|
||||
- Durable run state, checkpoints, and checkpoint-completed event payloads should persist only plain JSON values and `blob://` refs.
|
||||
|
||||
- Make blob storage global CAS instead of run-scoped.
|
||||
- Internally, blob bytes move from per-run keys to global keys such as `blobs#sha256#<blob_id>`.
|
||||
- Existing run-scoped server endpoints can remain as the API surface for now, but they should read and write the global CAS store under the hood.
|
||||
|
||||
- Keep blob handling invisible to the model.
|
||||
- The model should continue to receive file references in prompts and preambles.
|
||||
- `blob://` is a backend durability protocol, not a model-facing protocol.
|
||||
|
||||
- Materialize blobs only in execution-local views.
|
||||
- Before handler execution and before preamble construction, resolve `blob://` refs into local files for the active sandbox.
|
||||
- For remote sandboxes, materialize under `{working_directory}/.fabro/blobs/<blob_id>.json`.
|
||||
- For local execution, materialize under a run-local ephemeral runtime directory such as `runtime/blobs/<blob_id>.json`.
|
||||
|
||||
- Do not persist execution-local `file://` refs back into durable state.
|
||||
- Managed materialized blob file refs must be normalized back to `blob://sha256/<blob_id>` before context snapshots are emitted or checkpointed.
|
||||
|
||||
- Preserve compatibility with older runs.
|
||||
- Read paths should continue to recognize legacy blob-backed `file://.../<blob_id>.json` values.
|
||||
- New writes should use only the `blob://` form.
|
||||
|
||||
- Leave stage artifacts unchanged.
|
||||
- This change applies only to offloaded run blobs.
|
||||
- `ArtifactStore` remains the durable system for captured stage artifacts.
|
||||
|
||||
- Defer GC.
|
||||
- New blob writes are append-only in this pass.
|
||||
- No mark-and-sweep, refcounting, or retention enforcement is included here.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Blob Storage And Blob Ref Helpers
|
||||
|
||||
- Keep `RunBlobId` unchanged in `lib/crates/fabro-types/src/run_blob_id.rs`.
|
||||
- Add a shared blob-ref helper module in `fabro-workflow` or `fabro-types` that:
|
||||
- formats `blob://sha256/<blob_id>`
|
||||
- parses `blob://sha256/<blob_id>`
|
||||
- recognizes legacy blob-backed `file://.../<blob_id>.json`
|
||||
- extracts blob ids from managed materialized blob file paths
|
||||
- Change `fabro-store` blob key construction from `blobs#{run_id}#{blob_id}` to a global key layout such as `blobs#sha256#<blob_id>`.
|
||||
- Update `RunDatabase::write_blob` and `RunDatabase::read_blob` to operate on the global CAS namespace.
|
||||
- Remove blob enumeration from the main architecture path. `list_blobs` should not be part of new feature work; if retained temporarily, it should be treated as legacy/debug-only.
|
||||
|
||||
### 2. Automatic Offload
|
||||
|
||||
- In `lib/crates/fabro-workflow/src/artifact.rs`, change `offload_large_values` so that it:
|
||||
- serializes the JSON value
|
||||
- writes the bytes to CAS through the existing run-store handle
|
||||
- replaces the value with `blob://sha256/<blob_id>`
|
||||
- does not write a host-side cache file
|
||||
- Remove the current assumption that `cache/artifacts/values/{blob_id}.json` is part of the durable contract.
|
||||
- Keep the offload threshold unchanged at 100KB in this pass.
|
||||
|
||||
### 3. Execution-Time Materialization
|
||||
|
||||
- Replace `sync_artifacts_to_env` with an execution-time blob materialization flow that handles both:
|
||||
- new `blob://` refs
|
||||
- existing explicit or legacy `file://` refs
|
||||
- Split this into two responsibilities:
|
||||
- blob resolution and materialization for managed blob refs
|
||||
- existing file-copy behavior for explicit `file://` refs that are not blob-backed
|
||||
- Materialization behavior:
|
||||
- read the blob bytes from CAS
|
||||
- write the JSON bytes into a sandbox-usable file path
|
||||
- return a rewritten execution-local value using `file://<materialized_path>`
|
||||
- Managed materialized paths should use a deterministic layout based on blob id so repeated refs dedupe naturally within an execution.
|
||||
|
||||
### 4. Context And Durable Snapshot Boundaries
|
||||
|
||||
- Introduce a clear split between:
|
||||
- durable context values
|
||||
- execution-local resolved context values
|
||||
- Before handler execution, create a resolved execution view where `blob://` refs are rewritten to materialized `file://` refs.
|
||||
- After handler execution, normalize any managed materialized blob file refs in handler-produced context changes back to `blob://sha256/<blob_id>`.
|
||||
- Compatibility reads should normalize legacy blob-backed `file://.../<blob_id>.json` values to `blob://sha256/<blob_id>` in memory before they enter new durable snapshots.
|
||||
- Update checkpoint creation and checkpoint-completed event emission so they snapshot only durable values, never execution-local materialized paths.
|
||||
- Treat `current.preamble` as runtime-only derived state and exclude it from persisted context snapshots. This prevents preamble strings containing execution-local file paths from leaking into checkpoints or event payloads.
|
||||
|
||||
### 5. Preamble And Handler Execution
|
||||
|
||||
- Keep blobs invisible to the model.
|
||||
- Before fidelity builds `current.preamble`, resolve completed-stage outcome values and current context into an execution-local view that contains file refs, not blob refs.
|
||||
- `build_preamble` should continue to work with file references and should not mention `blob://` or “blobs” in user/model-facing output.
|
||||
- Prompt and agent handlers should continue to consume `context.preamble()` and file references exactly as they do now.
|
||||
- The only new behavior for handlers should be that the file refs they receive come from execution-time materialization rather than from durable checkpoint state.
|
||||
|
||||
### 6. Resume And Fork Behavior
|
||||
|
||||
- Resume should seed durable `blob://` values from checkpoint state and let the next execution hop materialize them as needed.
|
||||
- Legacy checkpoints containing blob-backed `file://.../<blob_id>.json` values should be normalized on read so resumed runs persist the new `blob://` form on the next checkpoint.
|
||||
- Fork should copy checkpoint and run state without copying blob payloads.
|
||||
- Child runs should retain the same `blob://sha256/<blob_id>` refs as the source run.
|
||||
|
||||
### 7. CLI And Export Behavior
|
||||
|
||||
- Update CLI final-output rendering so when `response.*` is a blob ref it resolves the blob through the run-store read path before printing markdown.
|
||||
- Keep explicit non-blob file refs as plain file references in CLI output.
|
||||
- Refactor `store dump` to become reference-driven for blobs:
|
||||
- scan exported JSON structures for blob refs
|
||||
- fetch only referenced blobs
|
||||
- hydrate them inline in exported JSON
|
||||
- stop emitting a top-level `blobs/` directory
|
||||
- Preserve the current export layout for run metadata, nodes, retro output, checkpoints, events, and stage artifacts.
|
||||
|
||||
### 8. Server And API Surface
|
||||
|
||||
- Keep the existing run-scoped blob routes:
|
||||
- `POST /api/v1/runs/{id}/blobs`
|
||||
- `GET /api/v1/runs/{id}/blobs/{blobId}`
|
||||
- Change their implementation to use global CAS storage internally.
|
||||
- Do not add public blob enumeration or global blob-fetch routes in this pass.
|
||||
- Do not add GC or blob-membership verification to the API contract in this pass.
|
||||
|
||||
## Test Plan
|
||||
|
||||
### Blob Ref Helpers
|
||||
|
||||
- parse and format `blob://sha256/<blob_id>`
|
||||
- recognize legacy blob-backed `file://.../<blob_id>.json`
|
||||
- reject ordinary non-blob `file://` refs
|
||||
- normalize managed materialized blob file refs back to blob refs
|
||||
|
||||
### Offload And Persistence
|
||||
|
||||
- large values are replaced with `blob://sha256/<blob_id>`
|
||||
- offload writes the blob bytes to CAS
|
||||
- offload no longer creates a host scratch cache file
|
||||
- small values remain inline
|
||||
- checkpoint and checkpoint-completed payloads persist `blob://` refs, not `file://`
|
||||
- `current.preamble` is excluded from persisted context snapshots
|
||||
|
||||
### Execution Materialization
|
||||
|
||||
- local execution materializes `blob://` refs to local runtime files
|
||||
- remote execution materializes `blob://` refs to sandbox files under `.fabro/blobs/`
|
||||
- preamble generation receives file refs and does not expose `blob://`
|
||||
- handlers receive file refs and can read them normally
|
||||
- explicit non-blob `file://` refs keep their existing remote-copy behavior
|
||||
|
||||
### Normalization And Compatibility
|
||||
|
||||
- handler-produced managed materialized blob file refs are normalized back to `blob://` before checkpointing
|
||||
- legacy blob-backed `file://.../<blob_id>.json` values are normalized to `blob://` on resume
|
||||
- ordinary explicit `file://` refs are preserved as file refs
|
||||
- resumed runs re-checkpoint using only the new `blob://` form
|
||||
|
||||
### Fork, CLI, And Export
|
||||
|
||||
- forked runs reuse the same `blob://sha256/<blob_id>` refs with no blob copy
|
||||
- CLI final-output rendering resolves blob-backed final responses
|
||||
- `store dump` hydrates referenced blobs inline
|
||||
- `store dump` emits no top-level `blobs/` directory
|
||||
|
||||
## Important Files
|
||||
|
||||
- `lib/crates/fabro-workflow/src/artifact.rs`
|
||||
- `lib/crates/fabro-workflow/src/lifecycle/artifact.rs`
|
||||
- `lib/crates/fabro-workflow/src/lifecycle/fidelity.rs`
|
||||
- `lib/crates/fabro-workflow/src/node_handler.rs`
|
||||
- `lib/crates/fabro-workflow/src/handler/llm/preamble.rs`
|
||||
- `lib/crates/fabro-workflow/src/pipeline/execute.rs`
|
||||
- `lib/crates/fabro-workflow/src/records/checkpoint.rs`
|
||||
- `lib/crates/fabro-workflow/src/lifecycle/event.rs`
|
||||
- `lib/crates/fabro-store/src/keys.rs`
|
||||
- `lib/crates/fabro-store/src/slate/run_store.rs`
|
||||
- `lib/crates/fabro-server/src/server.rs`
|
||||
- `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/run/output.rs`
|
||||
- `lib/crates/fabro-workflow/src/run_dump.rs`
|
||||
- `docs/execution/context.mdx`
|
||||
- `docs/agents/outputs.mdx`
|
||||
|
||||
## Assumptions And Defaults
|
||||
|
||||
- The durable blob ref format for this pass is `blob://sha256/<hex>`.
|
||||
- `RunBlobId` remains the current type name even though blobs are no longer run-scoped.
|
||||
- Global CAS uses the existing durable key-value store rather than introducing a new blob backend.
|
||||
- Existing run-scoped blob HTTP routes remain the only supported transport surface in this pass.
|
||||
- Blob lifecycle management and GC are explicitly deferred.
|
||||
|
|
@ -1,390 +0,0 @@
|
|||
---
|
||||
title: "feat: unify interview handling around projected questions, worker stdin, and server-owned Slack"
|
||||
type: feat
|
||||
status: active
|
||||
date: 2026-04-07
|
||||
---
|
||||
|
||||
# feat: unify interview handling around projected questions, worker stdin, and server-owned Slack
|
||||
|
||||
## Overview
|
||||
|
||||
Replace the current split interview architecture with one canonical model:
|
||||
|
||||
- pending interviews live in the durable run projection
|
||||
- answers enter through the server
|
||||
- active runs receive accepted answers through a live control sink
|
||||
- Slack becomes a server-owned delivery surface, not a special in-memory interviewer path
|
||||
|
||||
This refactor removes `FileInterviewer` and `WebInterviewer`, keeps the existing HTTP question and answer routes as the canonical external contract, and uses worker `stdin` JSONL for server-to-worker answer delivery.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Interview handling is currently split across two transport-specific implementations:
|
||||
|
||||
- subprocess runs use `FileInterviewer`, with `interview_request.json` and `interview_response.json` scratch files
|
||||
- the in-process server override path uses `WebInterviewer`, with pending questions and answer waiters held only in memory
|
||||
|
||||
That split leaks into the server:
|
||||
|
||||
- `GET /runs/{id}/questions` branches between `WebInterviewer.pending_questions()` and the request scratch file
|
||||
- `POST /runs/{id}/questions/{qid}/answer` branches between `WebInterviewer.submit_answer()` and the response scratch file
|
||||
- Slack is built on the same special `WebInterviewer` path instead of the canonical server question API
|
||||
|
||||
The result is one feature implemented twice, with two incompatible sources of truth for pending questions and two different answer delivery mechanisms.
|
||||
|
||||
The desired architecture is simpler:
|
||||
|
||||
- the durable run event stream and run projection are authoritative for pending interviews
|
||||
- the server owns answer validation and first-answer-wins behavior
|
||||
- subprocess workers receive accepted answers over `stdin`, which also establishes the future control plane for steering
|
||||
- Slack is just another server-owned client of the canonical answer path
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
In scope:
|
||||
|
||||
- add stable question ids and persist pending interviews in the run projection
|
||||
- replace scratch-file answer transport with worker `stdin` JSONL
|
||||
- replace `WebInterviewer` with the same brokered answer model used by subprocess runs
|
||||
- move Slack onto a single global Socket Mode listener inside `fabro-server`
|
||||
- keep the existing HTTP question and answer routes as the canonical external API
|
||||
- expand the question API payload to expose the information needed by CLI and Slack
|
||||
|
||||
Out of scope:
|
||||
|
||||
- worker-side steering behavior beyond reserving the `stdin` protocol shape for it
|
||||
- server restart rehydration of Slack delivery state
|
||||
- a separate Slack bridge process
|
||||
- signed Slack tokens or tamper-evident action payloads
|
||||
- any new public answer route or worker-side HTTP contract
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Pending interview state must be derived from durable run events and exposed from the run projection, not from scratch files or live interviewer objects.
|
||||
- R2. Every interview question must have a stable `question_id` that survives through events, HTTP APIs, Slack payloads, and worker answer delivery.
|
||||
- R3. `GET /runs/{id}/questions` must read only from canonical projected pending interview state.
|
||||
- R4. `POST /runs/{id}/questions/{qid}/answer` must remain the canonical answer ingress for web, CLI, and Slack.
|
||||
- R5. For subprocess runs, the server must deliver accepted answers to the worker over `stdin` as versioned JSONL.
|
||||
- R6. For the in-process `registry_factory_override` path, the server must still support interview-driven tests without `WebInterviewer`.
|
||||
- R7. `FileInterviewer` and `WebInterviewer` must be removed from production use and then deleted.
|
||||
- R8. Slack must be owned by `fabro-server` as a single global Socket Mode listener, not by per-run workers and not by a separate bridge process.
|
||||
- R9. Slack delivery state may be memory-only. After server restart, stale Slack prompts may be ignored and resumed runs may post fresh prompts under the new server config.
|
||||
- R10. Slack payloads must carry `run_id` and `qid`, and Slack answers must route through the same canonical server answer handler as HTTP.
|
||||
- R11. Multiple-choice and multi-select answers must remain structured end-to-end and must not be flattened to text in the Slack path.
|
||||
- R12. Accepted answers must use first-answer-wins semantics across concurrent HTTP and Slack submissions.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- `Question` gains a first-class `id: String`.
|
||||
- Generate it in the human handler as a ULID string.
|
||||
- Do not hide it in `metadata`.
|
||||
- Do not add a new `QuestionId` wrapper type in this pass.
|
||||
|
||||
- `interview.started` becomes the authoritative pending-question event.
|
||||
- Keep `question` as the human-readable text field.
|
||||
- Add `question_id`, `stage`, `question_type`, `options`, `allow_freeform`, `timeout_seconds`, and `context_display`.
|
||||
|
||||
- `interview.completed` and `interview.timeout` gain `question_id`.
|
||||
|
||||
- Add `interview.interrupted`.
|
||||
- Carry `question_id`, `question`, `stage`, `reason`, and `duration_ms`.
|
||||
- Use it when the interviewer returns `Interrupted`, while `Skipped` flows through `interview.completed`, so pending interview cleanup stays event-driven.
|
||||
|
||||
- `RunProjection` becomes the only source of truth for pending interviews.
|
||||
- Add `pending_interviews: BTreeMap<String, PendingInterviewRecord>`.
|
||||
- Insert on `interview.started`.
|
||||
- Remove on `interview.completed`, `interview.timeout`, `interview.interrupted`, `run.rewound`, and terminal run events.
|
||||
|
||||
- Keep the existing answer route contract.
|
||||
- `GET /runs/{id}/questions` and `POST /runs/{id}/questions/{qid}/answer` remain the public surface.
|
||||
- `SubmitAnswerRequest` already supports freeform, single-select, and multi-select and does not need to change.
|
||||
- Expand `ApiQuestion` with `stage`, `timeout_seconds`, and `context_display`.
|
||||
|
||||
- Server-to-worker answer delivery uses `stdin` JSONL, versioned from day one.
|
||||
- Use one JSON object per line.
|
||||
- Implement only `interview.answer` in this pass.
|
||||
- Reserve the envelope for future steering, but do not implement steering behavior yet.
|
||||
|
||||
- Use a broker-backed interviewer abstraction for both runtime paths.
|
||||
- Replace `FileInterviewer` and `WebInterviewer` with an internal `InterviewBroker` plus `ControlInterviewer`.
|
||||
- For subprocess runs, the broker is fed by parsed `stdin` control messages.
|
||||
- For the in-process override path, the broker is fed directly by the server’s canonical answer submission service.
|
||||
|
||||
- Slack is a server-owned delivery surface, not a worker concern.
|
||||
- Start one Socket Mode listener inside `fabro-server` when both Slack tokens and `slack.default_channel` are configured.
|
||||
- Have that service consume the server's existing global run-event broadcast, the same fanout fed by `forward_run_events_to_global(...)` for both subprocess and in-process runs.
|
||||
- Do not read from SSE endpoints or introduce a second event source.
|
||||
- Keep Slack message metadata and thread routing in server memory only.
|
||||
- Do not replay or restore Slack posts after restart.
|
||||
|
||||
- Slack action payloads use plain JSON in `value`.
|
||||
- Carry at least `run_id`, `qid`, and answer metadata.
|
||||
- Keep `action_id` structural rather than encoding identifiers into it.
|
||||
- Validate all incoming Slack answers against the current projected pending interview before accepting them.
|
||||
|
||||
- `ControlInterviewer` is the runtime `Interviewer` implementation.
|
||||
- `inform()` remains a no-op.
|
||||
- `ask_multiple()` continues to use the trait default, so multiple concurrent `ask()` calls must work correctly when keyed by `qid`.
|
||||
|
||||
- `InterviewBroker` owns only live waiter state.
|
||||
- It does not own canonical pending-question state; `RunProjection.pending_interviews` does.
|
||||
- Its server/transport injection surface is `submit(qid, answer) -> Result<(), SubmitError>`.
|
||||
- Unknown, already-resolved, or duplicate `qid`s are rejected by the broker.
|
||||
|
||||
- Event replay must stay backward compatible.
|
||||
- New interview event fields must deserialize with defaults so old `progress.jsonl` entries still replay.
|
||||
- Historical `interview.started` events that lack `question_id` must not populate `pending_interviews`.
|
||||
- Historical runs continue to replay normally, but projection-backed pending interview reconstruction is only guaranteed for runs created after this change.
|
||||
|
||||
- The old file-claim reattach window is intentionally removed.
|
||||
- Client detach and reattach no longer matter because the pending question is durable in the projection and can be fetched again later.
|
||||
- Only loss of the live server-worker control channel is treated as fatal for the waiting interview.
|
||||
|
||||
- First-answer-wins is enforced in memory before transport delivery.
|
||||
- Projection lookup proves the question is still pending.
|
||||
- A per-run acceptance guard must then claim `qid` exactly once before any answer is sent to the worker.
|
||||
- If transport delivery fails, that claim is released so a later submission can retry.
|
||||
- If transport delivery succeeds, the claim stays until the interview lifecycle event clears the pending question.
|
||||
|
||||
## Recommended Delivery Order
|
||||
|
||||
Recommended sequencing:
|
||||
|
||||
- Phase A: steps 1 and 2 together
|
||||
- lock the question id, event shape, replay compatibility, projection model, and API question shape first
|
||||
|
||||
- Phase B: steps 3, 4, and 5 together
|
||||
- implement `InterviewBroker`, `ControlInterviewer`, canonical answer submission, subprocess `stdin` transport, in-process override migration, and CLI attach adjustments in one pass
|
||||
- steps 3 and 4 should land together because they both restructure the live answer transport in `server.rs`
|
||||
|
||||
- Phase C: step 6
|
||||
- migrate Slack after the canonical pending-question model and answer submission path are stable
|
||||
|
||||
- Phase D: step 7
|
||||
- remove dead implementations, examples, and outdated docs only after the new path is covered by tests
|
||||
|
||||
Parallelizable work after Phase A is in place:
|
||||
|
||||
- worker-side `ControlInterviewer` and JSONL parsing
|
||||
- CLI `ApiQuestion` conversion updates
|
||||
- Slack payload and parsing refactor
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Canonical question ids and interview events
|
||||
|
||||
Update the workflow and event model so the pending interview can be reconstructed without a live transport object.
|
||||
|
||||
- Modify `lib/crates/fabro-interview/src/lib.rs`:
|
||||
- add `Question.id`
|
||||
- keep `metadata` and `default` as internal-only fields
|
||||
- export the new broker-backed interviewer implementation
|
||||
|
||||
- Modify `lib/crates/fabro-workflow/src/handler/human.rs`:
|
||||
- generate `question.id`
|
||||
- emit the richer `interview.started`
|
||||
- emit `interview.interrupted` for `Interrupted`
|
||||
- emit `interview.completed` for `Skipped`
|
||||
- emit `question_id` on `interview.completed` and `interview.timeout`
|
||||
|
||||
- Modify `lib/crates/fabro-workflow/src/event.rs` and `lib/crates/fabro-types/src/run_event/misc.rs`:
|
||||
- extend the interview event variants and payload props to carry the full pending-question surface
|
||||
- keep event names stable except for adding `interview.interrupted`
|
||||
|
||||
### 2. Run projection and API question surface
|
||||
|
||||
Update the store projection and public question API to surface the canonical pending interview state.
|
||||
|
||||
- Modify `lib/crates/fabro-store/src/run_state.rs`:
|
||||
- add `pending_interviews`
|
||||
- add `PendingInterviewRecord`
|
||||
- apply insert and cleanup rules for all interview lifecycle events
|
||||
|
||||
- Modify `docs/api-reference/fabro-api.yaml`:
|
||||
- expand `ApiQuestion` with `stage`, `timeout_seconds`, and `context_display`
|
||||
- leave `SubmitAnswerRequest` unchanged
|
||||
|
||||
- Regenerate generated API clients:
|
||||
- Rust via `cargo build -p fabro-api`
|
||||
- TypeScript via `cd lib/packages/fabro-api-client && bun run generate`
|
||||
|
||||
### 3. Replace file transport with worker `stdin` JSONL
|
||||
|
||||
Replace scratch-file answer delivery with a live control channel into the worker.
|
||||
|
||||
- Add `InterviewBroker` and `ControlInterviewer` in `lib/crates/fabro-interview/src/lib.rs` and supporting modules:
|
||||
- `ControlInterviewer` implements `Interviewer`
|
||||
- `ControlInterviewer::ask(question)` registers a oneshot waiter under `question.id` and awaits broker delivery
|
||||
- `InterviewBroker` owns only live waiter state, such as `HashMap<qid, oneshot::Sender<Answer>>`
|
||||
- `InterviewBroker::submit(qid, answer)` resolves a waiter exactly once and returns a typed error for unknown or already-resolved questions
|
||||
- `inform()` remains a no-op
|
||||
- `ask_multiple()` continues to use the trait default and is supported by allowing concurrent per-`qid` waiters
|
||||
|
||||
- Modify `lib/crates/fabro-server/src/server.rs`:
|
||||
- spawn workers with `stdin(Stdio::piped())`
|
||||
- store a per-run live answer transport instead of a `WebInterviewer`
|
||||
- use a bounded per-run `mpsc::Sender<WorkerControl>` feeding a dedicated JSONL pump into worker stdin
|
||||
- enqueue control messages with a short timeout; if enqueue times out or the channel is closed, clear any acceptance claim and return a transient server error rather than hanging the request
|
||||
- run a JSONL pump that writes accepted answers into the worker stdin pipe
|
||||
- replace the current `get_questions` and `submit_answer` branches with one projection-backed question query plus one internal answer-submission service
|
||||
- implement canonical answer submission in this order:
|
||||
- load the pending question from the projection
|
||||
- validate and build the `Answer`
|
||||
- acquire the per-run acceptance guard and claim `qid` exactly once
|
||||
- submit the answer to the live transport
|
||||
- release the claim on transport failure
|
||||
- keep the claim until interview completion, timeout, or abort clears the pending question
|
||||
- reject a second concurrent submission with `409` once the acceptance guard says the question was already claimed
|
||||
|
||||
- Modify `lib/crates/fabro-cli/src/commands/run/runner.rs`:
|
||||
- replace `FileInterviewer` with `ControlInterviewer`
|
||||
- start a `stdin` reader task that parses versioned JSONL `WorkerControl` messages
|
||||
- resolve broker waiters by `qid`
|
||||
- treat unexpected control-channel closure as interviewer abort/failure rather than hanging forever
|
||||
- keep a dedicated stdin reader task running for the life of the worker so answer messages do not block behind unrelated stage execution
|
||||
|
||||
- Define a wire-specific answer payload.
|
||||
- Do not serialize internal `Answer` directly on the wire.
|
||||
- Use an explicit `kind` shape such as `yes`, `no`, `text`, `selected`, and `multi_selected`.
|
||||
|
||||
- Remove scratch-file interview transport.
|
||||
- delete the request and response file helpers from the server
|
||||
- stop creating or reading `interview_request.json` and `interview_response.json` for server-managed runs
|
||||
- intentionally remove the old claim-file reattach window because pending questions are now projection-backed and re-fetchable after client reconnect
|
||||
|
||||
### 4. Replace `WebInterviewer` in the in-process override path
|
||||
|
||||
Keep the test override path, but move it onto the same architecture as subprocess runs.
|
||||
|
||||
- Modify `lib/crates/fabro-server/src/server.rs`:
|
||||
- replace `ManagedRun.interviewer` with a live answer transport enum such as:
|
||||
- subprocess `stdin` control sender
|
||||
- in-process broker handle
|
||||
- keep `create_app_state_with_registry_factory(...)` and `execute_run_in_process(...)`
|
||||
- pass a broker-backed `Arc<dyn Interviewer>` into the override registry instead of `WebInterviewer`
|
||||
|
||||
- Keep the external behavior unchanged for tests.
|
||||
- `GET /runs/{id}/questions` still lists pending questions
|
||||
- `POST /runs/{id}/questions/{qid}/answer` still satisfies waiting in-process interview gates
|
||||
- the difference is that both now go through the projection and canonical submission service
|
||||
|
||||
### 5. Keep CLI attach on the canonical server question path
|
||||
|
||||
Do not make attach parse the event payload into the prompt directly in this pass.
|
||||
|
||||
- Keep `lib/crates/fabro-cli/src/commands/run/attach.rs` event-driven behavior:
|
||||
- `interview.started` remains the trigger
|
||||
- attach fetches pending questions from the server
|
||||
- attach prompts locally with `ConsoleInterviewer`
|
||||
- attach submits answers through the existing server client
|
||||
|
||||
- Update CLI question conversion for any new `ApiQuestion` fields that should be shown, especially `context_display`.
|
||||
|
||||
### 6. Move Slack onto server-owned canonical answer handling
|
||||
|
||||
Replace the current `WebInterviewer`-centric Slack path with a server-owned integration.
|
||||
|
||||
- Add server-side Slack wiring in `lib/crates/fabro-server/src/server.rs`:
|
||||
- create a single Slack service on startup when both tokens and `slack.default_channel` are configured
|
||||
- subscribe it to the existing `state.global_event_tx` broadcast and filter `interview.started`, `interview.completed`, `interview.timeout`, and `interview.interrupted`
|
||||
- post a Slack message for each fresh pending interview
|
||||
- use completion, timeout, and abort events for best-effort Slack message updates while the in-memory message metadata still exists
|
||||
|
||||
- Refactor `lib/crates/fabro-slack`:
|
||||
- remove `WebInterviewer` dependencies from the Socket Mode connection path
|
||||
- change parsed interactions to carry `run_id` and `qid`
|
||||
- use structural `action_id` values and JSON `value` payloads
|
||||
- preserve structured multiple-choice and multi-select answers
|
||||
- change freeform thread routing from `thread_ts -> question_id` to `thread_ts -> (run_id, qid)`
|
||||
|
||||
- Keep Slack delivery state memory-only inside the server.
|
||||
- store `(run_id, qid) -> posted message metadata`
|
||||
- store `thread_ts -> (run_id, qid)`
|
||||
- after restart, do not rehydrate these maps
|
||||
- reject or ignore stale Slack interactions that no longer match a live pending interview
|
||||
|
||||
- Route Slack answers through the canonical internal answer-submission service.
|
||||
- Slack must not call interviewer objects directly
|
||||
- if the answer is accepted, update the original Slack message when metadata is still present
|
||||
|
||||
### 7. Remove obsolete interview implementations and docs
|
||||
|
||||
After replacement coverage is in place:
|
||||
|
||||
- delete `lib/crates/fabro-interview/src/file.rs`
|
||||
- delete `lib/crates/fabro-interview/src/web.rs`
|
||||
- remove their re-exports from `lib/crates/fabro-interview/src/lib.rs`
|
||||
- delete or rewrite `lib/crates/fabro-slack/examples/slack_e2e.rs`
|
||||
- update `docs/integrations/slack.mdx` so it describes the new server-owned projected-question architecture instead of the old web interviewer model
|
||||
|
||||
## Public Interface Changes
|
||||
|
||||
- `ApiQuestion` adds:
|
||||
- `stage`
|
||||
- `timeout_seconds`
|
||||
- `context_display`
|
||||
|
||||
- `SubmitAnswerRequest` does not change.
|
||||
|
||||
- Run events change as follows:
|
||||
- `interview.started` carries the full pending-question payload
|
||||
- `interview.completed` gains `question_id`
|
||||
- `interview.timeout` gains `question_id`
|
||||
- `interview.interrupted` is new
|
||||
|
||||
- Slack interactive payloads change from `question_id`-only routing to explicit `run_id + qid` routing in the action value payload.
|
||||
|
||||
## Test Plan
|
||||
|
||||
- `fabro-store`
|
||||
- add projection tests for pending interview insert and cleanup
|
||||
- cover `completed`, `timeout`, `interrupted`, rewind, and terminal run cleanup
|
||||
|
||||
- `fabro-workflow`
|
||||
- add handler tests that verify:
|
||||
- generated `question.id`
|
||||
- richer `interview.started`
|
||||
- `interview.interrupted` on `Interrupted`
|
||||
- `interview.completed` on `Skipped`
|
||||
- correlated `question_id` on completion and timeout
|
||||
- old interview events without the new fields still deserialize and replay safely
|
||||
|
||||
- `fabro-interview`
|
||||
- add broker tests for:
|
||||
- waiter registration by `qid`
|
||||
- answer delivery
|
||||
- unknown `qid`
|
||||
- duplicate answer handling
|
||||
- control-channel closure behavior
|
||||
|
||||
- `fabro-server`
|
||||
- add tests that verify:
|
||||
- `GET /runs/{id}/questions` is projection-backed only
|
||||
- `POST /runs/{id}/questions/{qid}/answer` works for both subprocess and in-process runs
|
||||
- first-answer-wins returns success once and `409` thereafter
|
||||
- no interview scratch files are created for server-managed runs
|
||||
- `registry_factory_override` still supports interview-driven tests without `WebInterviewer`
|
||||
- a full-loop integration test covers:
|
||||
- server starts a run with a human gate
|
||||
- worker emits `interview.started`
|
||||
- pending question appears in `GET /runs/{id}/questions`
|
||||
- `POST /runs/{id}/questions/{qid}/answer` succeeds
|
||||
- the server delivers the answer over worker `stdin`
|
||||
- the workflow continues to terminal completion
|
||||
|
||||
- `fabro-slack`
|
||||
- add tests that verify:
|
||||
- button payloads carry `run_id` and `qid`
|
||||
- freeform thread routing uses `(run_id, qid)`
|
||||
- multi-select remains structured
|
||||
- stale interactions are rejected after the pending interview is gone
|
||||
- Slack answers use the same canonical answer-submission service as HTTP
|
||||
|
||||
## Assumptions
|
||||
|
||||
- `Question.metadata` and `Question.default` remain internal runtime fields and are not exposed in `ApiQuestion`.
|
||||
- `context_display` is the only contextual prompt payload exposed externally in this pass.
|
||||
- Slack posts only when both Slack tokens and `slack.default_channel` are configured.
|
||||
- Slack delivery metadata is intentionally ephemeral and may be lost on server restart.
|
||||
- `stdin` JSONL is the long-term worker control plane; this pass only implements interview answers, not steering behavior.
|
||||
|
|
@ -1,121 +0,0 @@
|
|||
# Run Manifest Blobs And Bundle Removal Plan
|
||||
|
||||
## Summary
|
||||
Persist run-definition inputs in CAS-backed blob storage and stop treating scratch as a durable source of workflow definition state.
|
||||
|
||||
This pass stores two durable blob-backed payloads for `/runs` creates:
|
||||
|
||||
- the raw submitted `RunManifest` on `run.created`
|
||||
- the smaller accepted internal run definition on `run.submitted`
|
||||
|
||||
It removes `workflow_bundle.json` from scratch and updates start/resume to load the accepted definition from the run store instead.
|
||||
|
||||
## Key Decisions
|
||||
- Keep the current event sequence.
|
||||
- Do not add a separate `run.accepted` event.
|
||||
- `run.created` carries the raw submitted-manifest blob ref.
|
||||
- `run.submitted` carries the accepted-definition blob ref.
|
||||
- Store the submitted manifest as the exact request-body bytes.
|
||||
- Motivation: preserve the exact wire submission for audit/debugging, not just the parsed semantic content.
|
||||
- Consequence: semantically equivalent JSON bodies with different whitespace or field ordering will produce different blob IDs.
|
||||
- Treat this as greenfield work.
|
||||
- Do not add compatibility fallbacks for older event shapes, older runs, or older scratch layouts.
|
||||
- Do not preserve `workflow_bundle.json` reads or writes behind a migration shim.
|
||||
- Keep `workflow_source` inline on `run.created`.
|
||||
- Cheap projection reads and existing graph-source consumers should continue to work without hydrating a blob.
|
||||
- Rename `StoredWorkflowBundle` to `AcceptedRunDefinition` and make it the durable accepted-definition payload.
|
||||
- Keep the existing data shape (`workflow_path`, `workflows`) and add a `version` field.
|
||||
- Delete the file I/O helpers instead of introducing a second identical type with conversion boilerplate.
|
||||
- Treat the accepted-definition pointer as part of run status state.
|
||||
- Because `run.submitted` is reused by rewind, every `run.submitted` emission must carry the accepted-definition blob ref from run state.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Event and projection types
|
||||
- Update [`lib/crates/fabro-types/src/run_event/run.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-types/src/run_event/run.rs):
|
||||
- add `submitted_manifest_blob: Option<RunBlobId>` to `RunCreatedProps`
|
||||
- replace `RunSubmitted(RunStatusTransitionProps)` with `RunSubmitted(RunSubmittedProps)`
|
||||
- define `RunSubmittedProps { reason: Option<StatusReason>, accepted_definition_blob: Option<RunBlobId> }`
|
||||
- Update [`lib/crates/fabro-types/src/run_event/mod.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-types/src/run_event/mod.rs) and event-name plumbing to use the new `RunSubmittedProps`.
|
||||
- Update [`lib/crates/fabro-types/src/run.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-types/src/run.rs) `RunRecord` with:
|
||||
- `submitted_manifest_blob: Option<RunBlobId>`
|
||||
- `accepted_definition_blob: Option<RunBlobId>`
|
||||
- Update [`lib/crates/fabro-store/src/run_state.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-store/src/run_state.rs):
|
||||
- `run.created` seeds `submitted_manifest_blob`
|
||||
- `run.submitted` updates run status and overwrites `accepted_definition_blob`
|
||||
- `graph_source` continues to come from inline `workflow_source`
|
||||
|
||||
### 2. Durable run-definition blob payloads
|
||||
- Update [`lib/crates/fabro-workflow/src/workflow_bundle.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/workflow_bundle.rs):
|
||||
- rename `StoredWorkflowBundle` to `AcceptedRunDefinition`
|
||||
- add a `version` field
|
||||
- remove `load_from_run_dir()` and any `workflow_bundle.json` file I/O helpers
|
||||
- Keep `BundledWorkflow` and `WorkflowBundle` as runtime types used by execution and child-workflow resolution.
|
||||
- Keep the current constructor/runtime helper surface where useful, but do not add a parallel accepted-definition type or a redundant conversion layer.
|
||||
|
||||
### 3. Server create path and blob persistence
|
||||
- Update [`lib/crates/fabro-server/src/server.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-server/src/server.rs) `POST /runs`:
|
||||
- read the raw request body bytes
|
||||
- deserialize `RunManifest` from those bytes
|
||||
- pass both the typed manifest and the original bytes into workflow creation because this pass intentionally stores the exact submitted JSON bytes
|
||||
- Update [`lib/crates/fabro-workflow/src/operations/create.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/create.rs):
|
||||
- extend `CreateRunInput` with optional raw submitted-manifest bytes
|
||||
- after opening the run store, write the raw manifest bytes to CAS when present
|
||||
- derive the accepted definition from `workflow_path` + `workflow_bundle` and write it to CAS
|
||||
- remove the `persist_workflow_bundle()` call and delete the helper
|
||||
- append `run.created` with `submitted_manifest_blob`
|
||||
- append `run.submitted` with `accepted_definition_blob`
|
||||
- All normal `/runs` creates, including CLI `fabro run` through the server route, should write both blobs.
|
||||
- Direct low-level `CreateRunInput` callers that bypass manifests may omit `submitted_manifest_blob`.
|
||||
- If they still provide `workflow_path` + `workflow_bundle`, they should still get an `accepted_definition_blob`.
|
||||
- Only callers that provide neither manifest bytes nor a bundled workflow definition may leave both refs `None`.
|
||||
|
||||
### 4. Start, resume, and rewind
|
||||
- Update [`lib/crates/fabro-workflow/src/operations/start.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/start.rs):
|
||||
- stop reading `workflow_bundle.json` from `persisted.run_dir()`
|
||||
- load `state.run.accepted_definition_blob`
|
||||
- fetch the accepted-definition bytes through `RunStoreHandle`
|
||||
- deserialize the accepted definition and reconstruct `workflow_path` / `workflow_bundle`
|
||||
- Leave `WorkflowInput::Path` behavior unchanged for truly non-bundled runs that never had an accepted-definition blob.
|
||||
- Update [`lib/crates/fabro-cli/src/commands/run/rewind.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/rewind.rs) so the re-emitted `run.submitted` event includes the current `accepted_definition_blob` from run state.
|
||||
- Keep manager-loop and parallel child-workflow execution unchanged once `EngineServices.workflow_bundle` is hydrated from the accepted-definition blob.
|
||||
|
||||
### 5. Output and documentation cleanup
|
||||
- Update CLI JSON/event rendering paths that special-case empty `run.submitted` properties so they tolerate structured `RunSubmittedProps`:
|
||||
- [`lib/crates/fabro-cli/src/commands/run/logs.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/logs.rs)
|
||||
- [`lib/crates/fabro-cli/src/commands/run/attach.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/attach.rs)
|
||||
- Remove `workflow_bundle.json` from [`docs/reference/run-directory.mdx`](/Users/bhelmkamp/p/fabro-sh/fabro-2/docs/reference/run-directory.mdx).
|
||||
- Update any tests or docs that mention `StoredWorkflowBundle` or scratch-based workflow bundle persistence.
|
||||
|
||||
## Public Interface Changes
|
||||
- Internal event payload shape changes:
|
||||
- `run.created` gains `submitted_manifest_blob`
|
||||
- `run.submitted` now emits structured properties with `reason` and `accepted_definition_blob`
|
||||
- Internal run-state shape changes:
|
||||
- `RunProjection.run` gains `submitted_manifest_blob` and `accepted_definition_blob`
|
||||
- No public `/runs` request-shape change is intended.
|
||||
- No new HTTP routes are required; existing run-scoped blob read/write APIs remain the storage surface.
|
||||
|
||||
## Test Plan
|
||||
- Add create-path coverage in [`lib/crates/fabro-workflow/src/operations/create.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/create.rs):
|
||||
- manifest-backed create writes both blobs
|
||||
- raw submitted-manifest bytes round-trip exactly through CAS
|
||||
- first event is `run.created` with `submitted_manifest_blob`
|
||||
- second event is `run.submitted` with `accepted_definition_blob`
|
||||
- no `workflow_bundle.json` file is written
|
||||
- Add start/resume coverage in [`lib/crates/fabro-workflow/src/operations/start.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-workflow/src/operations/start.rs):
|
||||
- accepted-definition blob hydrates `workflow_bundle`
|
||||
- bundled imports/prompts/child workflows still resolve after original source files are removed
|
||||
- Add projection/event coverage in [`lib/crates/fabro-store/src/run_state.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-store/src/run_state.rs) and event serde tests:
|
||||
- `run.created` stores `submitted_manifest_blob`
|
||||
- `run.submitted` updates `accepted_definition_blob`
|
||||
- serialized/deserialized `RunSubmittedProps` round-trips cleanly
|
||||
- Add rewind coverage in [`lib/crates/fabro-cli/src/commands/run/rewind.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/commands/run/rewind.rs):
|
||||
- rewind re-emits `run.submitted` with the current accepted-definition blob
|
||||
- Update CLI attach/log integration tests so `run.submitted` JSON includes structured properties and still renders correctly.
|
||||
|
||||
## Assumptions
|
||||
- Greenfield strictness is preferred over compatibility padding.
|
||||
- Orphaned manifest/definition blobs are acceptable in this pass; no blob GC work is included.
|
||||
- CAS deduplication limits duplicate growth because identical payloads share blob storage.
|
||||
- The raw submitted-manifest blob is stored exactly as received over HTTP, not by reserializing a typed struct.
|
||||
- The accepted definition is the only durable source used to reconstruct bundled workflow execution state after creation.
|
||||
|
|
@ -1,66 +0,0 @@
|
|||
# Run State Projection Consolidation Plan
|
||||
|
||||
## Summary
|
||||
Consolidate the duplicated CLI and CLI-test run-state projection structs into the canonical read-model types owned by `fabro-store`.
|
||||
|
||||
This pass keeps `RunProjection` and `NodeState` in `fabro-store`, does not move them into `fabro-types`, and does not touch workflow events. The goal is to make the store projection the single source of truth for the `/api/v1/runs/{id}/state` response and for CLI-side consumption of that response.
|
||||
|
||||
## Key Decisions
|
||||
- `fabro_store::RunProjection` and `fabro_store::NodeState` become the only production definitions.
|
||||
- The server response shape remains strict.
|
||||
- Do not add backward-compat aliases, migration shims, or permissive serde fallbacks.
|
||||
- If the server and CLI drift, the build or tests should fail.
|
||||
- `RunProjection` remains a store-owned read model in this pass.
|
||||
- Do not move it into `fabro-types`.
|
||||
- The existing store projection helper surface is the shared API:
|
||||
- `node()`
|
||||
- `iter_nodes()`
|
||||
- `is_empty()`
|
||||
- `list_node_visits()`
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Make the store projection reusable as the client model
|
||||
- Update [`lib/crates/fabro-store/src/run_state.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-store/src/run_state.rs) so `RunProjection` and `NodeState` derive `serde::Deserialize` in addition to their current derives.
|
||||
- Keep the field layout unchanged unless deserialization requires a minimal adjustment for the existing JSON shape.
|
||||
- Keep the current helper methods on `RunProjection` as the public access surface for downstream crates.
|
||||
|
||||
### 2. Remove the duplicated CLI runtime projection
|
||||
- Delete the local `RunProjection` and `NodeState` definitions from [`lib/crates/fabro-cli/src/server_client.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/src/server_client.rs).
|
||||
- Import `fabro_store::RunProjection` instead.
|
||||
- Keep `get_run_state()` structurally simple:
|
||||
- fetch `/api/v1/runs/{id}/state`
|
||||
- deserialize the response into the shared store projection type
|
||||
- Do not recreate projection helper methods in the CLI.
|
||||
|
||||
### 3. Remove the duplicated CLI test projection
|
||||
- Delete the mirrored `RunProjection` and `NodeState` definitions from [`lib/crates/fabro-cli/tests/it/cmd/support.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-cli/tests/it/cmd/support.rs).
|
||||
- Reuse `fabro_store::RunProjection` in test helpers that fetch `/api/v1/runs/{id}/state`.
|
||||
- Rewrite any test call sites that depend on direct `nodes` map access to use the shared projection API instead:
|
||||
- `iter_nodes()`
|
||||
- `node()`
|
||||
- `list_node_visits()`
|
||||
|
||||
### 4. Keep the server boundary unchanged
|
||||
- Leave [`lib/crates/fabro-server/src/server.rs`](/Users/bhelmkamp/p/fabro-sh/fabro-2/lib/crates/fabro-server/src/server.rs) behavior unchanged for `GET /api/v1/runs/{id}/state`.
|
||||
- The endpoint already returns the store projection directly; this pass only removes downstream duplication.
|
||||
|
||||
## Public Interface Changes
|
||||
- No HTTP API shape change is intended.
|
||||
- No `fabro-types` change is intended.
|
||||
- The effective shared contract becomes explicit:
|
||||
- `/api/v1/runs/{id}/state` is represented by `fabro_store::RunProjection`
|
||||
- the CLI no longer maintains a private mirror type for that payload
|
||||
|
||||
## Test Plan
|
||||
- Add a `fabro-store` serde test that deserializes a representative run-state JSON payload into `RunProjection`, including stage-id string keys such as `build@2`.
|
||||
- Add a `fabro-store` round-trip test that serializes and deserializes `RunProjection` and verifies:
|
||||
- `node()` returns the expected node state
|
||||
- `list_node_visits()` returns the expected visit list
|
||||
- Run `cargo nextest run -p fabro-store`.
|
||||
- Run `cargo nextest run -p fabro-cli`.
|
||||
- Confirm existing CLI integration coverage that hits `/api/v1/runs/{id}/state` still passes with the shared projection type.
|
||||
|
||||
## Assumptions
|
||||
- This plan covers only the projection-consolidation pass we discussed, not event cleanup or broader run-state refactors.
|
||||
- Greenfield strictness is preferred over compatibility padding.
|
||||
- `fabro-store` is the correct ownership boundary for this read model in the current architecture.
|
||||
|
|
@ -1,235 +0,0 @@
|
|||
# Store Dump Server-Owned Export Plan
|
||||
|
||||
## Summary
|
||||
|
||||
Align `fabro store dump` with the intended architecture by making it a pure server-backed export command.
|
||||
|
||||
- The CLI should resolve runs from server summaries only.
|
||||
- It should fetch hydrated run state, hydrated event history, and artifacts over HTTP.
|
||||
- It should stop creating a temporary `Database`.
|
||||
- It should stop reading local scratch directories or local storage/object-store paths.
|
||||
- It can keep the current export-style output layout on disk, except blob storage should stay transparent:
|
||||
- top-level metadata files
|
||||
- `nodes/**`
|
||||
- `retro/**`
|
||||
- `events.jsonl`
|
||||
- `checkpoints/**`
|
||||
- `artifacts/**`
|
||||
|
||||
This is a debugging export, not a strict snapshot mechanism. Best-effort consistency is acceptable.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
`fabro store dump` is still implemented as a local store reconstruction flow:
|
||||
|
||||
- it resolves the run through local-storage-aware helpers
|
||||
- it fetches events over HTTP but replays them into an in-memory `fabro_store::Database`
|
||||
- it reads artifacts from local storage directly
|
||||
- it assumes the CLI can see the same storage and scratch directories as the server
|
||||
|
||||
That is now the wrong boundary. The server should own store access; the CLI should only export server-provided run data to disk.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
- `store dump` becomes server-only.
|
||||
- Use `ServerTargetArgs`, not `StorageDirArgs`.
|
||||
- Resolve selectors through `ServerSummaryLookup`, not `ServerRunLookup`.
|
||||
- Do not scan local scratch directories or orphan runs.
|
||||
|
||||
- Keep the current export layout.
|
||||
- It is fine that the command still writes `events.jsonl`, `checkpoints/`, and `artifacts/`.
|
||||
- It should not write a `blobs/` directory.
|
||||
- Blob storage is an internal offload mechanism, not part of the user-facing export model.
|
||||
|
||||
- Do not add blob enumeration.
|
||||
- Blob-backed values should be hydrated server-side before the CLI receives run state or events.
|
||||
- The CLI should not need to understand blob pointer conventions.
|
||||
- The exported files should look as if offloading had never happened.
|
||||
|
||||
- Best-effort race handling is acceptable.
|
||||
- If a blob or artifact is listed/referenced but disappears before download, skip it and continue.
|
||||
- Fail on transport or server errors other than `404`.
|
||||
|
||||
- Event pagination should use the server's `meta.has_more` contract.
|
||||
- Do not stop paging based on "returned fewer than page size".
|
||||
- The client should retain and use pagination metadata from the API response.
|
||||
|
||||
- Artifact downloads should be concurrent with a fixed upper bound.
|
||||
- Use a bounded concurrency strategy such as `JoinSet` or `FuturesUnordered` with a small limit.
|
||||
- Recommended default: `8` concurrent artifact downloads.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Convert `store dump` to standard server targeting
|
||||
|
||||
In `fabro-cli`:
|
||||
|
||||
- change `StoreDumpArgs` to flatten `ServerTargetArgs`
|
||||
- remove `StorageDirArgs` from this command
|
||||
- update help text, docs, and snapshots to show `--server` / `FABRO_SERVER`
|
||||
|
||||
Run resolution should follow the same contract as other server-backed inspection commands:
|
||||
|
||||
1. explicit `--server`
|
||||
2. configured `[server].target`
|
||||
3. default local server instance if no server target is configured
|
||||
|
||||
The command should no longer derive behavior from a local storage dir.
|
||||
|
||||
### 2. Resolve the run from server summaries only
|
||||
|
||||
- replace `ServerRunLookup` usage with `ServerSummaryLookup`
|
||||
- resolve `<RUN>` from server-provided summaries only
|
||||
- remove any dependence on local scratch-path scanning during selector resolution
|
||||
|
||||
This ensures `store dump` works even when the server runs on a different host.
|
||||
|
||||
### 3. Add server/API support for paginated hydrated reads
|
||||
|
||||
The CLI path depends on the server returning enough information to page correctly and to keep blob handling transparent.
|
||||
|
||||
Add or update the server/API contract for:
|
||||
|
||||
- `GET /runs/{id}/state?hydrate_blobs=true`
|
||||
- `GET /runs/{id}/events?...&hydrate_blobs=true`
|
||||
|
||||
Follow the existing OpenAPI-first workflow for these API changes:
|
||||
|
||||
- update `docs/api-reference/fabro-api.yaml`
|
||||
- rebuild Rust API types/client via `cargo build -p fabro-api`
|
||||
- regenerate the TypeScript client in `lib/packages/fabro-api-client`
|
||||
|
||||
Also update the CLI client shape for event listing so pagination metadata is preserved instead of discarded:
|
||||
|
||||
- add a new paginated event-list helper for `store dump` that returns both `data` and `meta.has_more`
|
||||
- keep the existing `list_run_events(...) -> Vec<EventEnvelope>` convenience method in place for current callers unless there is a strong reason to migrate them in the same change
|
||||
- `store dump` must consume the metadata-bearing form
|
||||
|
||||
The existing artifact APIs are already sufficient for this plan:
|
||||
|
||||
- `list_run_artifacts(run_id)`
|
||||
- `download_stage_artifact(run_id, stage_id, filename)`
|
||||
|
||||
No new artifact endpoint work is required here.
|
||||
|
||||
### 4. Add server-side blob hydration for state and events
|
||||
|
||||
Blob storage is intended to be transparent. `store dump` should not detect, enumerate, or hydrate blob pointers in the CLI.
|
||||
|
||||
Recommended API shape:
|
||||
|
||||
- add `hydrate_blobs=true` as an optional query parameter on both endpoints
|
||||
- when omitted or `false`, preserve current behavior
|
||||
- when `true`, the server resolves blob-backed references before serializing the response
|
||||
- reflect those query parameters in the OpenAPI schema and generated clients
|
||||
|
||||
Hydration scope:
|
||||
|
||||
- all blob-backed values inside `RunProjection`
|
||||
- all blob-backed values inside returned event payloads
|
||||
- this includes values that ultimately flow into exported checkpoint JSON because checkpoints come from `RunProjection.checkpoints`
|
||||
|
||||
Hydration mechanism:
|
||||
|
||||
- implement a shared server-side JSON hydrator that walks `serde_json::Value`, detects blob-backed pointer values, reads the referenced blobs from the run store, and replaces the pointer string with the parsed JSON payload
|
||||
- reuse the same helper for both state and event responses so blob resolution rules stay identical
|
||||
- keep the helper server-owned rather than attaching it only to `RunProjection`, because event payloads need the same treatment
|
||||
|
||||
If a referenced blob cannot be resolved during hydrated fetch:
|
||||
|
||||
- treat `404` as a race-tolerant miss
|
||||
- preserve the original pointer value in the hydrated response
|
||||
- fail on non-`404` server/store errors
|
||||
|
||||
This keeps blob knowledge server-owned, which matches the architecture this plan is trying to enforce.
|
||||
|
||||
### 5. Refactor `RunDump` to accept fetched export data instead of store handles
|
||||
|
||||
`RunDump::store_export` currently assumes:
|
||||
|
||||
- a `RunDatabase`
|
||||
- an `ArtifactStore`
|
||||
- store enumeration for blobs and artifacts
|
||||
|
||||
Refactor this into a store-agnostic export builder with a concrete constructor:
|
||||
|
||||
```rust
|
||||
RunDump::from_export(
|
||||
state: &RunProjection,
|
||||
events: &[EventEnvelope],
|
||||
artifacts: &HashMap<(StageId, String), Bytes>,
|
||||
) -> Result<Self>
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `state` is already hydrated
|
||||
- `events` are already hydrated
|
||||
- blobs are not a separate constructor parameter
|
||||
- `artifacts` are the only binary payloads the CLI still fetches explicitly
|
||||
|
||||
The new builder should preserve the current file layout and validation rules:
|
||||
|
||||
- top-level metadata files from `RunProjection`
|
||||
- node files under `nodes/<node>/visit-<n>/`
|
||||
- `retro/prompt.md` and `retro/response.md`
|
||||
- `events.jsonl`
|
||||
- `checkpoints/<seq>.json` sourced directly from `RunProjection.checkpoints`
|
||||
- `artifacts/nodes/<node>/visit-<n>/<relative_path>`
|
||||
|
||||
Keep the existing staged-directory write behavior:
|
||||
|
||||
- reject non-empty output dirs
|
||||
- write into a temp dir under the output parent
|
||||
- rename into place when complete
|
||||
|
||||
### 6. Replace local store reconstruction with HTTP-backed export collection
|
||||
|
||||
In `dump_command`, fetch the export inputs directly from the server:
|
||||
|
||||
- hydrated current run state via `get_run_state(run_id, hydrate_blobs = true)`
|
||||
- full hydrated event history via paginated `list_run_events(run_id, since_seq, limit, hydrate_blobs = true)`
|
||||
- use an explicit page size of `1000`
|
||||
- continue paging based on `meta.has_more`
|
||||
- run artifacts via `list_run_artifacts(run_id)`
|
||||
- artifact contents via `download_stage_artifact(run_id, stage_id, filename)` using bounded concurrency
|
||||
|
||||
Do not:
|
||||
|
||||
- create a `Database`
|
||||
- call `rebuild_run_store`
|
||||
- open a local `ArtifactStore`
|
||||
- read anything under local `storage/` or scratch paths
|
||||
|
||||
### 7. Leave shared event-rebuild helpers for other commands
|
||||
|
||||
`rebuild_run_store` is still used by other commands such as `fork`, `rewind`, and `pr create`.
|
||||
|
||||
- remove it from `store dump`
|
||||
- do not delete it in this change unless those other commands are migrated too
|
||||
|
||||
This plan is specific to aligning `store dump` with server-owned export.
|
||||
|
||||
## Test Plan
|
||||
|
||||
- update the `store dump --help` snapshot for the CLI arg change from `--storage-dir` to `--server`
|
||||
- re-enable the disabled `store dump` integration coverage and make it exercise the server-backed path only
|
||||
- add a regression test for a run with more than 100 events to prove pagination exports the full `events.jsonl`
|
||||
- add a regression test for a run with exactly `1000` events to prove the client performs the additional page fetch and stops on `has_more = false`, not on page-size heuristics
|
||||
- add server/API coverage for hydrated fetches:
|
||||
- hydrated `get_run_state(..., hydrate_blobs = true)` replaces blob-backed pointers with original JSON values
|
||||
- hydrated `list_run_events(..., hydrate_blobs = true)` replaces blob-backed pointers in event payloads
|
||||
- blob `404` during hydration preserves the original pointer value
|
||||
- add coverage that no `blobs/` directory is emitted
|
||||
- add `RunDump` coverage for the new store-agnostic constructor to verify the exported file layout remains unchanged for representative state/events/blobs/artifacts
|
||||
- keep or restore the non-empty output-dir rejection test
|
||||
- add a race-tolerance test where a referenced artifact returns `404` and the export completes without that artifact file
|
||||
- add coverage that artifact downloads run through the bounded-concurrency path without changing output order or file paths
|
||||
|
||||
## Assumptions and Defaults
|
||||
|
||||
- `store dump` should use the standard server-target contract, not `--storage-dir`
|
||||
- the current export file layout is intentionally preserved
|
||||
- blob handling is transparent and server-owned; there is no `blobs/` export directory and no need for a blob-list API
|
||||
- best-effort consistency is sufficient because this command exists for debugging and inspection
|
||||
- the server remains the only component allowed to access the underlying run store in this architecture
|
||||
|
|
@ -1,109 +0,0 @@
|
|||
# Complete Worker HTTP-Only Run Store Migration
|
||||
|
||||
## Summary
|
||||
- Finish the architecture change by removing all `RunDatabase` / SlateDB usage from the detached `fabro __run-worker` path.
|
||||
- Keep the server as the only SlateDB owner and single writer.
|
||||
- Do this with one run-scoped internal runtime abstraction used by workflow execution, plus two implementations:
|
||||
- local adapter for server-side execution and tests
|
||||
- HTTP-backed adapter for detached workers
|
||||
- Let the HTTP-backed worker maintain a write-through in-memory mirror of acknowledged events and projection state so repeated worker-side reads do not turn into unnecessary HTTP round-trips.
|
||||
- Reuse existing server endpoints; no OpenAPI or route changes are required for this migration.
|
||||
|
||||
## Internal Interface Changes
|
||||
- Introduce a small run-scoped async runtime-facing store interface in `fabro-workflow` for the operations the executor actually needs:
|
||||
- `load_state() -> RunProjection`
|
||||
- `list_events() -> Vec<EventEnvelope>`
|
||||
- `append_run_event(&RunEvent) -> ()`
|
||||
- `write_blob(&[u8]) -> RunBlobId`
|
||||
- `read_blob(&RunBlobId) -> Option<Bytes>`
|
||||
- Change workflow execution plumbing to depend on that interface instead of `RunDatabase`:
|
||||
- `StartServices`
|
||||
- `EngineServices`
|
||||
- the pipeline structs and options that currently carry `RunDatabase`
|
||||
- helpers that currently hard-code persisted-load, retro, and finalize store reads
|
||||
- Replace the `RunEventSink::store(RunDatabase)` special case with a backend-based writer so event emission no longer assumes a local SlateDB handle.
|
||||
- Keep the interface scoped to a single run so methods do not need a `RunId` parameter.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Runtime backend abstraction
|
||||
- Add a runtime store backend trait in `fabro-workflow` and migrate the worker-facing execution path to depend on it instead of `RunDatabase`.
|
||||
- Keep the interface narrow and asynchronous, covering only the worker-side behaviors that still depend on store access:
|
||||
- load run projection / run record / graph source
|
||||
- list events
|
||||
- append run events
|
||||
- write blobs
|
||||
- read blobs
|
||||
- Allow the HTTP-backed implementation to keep a write-through in-memory mirror of run state and events, but only update that mirror after the server has acknowledged the write. The server remains canonical; the worker cache is a derived mirror for read efficiency only.
|
||||
- Define failure policy up front:
|
||||
- apply bounded retries to transient HTTP failures
|
||||
- if retries exhaust on a required read or write, fail the worker run with a clear fatal error
|
||||
- do not continue executing after the worker loses the ability to read or write canonical run state
|
||||
|
||||
### 2. Local adapter for server execution
|
||||
- Add a local adapter in `fabro-workflow` that wraps `RunDatabase`.
|
||||
- Keep server-side execution behavior unchanged:
|
||||
- the server still opens the durable `RunDatabase`
|
||||
- the server passes the local adapter into workflow execution
|
||||
- the server remains the only SlateDB owner and single writer in production execution
|
||||
- Keep existing unit and integration tests that rely on in-process `RunDatabase` semantics working through this adapter.
|
||||
|
||||
### 3. HTTP-backed adapter for detached workers
|
||||
- Add an HTTP-backed adapter in `fabro-cli` on top of `ServerStoreClient`.
|
||||
- Extend `ServerStoreClient` with the missing worker-side helpers already supported by the server API:
|
||||
- write run blob
|
||||
- read run blob
|
||||
- get checkpoint only if a migrated path needs a direct checkpoint call rather than `load_state()`
|
||||
- The detached worker should use this adapter for all run-state reads and event/blob writes.
|
||||
- Seed the adapter from the server once at worker startup, then keep its in-memory mirror in sync from acknowledged appends and explicit refetches when needed.
|
||||
|
||||
### 4. Migrate confirmed worker-path reads off `RunDatabase`
|
||||
- Move the confirmed detached-worker call sites to the new backend before deleting any local store construction:
|
||||
- startup validation and persisted-run loading
|
||||
- resume checkpoint loading
|
||||
- retro state and event reads
|
||||
- finalize conclusion building and metadata-finalize reads
|
||||
- artifact blob offload and any worker-path blob reads
|
||||
- git metadata checkpoint and finalize reads that currently load state from the local store
|
||||
- Treat this as a worker-path refactor, not a whole-repo purge of `RunDatabase`.
|
||||
- Explicitly out of scope for this migration:
|
||||
- server supervisor code
|
||||
- server routes and server-local run execution
|
||||
- `store dump` and other separate server-funneling work
|
||||
|
||||
### 5. Remove local worker store usage
|
||||
- After the worker-path reads above are migrated, delete the local seeded in-memory store path from `lib/crates/fabro-cli/src/commands/run/runner.rs`:
|
||||
- remove local `Database::new(InMemory, ..., flush_interval)` construction
|
||||
- remove seeding via `list_run_events()` into a local `RunDatabase`
|
||||
- remove the worker-side `RunEventSink::fanout([store, callback])`
|
||||
- After this change, detached workers send events directly to the server over HTTP and never construct or open any `fabro_store::Database`.
|
||||
|
||||
## Test Plan
|
||||
- Add unit coverage for the new local adapter covering:
|
||||
- state loading
|
||||
- event append
|
||||
- blob write behavior
|
||||
- blob read behavior
|
||||
- Add focused unit coverage for the HTTP-backed adapter covering:
|
||||
- write-through projection and event cache updates after acknowledged appends
|
||||
- bounded retry behavior
|
||||
- fatal failure when required HTTP reads or writes keep failing
|
||||
- Add focused CLI and worker tests proving detached execution still works for:
|
||||
- start
|
||||
- resume
|
||||
- cancel / ctrl-c
|
||||
- human gate handling
|
||||
- large context value blob offload
|
||||
- Add a regression test that would have failed under the old design:
|
||||
- detached worker event delivery is no longer paced by a local worker-side store append
|
||||
- `dry_run_simple` no longer shows the `~100ms` per-event cadence caused by the worker’s local store path
|
||||
- Add a regression test that the detached worker path no longer constructs a local `fabro_store::Database`.
|
||||
- Keep existing server execution tests green to prove the local adapter preserved current semantics.
|
||||
|
||||
## Assumptions and Defaults
|
||||
- No public HTTP API changes are needed for this migration; existing run state, event, checkpoint, blob, and artifact routes are sufficient.
|
||||
- The runtime backend is scoped to a single run, matching detached-worker execution semantics.
|
||||
- The HTTP-backed worker cache is a derived mirror updated only after successful server acknowledgements; it does not make the worker a second source of truth.
|
||||
- While a detached worker is executing, it is assumed to be the sole emitter of run events for that run; if server-originated events are later added to the live run stream, the cache model will need an explicit invalidation or subscription mechanism.
|
||||
- The detached worker must have zero direct SlateDB access after this change.
|
||||
- The server remains the only component allowed to own a `RunDatabase` in production execution.
|
||||
- This should land as one coherent migration, not as a partial compatibility phase, because the current mixed model is both architecturally wrong and performance-visible.
|
||||
|
|
@ -1,339 +0,0 @@
|
|||
---
|
||||
title: "feat: Add `fabro uninstall` command"
|
||||
type: feat
|
||||
status: completed
|
||||
date: 2026-04-08
|
||||
origin: docs/ideation/2026-04-08-fabro-uninstall-ideation.md
|
||||
deepened: 2026-04-08
|
||||
---
|
||||
|
||||
# feat: Add `fabro uninstall` command
|
||||
|
||||
## Overview
|
||||
|
||||
Add a `fabro uninstall` top-level CLI command that reverses the effects of `fabro install` and `install.sh`. The command stops a running server, removes the `~/.fabro/` directory tree, cleans shell config PATH entries, and handles binary self-removal. Defaults to dry-run (preview) mode, requiring `--yes` to execute.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
There is no supported way to uninstall Fabro. Users must manually `rm -rf ~/.fabro`, hunt for stale PATH entries in their shell configs, and figure out how to stop the server. This creates friction, erodes trust, and leaves detritus after uninstall.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Remove the `~/.fabro/` directory and all contents
|
||||
- R2. Stop a running server before removing files
|
||||
- R3. Remove `# fabro` PATH lines from shell configs (.zshrc, .bashrc, .bash_profile, .config/fish/config.fish)
|
||||
- R4. Default to dry-run with size reporting; require `--yes` to execute
|
||||
- R5. Delete the binary when installed via `install.sh` to `~/.fabro/bin/`; print a hint otherwise
|
||||
- R6. Support `--json` output for scriptability
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No selective/component uninstall (users can back up manually)
|
||||
- No GitHub App deregistration via API
|
||||
- No export/backup archive feature
|
||||
- No telemetry farewell event
|
||||
- No per-repo cascade cleanup (repos can be cleaned individually via `fabro repo deinit`)
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-cli/src/commands/install.rs` — what `fabro install` creates (settings.toml, certs/, secrets.json)
|
||||
- `apps/marketing/public/install.sh` — what the shell installer creates (binary at `~/.fabro/bin/fabro`, PATH lines with `# fabro` sentinel)
|
||||
- `lib/crates/fabro-cli/src/commands/server/stop.rs` — `execute(storage_dir, timeout)`: SIGTERM, poll, SIGKILL, record+socket cleanup
|
||||
- `lib/crates/fabro-cli/src/commands/server/record.rs` — `active_server_record_details()` for detecting running server
|
||||
- `lib/crates/fabro-cli/src/commands/system/prune.rs` — dry-run-by-default pattern with `--yes`, size reporting via `format_size()`
|
||||
- `lib/crates/fabro-cli/src/commands/repo/deinit.rs` — cleanup command pattern: green checkmarks, NotFound tolerance, `Vec<String>` return, `--json` support
|
||||
- `lib/crates/fabro-util/src/home.rs` — `Home` struct with all path accessors (`root()`, `certs_dir()`, `storage_dir()`, etc.)
|
||||
- `lib/crates/fabro-config/src/storage.rs` — `Storage` struct with storage path accessors
|
||||
- `lib/crates/fabro-cli/src/args.rs` — `Commands` enum for command registration, `Commands::name()` for telemetry
|
||||
- `lib/crates/fabro-cli/src/commands/upgrade.rs` — `std::env::current_exe()?.canonicalize()?` for binary path detection
|
||||
- `lib/crates/fabro-config/src/user_config.rs` — `load_settings()` for resolving effective configuration including non-default `storage_dir`
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
No `docs/solutions/` directory exists. No prior learnings on install/uninstall patterns.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Top-level command, not subcommand of `system`**: Matches `install`/`upgrade` placement. Users will search for `fabro uninstall` — discoverability matters. (see origin: docs/ideation/2026-04-08-fabro-uninstall-ideation.md)
|
||||
- **`--yes` confirmation model (not `--dry-run`)**: Matches `system prune` pattern — destructive operations default to preview. The flag name `--yes` is already established in the codebase.
|
||||
- **Use `Home::from_env()` as the canonical root**: Respects `$FABRO_HOME` for non-default installations. Never hardcode `~/.fabro/`.
|
||||
- **Shell config cleanup uses exact `# fabro` sentinel match**: The `install.sh` script writes `# fabro` as a marker comment before the PATH export. Match with `line.trim() == "# fabro"` (exact match, not substring) to avoid deleting unrelated lines like `# fabro workflow helper`. After matching the sentinel, validate that the following line matches an expected PATH pattern (`export PATH=` or `fish_add_path`) before removing it — this prevents accidentally deleting an innocent line if the file was manually edited.
|
||||
- **Binary path resolved during inventory, not after deletion**: `std::env::current_exe()?.canonicalize()?` must be called during the inventory phase (Unit 2) and stored. On macOS, `canonicalize()` fails with `NotFound` after the file is deleted by `remove_dir_all`. The stored path is used later by Unit 5.
|
||||
- **Binary self-deletion is the final step**: On Unix, unlinking a running binary works (the inode stays alive until the process exits). Must be absolutely last since nothing can run after the binary is gone.
|
||||
- **Do not call `stop::execute()` without a guard**: `server::stop::execute()` calls `std::process::exit(1)` when no server is running. The uninstall command must check `record::active_server_record_details()` first and only call `stop::execute()` when a server is confirmed running.
|
||||
- **Resolve `storage_dir` through settings, not just `Home`**: If `settings.toml` configures a non-default `storage_dir`, the server record lives at that custom path. Load effective settings via `user_config::load_settings()` during inventory to resolve the actual `storage_dir`.
|
||||
- **Compute-once inventory**: The inventory is built once (Unit 2) and consumed by all subsequent units. No step should re-detect artifacts during execution — the directory may already be partially deleted.
|
||||
- **Exit code policy**: Exit 0 only if all critical steps (server stop, directory removal) succeeded. Exit 1 if any critical step failed. Shell config cleanup and binary handling failures warn but do not affect the exit code.
|
||||
- **Synchronous implementation**: Server stop logic (`stop::execute`) is synchronous. The uninstall function itself should be async (matching the dispatch pattern in main.rs) but can call sync helpers.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Should uninstall clean up shell configs that `fabro install` (Rust) didn't create?** Yes — `install.sh` creates them, and the user experience of "uninstall" should reverse the full installation, not just the Rust command's portion.
|
||||
- **What if the server won't stop?** Follow the existing SIGTERM→SIGKILL pattern from `server/stop.rs`. If SIGKILL fails (shouldn't happen on Unix), warn and continue with removal.
|
||||
|
||||
- **Should the dry-run preview show active workflow run count?** Yes — if the server is running with in-flight workflows, stopping it will terminate them. The preview should report the count so users can make an informed decision. The run count can be obtained from the server API if available, or noted as "server running (active runs unknown)" if the API is unreachable.
|
||||
- **What about `$ZDOTDIR` mismatch between install and uninstall time?** If the user's `$ZDOTDIR` was set differently at install time versus uninstall time, the uninstall will look in the wrong file. This is an inherent limitation — document it but do not try to solve it.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Fish shell syntax differences**: `fish_add_path` vs `export PATH=` — the removal logic needs shell-specific handling. Determine exact patterns during implementation.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Command registration and skeleton**
|
||||
|
||||
**Goal:** Register `fabro uninstall` as a top-level CLI command with args parsing.
|
||||
|
||||
**Requirements:** R4, R6
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs`
|
||||
- Create: `lib/crates/fabro-cli/src/commands/uninstall.rs`
|
||||
|
||||
**Approach:**
|
||||
- Add `UninstallArgs` struct with `--yes` bool field (clap attribute: `#[arg(long)]`)
|
||||
- Add `Uninstall(UninstallArgs)` variant to `Commands` enum with doc comment `/// Uninstall Fabro from this machine`
|
||||
- Add `Self::Uninstall(_) => "uninstall"` to `Commands::name()`
|
||||
- Add `pub(crate) mod uninstall;` to `commands/mod.rs`
|
||||
- Add dispatch arm in main.rs calling `commands::uninstall::run_uninstall(&args, &globals).await?`
|
||||
- Skeleton `run_uninstall` that prints "not yet implemented" and returns Ok
|
||||
|
||||
**Patterns to follow:**
|
||||
- `InstallArgs` struct and `Commands::Install` variant in `args.rs`
|
||||
- Dispatch pattern in `main.rs` (line ~176)
|
||||
- Module declaration pattern in `commands/mod.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `fabro uninstall --help` outputs usage text including `--yes` flag description
|
||||
- Happy path: `fabro uninstall` (no args) parses successfully and runs the skeleton
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-cli` succeeds
|
||||
- `fabro uninstall --help` shows the expected usage
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2: Inventory and dry-run preview**
|
||||
|
||||
**Goal:** Discover all Fabro artifacts on the system, compute sizes, and display a preview manifest. When `--yes` is not passed, this is the complete behavior.
|
||||
|
||||
**Requirements:** R1, R2, R3, R4, R5, R6
|
||||
|
||||
**Dependencies:** Unit 1
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
|
||||
|
||||
**Approach:**
|
||||
- Use `Home::from_env()` to resolve the root directory
|
||||
- Check if `Home::root()` exists; if not, print "Fabro is not installed" and exit 0 (skip settings loading entirely)
|
||||
- If home exists, attempt to load effective settings via `user_config::load_settings()` to resolve actual `storage_dir`. If settings loading fails (e.g., settings.toml missing or corrupt), fall back to `Home::from_env().storage_dir()` — this handles partial installs and repeated uninstall attempts
|
||||
- Build an inventory struct containing all information needed by subsequent units:
|
||||
- `home_root`: resolved Home root path
|
||||
- `storage_dir`: resolved storage directory path
|
||||
- `home_exists`: whether the home directory exists
|
||||
- `home_size`: total size of home directory (recursive walk)
|
||||
- `server_running`: whether a server is detected via `record::active_server_record_details(&storage_dir)`
|
||||
- `shell_configs`: list of shell config file paths that contain the `# fabro` sentinel (exact match: `line.trim() == "# fabro"`)
|
||||
- `binary_path`: resolved path from `std::env::current_exe()?.canonicalize()?` (must be resolved NOW, before any deletion)
|
||||
- `binary_is_managed`: whether `binary_path` starts with `home_root`
|
||||
- Shell config files to scan: `$ZDOTDIR/.zshrc` or `~/.zshrc`, `~/.bashrc`, `~/.bash_profile`, `~/.config/fish/config.fish`
|
||||
- In dry-run mode (no `--yes`): print each item that would be removed with its size, including active run warning if server is running, then print `"Pass --yes to confirm."` summary
|
||||
- Support `--json` output: serialize inventory as JSON to stdout
|
||||
- Follow the `system prune` output style for human-readable format
|
||||
|
||||
**Patterns to follow:**
|
||||
- `system prune` dry-run output format ("would delete: ...", "N item(s) would be deleted (X freed)")
|
||||
- `format_size()` for human-readable byte formatting
|
||||
- `console::Style` / `Styles::detect_stderr()` for colored output
|
||||
- `GlobalArgs.json` check for JSON vs human output
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: preview with populated `~/.fabro/` lists all directories and files with sizes
|
||||
- Happy path: preview with `--json` outputs structured JSON to stdout
|
||||
- Edge case: `~/.fabro/` does not exist — prints "Fabro is not installed" and exits cleanly
|
||||
- Edge case: shell config files exist but contain no fabro lines — omitted from preview
|
||||
- Edge case: binary is not in `~/.fabro/bin/` — preview notes it must be removed manually
|
||||
- Happy path: running server detected — preview notes it will be stopped and warns about active runs
|
||||
- Edge case: `current_exe()` or `canonicalize()` fails — inventory stores `None` for binary path, warns in preview
|
||||
|
||||
**Verification:**
|
||||
- `fabro uninstall` (no `--yes`) prints a complete manifest and does NOT delete anything
|
||||
- `fabro uninstall --json` outputs valid JSON with inventory details
|
||||
- Preview accurately reflects what exists on disk
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 3: Server shutdown and directory removal**
|
||||
|
||||
**Goal:** When `--yes` is passed, stop a running server and remove `~/.fabro/` and all contents.
|
||||
|
||||
**Requirements:** R1, R2
|
||||
|
||||
**Dependencies:** Unit 2
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/uninstall.rs`
|
||||
|
||||
**Approach:**
|
||||
- Use the inventory's `server_running` and `storage_dir` fields (computed in Unit 2)
|
||||
- **Critical**: Only call `server::stop::execute()` when `inventory.server_running` is true. `stop::execute()` calls `std::process::exit(1)` when no server is found — calling it unconditionally would terminate the process before any cleanup happens.
|
||||
- If running, call `server::stop::execute(&inventory.storage_dir, Duration::from_secs(5))`
|
||||
- If not running, skip with no error
|
||||
- **Safety guardrail before deletion**: Validate `inventory.home_root` is reasonable before calling `remove_dir_all`. Refuse to proceed if the resolved path is a filesystem root (`/`), the user's home directory (`$HOME`), or does not contain an expected marker file (e.g., `settings.toml` or `certs/`). This prevents catastrophic data loss from a misconfigured `$FABRO_HOME`.
|
||||
- After validation, remove `inventory.home_root` with `std::fs::remove_dir_all`
|
||||
- If `storage_dir` differs from the default and is outside `home_root`, validate it contains Fabro artifacts (e.g., `secrets.json` or `store/`) before removing
|
||||
- Handle `ErrorKind::NotFound` gracefully (already uninstalled)
|
||||
- Report each step with green checkmark output following `deinit.rs` pattern
|
||||
- The `fabro.sock` socket file is inside `~/.fabro/` so it's removed as part of the directory deletion
|
||||
|
||||
**Patterns to follow:**
|
||||
- `server::stop::execute()` for server shutdown (call ONLY when server is confirmed running)
|
||||
- `record::active_server_record_details()` for server detection (already done in inventory)
|
||||
- `deinit.rs` checkmark output pattern
|
||||
- `RunScratch::remove()` for NotFound tolerance
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: with `--yes` and no running server, `~/.fabro/` is removed successfully
|
||||
- Happy path: with `--yes` and running server, server is stopped before removal
|
||||
- Edge case: `~/.fabro/` does not exist — reports "nothing to remove" without error
|
||||
- Error path: server stop fails (SIGKILL also fails) — warns and continues with removal
|
||||
- Error path: `$FABRO_HOME` set to `/` — refuses to delete, prints error
|
||||
- Error path: `$FABRO_HOME` set to `$HOME` — refuses to delete, prints error
|
||||
- Error path: `$FABRO_HOME` points to a directory without Fabro marker files — refuses to delete
|
||||
- Integration: after removal, `~/.fabro/` directory does not exist on disk
|
||||
|
||||
**Verification:**
|
||||
- `fabro uninstall --yes` removes `~/.fabro/` completely
|
||||
- A running server is stopped before file removal
|
||||
- No orphaned processes remain after uninstall
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 4: Shell config cleanup**
|
||||
|
||||
**Goal:** Remove PATH lines that `install.sh` added to shell configuration files, using the `# fabro` sentinel comment.
|
||||
|
||||
**Requirements:** R3
|
||||
|
||||
**Dependencies:** Unit 2 (uses shell config detection from inventory)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/uninstall.rs`
|
||||
|
||||
**Approach:**
|
||||
- Use the inventory's `shell_configs` list (detected in Unit 2)
|
||||
- For each shell config file in the list:
|
||||
- Read the file contents
|
||||
- Find lines where `line.trim() == "# fabro"` (exact match, not substring — avoids matching `# fabro workflow helper`)
|
||||
- Validate that the following line matches an expected PATH pattern before removing it:
|
||||
- zsh/bash: following line starts with `export PATH=`
|
||||
- fish: following line starts with `fish_add_path`
|
||||
- If the following line does NOT match, remove only the sentinel line (defensive — the file was manually edited)
|
||||
- Remove the sentinel line AND the validated following line
|
||||
- Write the modified contents back
|
||||
- Handle edge cases: sentinel at end of file, multiple sentinels, sentinel with no following line
|
||||
- Report each modified file with the deinit checkmark pattern
|
||||
- If a shell config file is not found or has no fabro lines, skip silently
|
||||
|
||||
**Patterns to follow:**
|
||||
- `deinit.rs` reporting pattern (green checkmarks per item)
|
||||
- **Atomic write pattern**: Write modified content to a temporary file in the same directory, then `std::fs::rename()` over the original (atomic on POSIX). This prevents a truncated/corrupt dotfile if the process crashes mid-write. Check `std::fs::symlink_metadata()` before modifying — if the file is a symlink, follow it (matching `std::fs::read_to_string` behavior) but note this in output so users with dotfile managers are aware.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `.zshrc` with `# fabro` + PATH line — both lines removed, rest of file intact
|
||||
- Happy path: `.bashrc` with `# fabro` + PATH line — both lines removed
|
||||
- Happy path: `.bash_profile` with `# fabro` + PATH line — both lines removed
|
||||
- Happy path: `config.fish` with `# fabro` + `fish_add_path` — both lines removed
|
||||
- Edge case: shell config exists but has no `# fabro` line — file is not modified
|
||||
- Edge case: shell config file does not exist — no error
|
||||
- Edge case: `# fabro` is the last line in the file (no following PATH line) — only sentinel line removed
|
||||
- Edge case: multiple `# fabro` blocks in the same file — all are removed
|
||||
- Edge case: `# fabro` followed by an unrelated line (not PATH export) — only sentinel removed, following line preserved
|
||||
- Edge case: line contains `# fabro` as substring (`# fabro-related`) — not matched, file unchanged
|
||||
- Integration: after cleanup, opening a new shell does not add fabro to PATH
|
||||
|
||||
**Verification:**
|
||||
- Shell config files have fabro lines removed without corrupting other content
|
||||
- Files without fabro lines are not modified (mtime unchanged)
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 5: Binary status reporting and final output**
|
||||
|
||||
**Goal:** Report whether the binary was already removed (managed install) or print a removal hint (external install). Print final summary.
|
||||
|
||||
**Requirements:** R5
|
||||
|
||||
**Dependencies:** Unit 3 (must run after directory removal)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/uninstall.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/uninstall.rs`
|
||||
|
||||
**Approach:**
|
||||
- Use the inventory's pre-resolved `binary_path` and `binary_is_managed` fields (resolved in Unit 2 before any deletion — `canonicalize()` fails on macOS after the file is deleted)
|
||||
- If `binary_is_managed` is true: the binary was inside `~/.fabro/bin/` and was already removed by Unit 3's `remove_dir_all` — report as removed
|
||||
- If `binary_is_managed` is false: print a tailored hint
|
||||
- Check if path contains `/Cellar/` (Homebrew): "run `brew uninstall fabro`"
|
||||
- Check if path contains `.cargo/bin/` (cargo): "run `cargo uninstall fabro`"
|
||||
- Otherwise: "The fabro binary at {path} must be removed manually."
|
||||
- If `binary_path` is `None` (resolution failed in Unit 2): warn and skip
|
||||
- Print final summary: "Fabro has been uninstalled." (bold, to stderr)
|
||||
- For `--json` output: include `binary_removed` and `binary_hint` fields
|
||||
|
||||
**Patterns to follow:**
|
||||
- `deinit.rs` final summary line pattern (bold text)
|
||||
- Package manager path detection is heuristic — keep it simple
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: binary was in `~/.fabro/bin/` and was already removed by directory deletion — reports binary removed
|
||||
- Happy path: binary is in `/opt/homebrew/Cellar/` — prints "run `brew uninstall fabro`" hint
|
||||
- Happy path: binary is in `~/.cargo/bin/` — prints "run `cargo uninstall fabro`" hint
|
||||
- Edge case: binary path detection fails (`current_exe()` error) — warns but does not fail the overall uninstall
|
||||
- Happy path: final summary message is printed after all steps complete
|
||||
|
||||
**Verification:**
|
||||
- When binary was installed via `install.sh`, it is deleted or confirmed deleted
|
||||
- When binary was installed via other means, a clear removal instruction is printed
|
||||
- `fabro uninstall --yes --json` outputs valid JSON including inventory, execution results, and binary status
|
||||
- The command exits successfully after all steps
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** The uninstall command interacts with: `server::stop` (server lifecycle), `Home`/`Storage` (path resolution), shell config files (external to fabro), and the running binary itself. No callbacks, middleware, or observers are affected.
|
||||
- **Error propagation:** Each step warns on failure but continues. Critical steps (server stop, directory removal) affect the exit code (exit 1 on failure). Non-critical steps (shell config, binary) warn only. A partial uninstall is better than aborting on the first error.
|
||||
- **State lifecycle risks:** Stopping the server terminates in-flight workflow runs — the dry-run preview warns about this. Mitigated by mandatory server stop as the first step (prevents filesystem corruption) and by defaulting to dry-run (gives user a chance to see the warning before committing).
|
||||
- **API surface parity:** No API endpoint equivalent needed — uninstall is a local-only operation.
|
||||
- **Unchanged invariants:** `fabro install`, `fabro server`, `fabro repo deinit`, and `system prune` are not modified by this plan. The uninstall command reuses their code but does not change their behavior.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Shell config surgery corrupts user's dotfiles | Use sentinel-based detection (not regex on PATH content). Only remove exact `# fabro` + next line. Write tests with realistic file content. |
|
||||
| Binary self-deletion race condition | Delete binary as the absolute last step. On Unix, unlink of a running binary is safe (inode persists until process exits). |
|
||||
| `$FABRO_HOME` set to dangerous path (`/`, `$HOME`) | Safety guardrail: validate resolved path is not a root or home dir, and contains expected marker files, before `remove_dir_all`. |
|
||||
| Server stop timeout blocks uninstall | Use a short timeout (5s). SIGKILL as fallback. Continue with removal even if stop fails. |
|
||||
| `stop::execute()` exits process when no server found | Guard with `active_server_record_details()` check; never call `stop::execute()` unconditionally. |
|
||||
| `canonicalize()` fails after file deletion on macOS | Resolve binary path during inventory phase (Unit 2), before any deletion occurs. |
|
||||
| Non-default `storage_dir` in settings.toml | Load settings during inventory to resolve actual storage_dir; don't assume it's inside `~/.fabro/`. |
|
||||
| `$ZDOTDIR` differs between install and uninstall time | Known limitation — document it. Uninstall uses current `$ZDOTDIR`. |
|
||||
| Partial `remove_dir_all` failure (locked files on macOS) | Warn and report which files remain. Exit 1. User can retry or manually remove. |
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin document:** [docs/ideation/2026-04-08-fabro-uninstall-ideation.md](docs/ideation/2026-04-08-fabro-uninstall-ideation.md)
|
||||
- Related code: `lib/crates/fabro-cli/src/commands/install.rs`, `lib/crates/fabro-cli/src/commands/server/stop.rs`, `lib/crates/fabro-cli/src/commands/system/prune.rs`, `lib/crates/fabro-cli/src/commands/repo/deinit.rs`
|
||||
- Related code: `lib/crates/fabro-util/src/home.rs`, `lib/crates/fabro-config/src/storage.rs`
|
||||
- Related code: `apps/marketing/public/install.sh`
|
||||
|
|
@ -1,160 +0,0 @@
|
|||
# CLI CommandContext And Server Access Refactor Plan
|
||||
|
||||
## Summary
|
||||
Refactor `fabro-cli` around an invocation-scoped `CommandContext` that centralizes local settings loading and server connection setup for user-facing server-backed commands. This is a greenfield codebase with no backward-compatibility constraints, so the refactor should be done in one full pass for the in-scope command surface rather than preserving a long-lived mixed model. Keep config-layer composition command-local where commands genuinely need it, keep the generated `fabro_api::Client` as the main HTTP interface, and reuse the existing `ServerStoreClient` type instead of layering a second handwritten endpoint facade on top of it.
|
||||
|
||||
## Public Types And Interfaces
|
||||
- Add eager, invocation-scoped `CommandContext`:
|
||||
- Holds `cwd`, `base_config_path`, `machine_settings`, `server_mode`, and a cached server client cell.
|
||||
- `cwd` is the invocation working directory and replaces repeated inline `std::env::current_dir()` lookups in migrated commands such as `preflight`, `validate`, `graph`, `fabro settings`, and workflow-oriented run creation paths.
|
||||
- `base_config_path` is the local settings file path chosen by `--config`, `FABRO_CONFIG`, or the default path.
|
||||
- `machine_settings` is the result of the existing local settings loaders for the command:
|
||||
- base settings for commands using `load_settings()`
|
||||
- base settings plus storage-dir override for commands using `load_settings_with_storage_dir(...)`
|
||||
- `machine_settings` does not include workflow or project config layers.
|
||||
- Do not store `ConfigLayer` on `CommandContext`.
|
||||
- Keep config-layer composition command-local:
|
||||
- `fabro settings` continues to build `EffectiveSettingsLayers` with its existing helpers.
|
||||
- workflow and manifest code continues to use `ConfigLayer::for_workflow(...)`, `discover_project_config(...)`, and existing workflow resolution structs where individual layers matter.
|
||||
- `CommandContext` should not attempt to reconstruct or cache workflow/project config layers.
|
||||
- Use two explicit server access modes that match the real connection paths in the codebase:
|
||||
- `ServerMode::None`
|
||||
- `ServerMode::ByTarget { target_override: Option<String> }`
|
||||
- `ServerMode::ByStorageDir { target_override: Option<String>, storage_dir_override: Option<PathBuf> }`
|
||||
- `ByTarget` maps to the current `connect_server_only(...)` behavior.
|
||||
- `ByTarget` also covers the current `ServerSummaryLookup::connect(...)` resolution path used by run, pr, runs, and artifact lookup commands.
|
||||
- `ByStorageDir` maps to the current `connect_server_backed_api_client_with_storage_dir(...)` behavior when a real storage-dir-aware connection mode is needed.
|
||||
- current callers of `connect_server_backed_api_client(...)` migrate to `ByTarget` in this refactor because their existing `None` storage-dir path collapses to the same local settings load as `connect_server_only(...)`.
|
||||
- Do not collapse these two behaviors into one variant with optional target and storage fields.
|
||||
- Reuse existing target concepts instead of introducing a second target enum:
|
||||
- keep `ServerTargetArgs`, `ServerConnectionArgs`, and the resolved `ServerTarget` model already used by `user_config` and `server_client`
|
||||
- do not introduce `ServerTargetInput` in this pass
|
||||
- Keep `ServerStoreClient`:
|
||||
- do not rename it during the same refactor
|
||||
- add narrow accessors as needed for:
|
||||
- the generated `fabro_api::Client`
|
||||
- raw `reqwest::Client`
|
||||
- `base_url`
|
||||
- this preserves the current `exec` adapter path without adding a second server session type
|
||||
- `CommandContext::server().await?`:
|
||||
- available only for `ServerMode::ByTarget` and `ServerMode::ByStorageDir`
|
||||
- returns `Arc<ServerStoreClient>`
|
||||
- caches the first successful connection in a `OnceCell`
|
||||
- does not cache failures; a later retry should attempt a fresh connection
|
||||
- `ByTarget` performs current target-based resolution and Unix-socket auto-start behavior
|
||||
- `ByStorageDir` performs current storage-dir-backed daemon resolution and startup behavior
|
||||
- to make both modes uniform, refactor the current storage-dir-backed path, which now returns a bare `fabro_api::Client`, to construct a `ServerStoreClient` first and expose the generated client through an accessor
|
||||
- migrated connection logic must use `machine_settings` and `base_config_path` already loaded on `CommandContext`; it should stop re-calling `load_settings()` and `load_settings_with_storage_dir(...)` inside `server_client.rs`
|
||||
- HTTP and HTTPS targets never auto-start
|
||||
- Keep the existing run-summary lookup pattern, but separate lookup construction from connection:
|
||||
- add `ServerSummaryLookup::from_client(client: Arc<ServerStoreClient>) -> Result<Self>`
|
||||
- make the existing `ServerSummaryLookup::connect(...)` a compatibility wrapper during migration, then remove direct call sites from migrated commands
|
||||
- migrated commands that currently do `ServerSummaryLookup::connect(...)` should instead do `ServerSummaryLookup::from_client(ctx.server().await?)`
|
||||
- this keeps summary listing, sorting, and selector resolution behavior intact while moving connection ownership into `CommandContext`
|
||||
|
||||
## Implementation Changes
|
||||
- Keep `main` bootstrap ordering intact:
|
||||
- continue loading enough local settings before tracing init to determine log level and upgrade-check behavior
|
||||
- `CommandContext` begins after tracing is initialized; it does not replace that earlier bootstrap phase
|
||||
- Do not introduce `Services` in this pass:
|
||||
- the current review surfaced that a `Services` wrapper does not pull enough independent process-scoped concerns to justify the extra indirection
|
||||
- if a later refactor reveals multiple real process-scoped services, add that separately
|
||||
- Keep style construction local for now:
|
||||
- several current command paths still rely on `&'static Styles`
|
||||
- this refactor should not add a style ownership change on top of settings/server wiring cleanup
|
||||
- Make `map_api_error` deduplication a firm deliverable:
|
||||
- migrated commands should reuse the shared `server_client::map_api_error`
|
||||
- remove remaining verbatim local copies in the in-scope command surface
|
||||
- Implement in this order:
|
||||
- Step 1: add `CommandContext`, `ServerMode`, `ctx.server()` caching semantics, convert the storage-dir-backed connect path to construct `ServerStoreClient`, add `ServerSummaryLookup::from_client(...)`, and thread preloaded `machine_settings` / `base_config_path` into server resolution so migrated commands stop re-loading settings inside connection helpers
|
||||
- Step 2: migrate the workflow-oriented server commands:
|
||||
- the main `run` command in [`commands/run/command.rs`](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/commands/run/command.rs)
|
||||
- `run create`
|
||||
- `run start`
|
||||
- `run attach`
|
||||
- `run diff`
|
||||
- `run logs`
|
||||
- `run preview`
|
||||
- `run ssh`
|
||||
- `run resume`
|
||||
- `run rewind`
|
||||
- `run fork`
|
||||
- `run wait`
|
||||
- `run cp`
|
||||
- include the existing internal create → start → attach chain where multiple settings loads and server connects exist today
|
||||
- `preflight`
|
||||
- `validate`
|
||||
- `graph`
|
||||
- Step 3: migrate the remaining user-facing commands that use target-based resolution or resolved-target lookup:
|
||||
- `model`
|
||||
- `secret`
|
||||
- `provider login`
|
||||
- `repo init`
|
||||
- `doctor`
|
||||
- `pr` (treat separately inside this step because it mixes settings for app ID and `ServerSummaryLookup::connect`)
|
||||
- `runs`
|
||||
- `artifact`
|
||||
- these commands should use `ServerMode::ByTarget` after migration, even when they currently call `connect_server_backed_api_client(...)`, because their existing `None` storage-dir path collapses to the same local settings load as `connect_server_only(...)`
|
||||
- Step 4: migrate the user-facing commands that genuinely resolve through a storage-dir-aware server mode:
|
||||
- `system info`
|
||||
- `system df`
|
||||
- `system events`
|
||||
- `system prune`
|
||||
- these commands should use `ServerMode::ByStorageDir`
|
||||
- Step 5: adapt `fabro settings` to use `CommandContext` only for base local settings inputs while keeping its existing layer-building and effective-settings logic
|
||||
- Step 6: remove obsolete helper entrypoints from migrated call sites and reduce `server_client.rs` to the minimal shared surface still needed by explicit out-of-scope and internal commands:
|
||||
- migrated commands should stop calling `connect_server_only(...)`, `connect_server_backed_api_client(...)`, `connect_server_backed_api_client_with_storage_dir(...)`, and `ServerSummaryLookup::connect(...)` directly
|
||||
- migrated commands that need run lookup/resolve behavior should use `ServerSummaryLookup::from_client(ctx.server().await?)`
|
||||
- keep `connect_server(...)`, `connect_api_client(...)`, and `connect_server_target_direct(...)` only for direct storage-dir or direct-target flows that remain explicit out-of-scope or internal
|
||||
- Stage dependencies:
|
||||
- Steps 2, 3, and 4 all depend on Step 1
|
||||
- Step 5 depends on Step 1 but not on the migration of other command groups
|
||||
- Step 6 happens only after the other steps are complete
|
||||
- Explicitly out of scope:
|
||||
- `exec`
|
||||
- `server` lifecycle commands
|
||||
- hidden `run worker`
|
||||
- `store dump`
|
||||
- `workflow`
|
||||
- `parse`
|
||||
- `repo deinit`
|
||||
- `install`
|
||||
- `sandbox`
|
||||
- `upgrade`
|
||||
- hidden analytics and panic upload commands
|
||||
- direct storage-dir run lookup flows, including `ServerRunLookup`, remain unchanged in this pass
|
||||
- Cleanup target after the pass:
|
||||
- the remaining old helper surface should exist only for those explicitly out-of-scope or internal commands
|
||||
- migrated user-facing commands should no longer call settings loaders or top-level server connect helpers directly
|
||||
|
||||
## Test Plan
|
||||
- New unit tests for `CommandContext` construction:
|
||||
- base config path precedence remains `--config` > `FABRO_CONFIG` > default path (`$FABRO_HOME/settings.toml` if `FABRO_HOME` is set, else `$HOME/.fabro/settings.toml`)
|
||||
- missing default base config path is allowed; missing explicit config path still errors
|
||||
- `machine_settings` reflect only the command's existing local settings load path:
|
||||
- base settings for target-based commands
|
||||
- base settings plus storage-dir override for storage-backed commands
|
||||
- New unit tests for server access modes:
|
||||
- `ServerMode::ByTarget` matches current target-based resolution
|
||||
- `ServerMode::ByStorageDir` matches current storage-dir-backed resolution
|
||||
- Unix-socket targets may auto-start; HTTP and HTTPS targets never auto-start
|
||||
- `ctx.server()` caches a successful client and retries after failures
|
||||
- Existing regression coverage that must keep passing for config-layer commands:
|
||||
- workflow and manifest code still layer workflow and project config exactly as before
|
||||
- `fabro settings` local, daemon, and remote effective-settings modes remain unchanged
|
||||
- Existing regression coverage that must keep passing for special cases:
|
||||
- `exec` with no explicit server target still runs directly against providers
|
||||
- `exec` with an explicit server target still constructs the server-backed adapter path correctly using `ServerStoreClient` accessors
|
||||
- Existing integration coverage that must keep passing for migrated command groups:
|
||||
- Step 2: the main `run` command, `run create`, `run start`, `run attach`, `run diff`, `run logs`, `run preview`, `run ssh`, `run resume`, `run rewind`, `run fork`, `run wait`, `run cp`, `preflight`, `validate`, and `graph`
|
||||
- Step 3: representative `model`, `secret`, `provider login`, `repo init`, `doctor`, `pr`, `artifact`, and `runs` commands
|
||||
- Step 4: representative `system info`, `system df`, `system events`, and `system prune` commands
|
||||
- Step 5: `fabro settings` base-settings-input path adopted from `CommandContext` while layer-building and effective-settings logic stay unchanged
|
||||
|
||||
## Assumptions And Defaults
|
||||
- This is a greenfield codebase with no production compatibility constraints, so one full-pass refactor across the in-scope user-facing command surface is acceptable.
|
||||
- `CommandContext` is for shared local settings loading and server access only; it is not a universal repository for every config layer or every command concern.
|
||||
- Commands that need workflow/project layering continue to compute those layers locally from the existing config helpers.
|
||||
- `ServerStoreClient` remains the shared server connection type in this pass and may gain accessors, but not a second handwritten endpoint layer.
|
||||
- `exec` remains outside the main abstraction because it still has a real direct-provider fallback mode that is different from normal server-backed commands.
|
||||
- "Resolved path" means the same path shape produced by current helpers: expanded and made absolute where the helpers already do so, but not canonicalized in a way that would require the file to exist.
|
||||
|
|
@ -1,134 +0,0 @@
|
|||
# Fabro SPA Asset Crate Plan
|
||||
|
||||
## Summary
|
||||
Create a new internal crate, `fabro-spa`, as the runtime source of truth for the production web bundle. The crate will contain committed built assets and expose a narrow asset API backed by `rust-embed` with compression and include/exclude filtering. This removes Bun/Node from Cargo builds, release builds, and runtime, while preserving the current low-complexity local workflow: `fabro server start` plus `cd apps/fabro-web && bun run dev`, with browser refreshes picking up rebuilt files.
|
||||
|
||||
## Key Decisions
|
||||
- Commit the production bundle in `lib/crates/fabro-spa/assets`.
|
||||
- This is the explicit tradeoff for keeping Bun out of Cargo builds, release builds, and runtime. A CI-only asset build would keep the release path coupled to Bun, which is the dependency boundary this plan is trying to remove.
|
||||
- Repo growth is accepted in exchange for a fully self-contained Rust release artifact. Mitigations in this plan are: no sourcemaps, generated-asset `.gitattributes`, a `15 MB` committed-asset size budget, and a separate `5 MB` embedded-payload budget.
|
||||
- Keep Bun as an authoring/build-time tool only.
|
||||
- Do not add Bun to Rust CI or release builds.
|
||||
- Do not add HMR or a separate browser dev server in this pass.
|
||||
- `fabro-spa` returns plain file bytes, not content-encoded payloads.
|
||||
- `rust-embed` compression is an implementation detail inside the crate.
|
||||
- The `fabro-server` caller should continue to receive normal file bytes for MIME detection and response body construction.
|
||||
- Define refresh-script idempotency as: running the refresh script twice on unchanged frontend source produces no git diff under `lib/crates/fabro-spa/assets`.
|
||||
- Keep debug disk fallback anchored to `env!("CARGO_MANIFEST_DIR")`, matching the current server behavior.
|
||||
- Do not make path resolution depend on cwd.
|
||||
- Do not add a new env var override in this iteration.
|
||||
|
||||
## Implementation Changes
|
||||
### 1. Package the production SPA in `fabro-spa`
|
||||
- Add `lib/crates/fabro-spa` with a committed `assets/` directory populated from `apps/fabro-web/dist`.
|
||||
- In `fabro-spa`, use `rust-embed` with:
|
||||
- `compression`
|
||||
- `include-exclude`
|
||||
- `deterministic-timestamps` if needed to keep embedded metadata stable across identical rebuilds
|
||||
- Exclude sourcemaps in two places:
|
||||
- the refresh script must not copy any `*.map` files into `fabro-spa/assets`
|
||||
- the embed definition must also exclude `*.map` and `**/*.map`
|
||||
- Keep the crate API narrow and owned by `fabro-spa`.
|
||||
- Expose `get(path: &str) -> Option<AssetBytes>` where `AssetBytes` is a crate-local wrapper around the underlying bytes.
|
||||
- `AssetBytes` should provide access to the normal file bytes only; it must not expose `rust-embed` types or compression details.
|
||||
- Do not add `iter()` in v1. If tests need enumeration, add a dedicated test-only helper later.
|
||||
|
||||
### 2. Move `fabro-server` to consume `fabro-spa`
|
||||
- Replace the direct `RustEmbed` usage in `lib/crates/fabro-server/src/static_files.rs` with calls into `fabro-spa`.
|
||||
- Preserve existing server behavior:
|
||||
- SPA fallback to `index.html`
|
||||
- MIME detection in the server
|
||||
- current cache-control behavior for hashed assets vs entry/root assets
|
||||
- Preserve low-friction local development by keeping a debug-only disk override.
|
||||
- In debug builds, first check `apps/fabro-web/dist/<path>` on disk using a path derived from `env!("CARGO_MANIFEST_DIR")`.
|
||||
- If the file exists, serve it directly.
|
||||
- Otherwise fall back to the embedded `fabro-spa` asset.
|
||||
- Remove the current Bun-based release build hook in `lib/crates/fabro-server/build.rs`.
|
||||
- Remove the direct `rust-embed` dependency from `fabro-server` once the embed lives entirely in `fabro-spa`.
|
||||
|
||||
### 3. Keep the current Bun authoring/build path
|
||||
- Keep `apps/fabro-web` as the authoring app and keep the existing custom Bun production build script.
|
||||
- Keep `bun run dev` as the watch-and-rebuild command, with no HMR or browser dev server added in this pass.
|
||||
- The local workflow remains:
|
||||
- run `fabro server start`
|
||||
- run `cd apps/fabro-web && bun run dev`
|
||||
- refresh the browser manually after rebuilds
|
||||
- Do not add a Rust-side dev proxy, a frontend HMR server, or a bundler migration in this iteration.
|
||||
|
||||
### 4. Add an explicit asset refresh workflow
|
||||
- Add a repo-level refresh command, `scripts/refresh-fabro-spa.sh`.
|
||||
- The script should:
|
||||
- run the existing web production build in `apps/fabro-web`
|
||||
- fully replace `lib/crates/fabro-spa/assets` rather than incrementally syncing it
|
||||
- copy only shippable files from `dist`
|
||||
- exclude all sourcemaps
|
||||
- Treat git state as the source of idempotency truth.
|
||||
- Two consecutive runs on unchanged frontend source must leave no git diff under `lib/crates/fabro-spa/assets`.
|
||||
- Timestamps in the filesystem do not matter; only committed file content and paths matter.
|
||||
- Make this script the only supported way to update committed SPA assets.
|
||||
|
||||
### 5. Add repo hygiene and CI guardrails
|
||||
- Add `.gitattributes` entries for `lib/crates/fabro-spa/assets/**`.
|
||||
- Mark the directory as generated for repository tooling.
|
||||
- Suppress noisy diffs for minified hashed bundles.
|
||||
- Do not use Git LFS in v1 unless the committed asset size proves unmanageable.
|
||||
- Add a size budget check for `lib/crates/fabro-spa/assets`.
|
||||
- Fail CI if total committed asset size exceeds `15 MB` without an explicit budget update.
|
||||
- This budget is intentionally above the current no-sourcemap bundle size, which is about `12.3 MB` in the current branch, so the initial implementation passes with modest headroom.
|
||||
- Add a separate embedded-payload budget check for the release binary.
|
||||
- Fail CI or release verification if the estimated compressed `fabro-spa` asset payload exceeds `5 MB` without an explicit budget update.
|
||||
- This budget is intentionally above the current estimated compressed payload, which is about `2.8 MB` in the current branch, so the initial implementation passes with meaningful headroom.
|
||||
- Include a release-build smoke check so accidental asset over-inclusion is visible before merge.
|
||||
- Keep drift verification in Bun-capable CI, not Rust CI.
|
||||
- Update the TypeScript workflow to run the refresh script and fail if it leaves a diff under `lib/crates/fabro-spa/assets`.
|
||||
- Expand that workflow's path coverage to include both `apps/fabro-web/**` and `lib/crates/fabro-spa/**`.
|
||||
- Treat this freshness job as the authoritative stale-asset check for frontend changes.
|
||||
- Leave the Rust/release workflows Bun-free.
|
||||
|
||||
### 6. Update docs around the new split
|
||||
- Update docs that currently say `bun run dev` serves the app on port `5173`; they should instead describe the watch-build plus manual-refresh flow against `fabro server start`.
|
||||
- Update architecture/deployment docs that imply `fabro-server` builds frontend assets during release.
|
||||
- Document the new refresh step for contributors who change `apps/fabro-web`.
|
||||
|
||||
## Interfaces And Workflow Changes
|
||||
- New internal crate: `lib/crates/fabro-spa`
|
||||
- Removed implicit build coupling: `cargo build` and release builds must no longer invoke Bun
|
||||
- No HTTP API changes
|
||||
- No new public CLI flags or env vars in this iteration
|
||||
- New developer-maintained artifact boundary:
|
||||
- `apps/fabro-web` remains source code
|
||||
- `lib/crates/fabro-spa/assets` becomes committed runtime bundle output
|
||||
|
||||
## Test Plan
|
||||
- Add server tests covering:
|
||||
- embedded asset serving when no disk bundle is present
|
||||
- debug disk override when `apps/fabro-web/dist` contains a rebuilt file
|
||||
- SPA fallback to `index.html` for unknown client routes
|
||||
- immutable cache headers for hashed assets
|
||||
- no-cache headers for entry/root assets
|
||||
- `.map` files are not served
|
||||
- Add refresh-script verification covering:
|
||||
- running the refresh script twice without source changes produces no git diff
|
||||
- asset replacement strips sourcemaps reliably
|
||||
- the committed asset directory stays under the `15 MB` size budget
|
||||
- Add release-build verification covering:
|
||||
- `cargo build --release` succeeds without Bun installed
|
||||
- the estimated compressed embedded asset payload stays under the `5 MB` budget
|
||||
- the resulting binary size is recorded during CI/manual verification so the measured end-to-end delta is visible
|
||||
- Run:
|
||||
- `cd apps/fabro-web && bun run build`
|
||||
- the refresh script
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo build --release`
|
||||
- Manual smoke check:
|
||||
- start the Rust server
|
||||
- run `cd apps/fabro-web && bun run dev`
|
||||
- change a UI file
|
||||
- confirm the rebuilt asset is served after a browser refresh
|
||||
|
||||
## Assumptions
|
||||
- The production bundle is intentionally committed to `lib/crates/fabro-spa/assets` to preserve Bun-free Cargo and release builds.
|
||||
- Sourcemaps are not shipped in the binary and are not copied into the asset crate.
|
||||
- Local web development accepts manual refresh; no HMR/dev server is part of this plan.
|
||||
- Bun remains a frontend authoring/build-time dependency only; it is removed from runtime, Cargo build, and release requirements.
|
||||
- A future bundler migration or HMR setup is explicitly deferred rather than partially introduced here.
|
||||
|
|
@ -1,97 +0,0 @@
|
|||
# Optional Web UI for `fabro server` Plan
|
||||
|
||||
## Summary
|
||||
Make the Fabro server able to run in two surfaces:
|
||||
|
||||
- API-only
|
||||
- API + web UI
|
||||
|
||||
The always-on surface is `/health` plus the machine API under `/api/v1`. The web surface includes the embedded SPA fallback, browser auth routes under `/auth/*`, and the browser-session/setup/demo helper endpoints that currently live under `/api/v1` in `web_auth::api_routes()`:
|
||||
|
||||
- `/api/v1/auth/me`
|
||||
- `/api/v1/setup/register`
|
||||
- `/api/v1/setup/status`
|
||||
- `/api/v1/demo/toggle`
|
||||
|
||||
When the web UI is disabled, all of those web-surface routes return `404`, even when they live under `/api/v1`. API-only mode is a routing change only; it does not remove the embedded SPA from the binary.
|
||||
|
||||
Operator control should use both config and CLI:
|
||||
|
||||
- Add `web.enabled` to server settings
|
||||
- Add `--web` / `--no-web` startup overrides
|
||||
- Precedence: CLI override > config > default
|
||||
- Default: web UI enabled
|
||||
|
||||
## Key Changes
|
||||
### Config and CLI surface
|
||||
- Extend the existing `[web]` config section with `enabled`.
|
||||
- Add `enabled: Option<bool>` to the config model and `enabled: bool` to resolved settings, defaulting to `true`.
|
||||
- Add mutually exclusive `--web` and `--no-web` flags to server startup args.
|
||||
- Define merge behavior explicitly: combine `WebConfig` sources first with last-non-`None` wins for `enabled`, then materialize resolved `WebSettings.enabled`, then apply the CLI override last.
|
||||
- Apply the flags in the same resolved-settings pass that already handles other serve-time overrides.
|
||||
- Update help text and docs to describe the new toggle and its precedence.
|
||||
|
||||
### Router composition
|
||||
- Refactor server router construction so the machine API, web surface, and health surface are composed separately.
|
||||
- Keep these always mounted:
|
||||
- machine API routes under `/api/v1`, excluding the routes currently provided by `web_auth::api_routes()`
|
||||
- `/health`
|
||||
- Treat these as web-only routes, even when they live under `/api/v1`:
|
||||
- `/api/v1/auth/me`
|
||||
- `/api/v1/setup/register`
|
||||
- `/api/v1/setup/status`
|
||||
- `/api/v1/demo/toggle`
|
||||
- `/auth/*`
|
||||
- SPA/static fallback for non-API `GET`/`HEAD`
|
||||
- The current SPA is served from the fallback closure, not a mounted router. In API-only mode, that fallback closure must return `404` for all non-API, non-health routes instead of serving the SPA.
|
||||
- In API-only mode, disable the browser-oriented demo/session behavior as well:
|
||||
- `/api/v1/demo/toggle` returns `404`
|
||||
- cookie-driven and `X-Fabro-Demo` header demo dispatch do not route requests into the auth-disabled demo router
|
||||
- requests use only the normal machine API router plus `/health`
|
||||
- When the web UI is enabled, preserve current browser session, setup, and demo-cookie behavior.
|
||||
|
||||
### Internal interface changes
|
||||
- Thread a resolved `web_enabled` boolean into router construction.
|
||||
- Prefer making this explicit in the server boundary, for example by extending `build_router(...)` with a surface/options argument, rather than re-reading settings inside the router.
|
||||
- `build_router(state, auth_mode)` has a broad test blast radius. Minimize churn by introducing a small `RouterOptions`-style parameter or helper wrapper so tests that do not care about web surface toggling can keep using the default-enabled path.
|
||||
- Keep the decision centralized in startup/resolution code so tests can build routers deterministically.
|
||||
|
||||
## Test Plan
|
||||
- Router tests:
|
||||
- web enabled: `GET /` serves SPA
|
||||
- web enabled: `/auth/*` remains available
|
||||
- web enabled: `/api/v1/auth/me`, `/api/v1/setup/status`, and `/api/v1/demo/toggle` keep their current behavior
|
||||
- web disabled: `GET /` returns `404`
|
||||
- web disabled: client routes like `/runs/abc` return `404`
|
||||
- web disabled: `/auth/*` returns `404`
|
||||
- web disabled: `/api/v1/auth/me`, `/api/v1/setup/register`, `/api/v1/setup/status`, and `/api/v1/demo/toggle` return `404`
|
||||
- web disabled: representative machine API endpoints still work
|
||||
- web disabled: cookie-driven or `X-Fabro-Demo` requests do not enter auth-disabled demo dispatch
|
||||
- `/health` still works in both modes
|
||||
- CLI/config tests:
|
||||
- default startup serves web UI
|
||||
- config `web.enabled = false` disables the UI
|
||||
- `--web` overrides config-disabled to enable
|
||||
- `--no-web` overrides config-enabled/default to disable
|
||||
- help snapshots include `--web` and `--no-web`
|
||||
- Regression coverage:
|
||||
- existing source-map/static routing tests still pass in enabled mode
|
||||
- existing server lifecycle tests still pass with default behavior unchanged
|
||||
|
||||
## Docs and User-Facing Behavior
|
||||
- Update CLI docs for `fabro server start` to describe `--web` / `--no-web`.
|
||||
- Update server configuration docs to document `[web].enabled`.
|
||||
- Update deploy/architecture docs so “server mode” no longer implies the web UI is always present.
|
||||
- Call out that “web UI disabled” means:
|
||||
- no `/auth/*`
|
||||
- no web-session/setup/demo helper endpoints under `/api/v1`
|
||||
- no SPA fallback at `/` or client routes
|
||||
- machine API and `/health` only
|
||||
- embedded SPA assets are still compiled into the binary; this is not a build-time exclusion
|
||||
|
||||
## Assumptions and Defaults
|
||||
- Default remains web UI enabled.
|
||||
- CLI flags are `--web` and `--no-web`.
|
||||
- CLI override precedence is standard: CLI > config > default.
|
||||
- Disabling the web UI is strictly an HTTP-surface change; it does not disable workflow execution, machine API behavior, or server-owned background services.
|
||||
- No OpenAPI/API schema changes are needed, since this only changes route availability and classification within the existing server.
|
||||
|
|
@ -1,269 +0,0 @@
|
|||
# Production Web UI Test Plan
|
||||
|
||||
## Harness requirements
|
||||
|
||||
### 1. Rust HTTP integration harness (existing)
|
||||
|
||||
- **What it does:** Sends HTTP requests to the fabro server via `tower::ServiceExt::oneshot()` against an in-memory `AppState`. No network, no boot overhead.
|
||||
- **What it exposes:** Full request/response cycle including headers, status codes, JSON bodies. Direct mutation of `AppState` (e.g., setting run status) for precondition setup.
|
||||
- **Estimated complexity:** Already exists (`lib/crates/fabro-server/tests/it/helpers.rs`). Provides `test_app_state()`, `build_router()`, `body_json()`, `create_and_start_run()`, `api()`, etc.
|
||||
- **Which tests depend on it:** Tests 1-6
|
||||
|
||||
### 2. Playwright browser harness (new -- must be built)
|
||||
|
||||
- **What it does:** Launches a real browser against a running fabro server that serves the built SPA. Exercises the full stack: React app fetching real HTTP endpoints, rendering real DOM, cookies for demo mode.
|
||||
- **What it exposes:** Page navigation, DOM element inspection, cookie management, screenshot capture, click/interaction simulation.
|
||||
- **Estimated complexity:** Moderate. Requires:
|
||||
1. Install `@playwright/test` as a dev dependency in `apps/fabro-web`
|
||||
2. Create `apps/fabro-web/tests/playwright.config.ts` with `webServer` config that builds the SPA and starts the fabro server with `AuthMode::Disabled` and in-memory store
|
||||
3. The server already serves the built SPA when `FABRO_STATIC_DIR` is configured. Auth disabled mode returns a synthetic user from `/auth/me`.
|
||||
- **Which tests depend on it:** Tests 7-14
|
||||
|
||||
### 3. TypeScript unit test harness (existing)
|
||||
|
||||
- **What it does:** Runs bun tests for pure TypeScript functions and React component logic.
|
||||
- **What it exposes:** Direct function calls, React `renderToString` for context providers.
|
||||
- **Estimated complexity:** Already exists (`bun test`).
|
||||
- **Which tests depend on it:** Tests 15-18
|
||||
|
||||
---
|
||||
|
||||
## Test plan
|
||||
|
||||
### Test 1: Demo `/boards/runs` returns RunListItem-shaped data
|
||||
|
||||
- **Name:** Requesting the runs board in demo mode returns run list items with repository, title, workflow, and board column status
|
||||
- **Type:** integration
|
||||
- **Disposition:** new
|
||||
- **Harness:** Rust HTTP integration harness
|
||||
- **Preconditions:** Server initialized with `AuthMode::Disabled`. Demo header `X-Fabro-Demo: 1` set on request.
|
||||
- **Actions:** `GET /api/v1/boards/runs` with `X-Fabro-Demo: 1` header
|
||||
- **Expected outcome:** HTTP 200. Response body has `data` array. First item has string `id`, object `repository` (with `name`), string `title`, object `workflow` (with `slug`), string `status` that is one of `"working"`, `"pending"`, `"review"`, `"merge"`, and string `created_at`. Source of truth: OpenAPI spec `PaginatedRunList` schema and plan Decision 2.
|
||||
- **Interactions:** Demo data module (`demo/mod.rs` `runs::list_items()`)
|
||||
|
||||
### Test 2: Demo `GET /runs/{id}` returns StoreRunSummary shape (not RunStatusResponse)
|
||||
|
||||
- **Name:** Requesting a single run in demo mode returns the StoreRunSummary shape with run_id, goal, and workflow fields instead of the old RunStatusResponse shape
|
||||
- **Type:** integration
|
||||
- **Disposition:** new
|
||||
- **Harness:** Rust HTTP integration harness
|
||||
- **Preconditions:** Server initialized with `AuthMode::Disabled`. Demo header set. Run ID "run-1" exists in demo data.
|
||||
- **Actions:** `GET /api/v1/runs/run-1` with `X-Fabro-Demo: 1` header
|
||||
- **Expected outcome:** HTTP 200. Body has `run_id` (string), `goal` (string), `workflow_slug` (string), `workflow_name` (string), `host_repo_path` (string), `status` (string), `duration_ms` (number or null). Body does NOT have `queue_position` field. Source of truth: OpenAPI spec `StoreRunSummary` schema and plan Decision 3.
|
||||
- **Interactions:** Demo data module
|
||||
|
||||
### Test 3: Demo `GET /runs/{id}` returns 404 for unknown run
|
||||
|
||||
- **Name:** Requesting a nonexistent run in demo mode returns 404
|
||||
- **Type:** boundary
|
||||
- **Disposition:** new
|
||||
- **Harness:** Rust HTTP integration harness
|
||||
- **Preconditions:** Server initialized with `AuthMode::Disabled`. Demo header set.
|
||||
- **Actions:** `GET /api/v1/runs/nonexistent-run-id` with `X-Fabro-Demo: 1` header
|
||||
- **Expected outcome:** HTTP 404. Source of truth: OpenAPI spec 404 error response.
|
||||
- **Interactions:** Demo data module
|
||||
|
||||
### Test 4: Real `/boards/runs` returns RunListItem shape with board columns
|
||||
|
||||
- **Name:** Requesting the runs board in production mode returns enriched run list items with board column statuses instead of lifecycle statuses
|
||||
- **Type:** integration
|
||||
- **Disposition:** new
|
||||
- **Harness:** Rust HTTP integration harness
|
||||
- **Preconditions:** Server initialized with `AuthMode::Disabled`, no demo header. A run created and started, then set to `RunStatus::Running` in state.
|
||||
- **Actions:** `GET /api/v1/boards/runs` (no demo header)
|
||||
- **Expected outcome:** HTTP 200. Response has `data` array. The created run appears with string `id`, string `title`, object `repository` (with `name`), object `workflow` (with `slug`), string `status` equal to `"working"` (the board column mapping of `Running`), and string `created_at`. Source of truth: OpenAPI spec `PaginatedRunList` schema and plan Decision 1 (Running -> "working").
|
||||
- **Interactions:** `state.runs` mutex, `state.store.list_runs()`
|
||||
|
||||
### Test 5: Real `/boards/runs` excludes non-board statuses
|
||||
|
||||
- **Name:** Runs with statuses that don't map to board columns (Submitted, Runnable, Starting, Failed, Cancelled) are excluded from the board response
|
||||
- **Type:** boundary
|
||||
- **Disposition:** new
|
||||
- **Harness:** Rust HTTP integration harness
|
||||
- **Preconditions:** Server initialized. A run created and started, then set to `RunStatus::Failed`.
|
||||
- **Actions:** `GET /api/v1/boards/runs` (no demo header)
|
||||
- **Expected outcome:** HTTP 200. The failed run does NOT appear in the `data` array. Source of truth: Plan Decision 1 status mapping -- Failed is excluded.
|
||||
- **Interactions:** `state.runs` mutex
|
||||
|
||||
### Test 6: Real `/boards/runs` maps Paused to "pending" and Completed to "merge"
|
||||
|
||||
- **Name:** Board column mapping correctly translates Paused to pending and Completed to merge
|
||||
- **Type:** integration
|
||||
- **Disposition:** new
|
||||
- **Harness:** Rust HTTP integration harness
|
||||
- **Preconditions:** Server initialized. Two runs created: one set to `RunStatus::Paused`, one set to `RunStatus::Completed`.
|
||||
- **Actions:** `GET /api/v1/boards/runs` (no demo header)
|
||||
- **Expected outcome:** HTTP 200. Paused run has `status: "pending"`. Completed run has `status: "merge"`. Source of truth: Plan Decision 1 status mapping.
|
||||
- **Interactions:** `state.runs` mutex, `state.store.list_runs()`
|
||||
|
||||
### Test 7: Runs board loads without errors in production mode (browser)
|
||||
|
||||
- **Name:** Navigating to the runs board in production mode renders a page without error messages
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Fabro server running with auth disabled and in-memory store. SPA built and served. No demo cookie set.
|
||||
- **Actions:** Navigate to `/runs`.
|
||||
- **Expected outcome:** Page loads. Body does not contain "Unauthorized" or "500" or "error" (case-insensitive check excluding expected UI text). Screenshot captured as artifact at `test-results/runs-prod.png`. Source of truth: User request ("make it production grade" -- the runs board is the primary view and must render).
|
||||
- **Interactions:** React Router loader -> `apiFetch("/boards/runs")` -> server real `list_board_runs` handler
|
||||
|
||||
### Test 8: Navigation hides Workflows and Insights in production mode (browser)
|
||||
|
||||
- **Name:** The sidebar/header navigation does not show Workflows or Insights links when not in demo mode
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running, no demo cookie.
|
||||
- **Actions:** Navigate to `/runs`. Inspect the `nav` element.
|
||||
- **Expected outcome:** `nav` element does NOT contain text "Workflows". `nav` element does NOT contain text "Insights". `nav` element DOES contain text "Runs". Source of truth: Plan Decision 4 and user request ("remove the corresponding UI from fabro web for now").
|
||||
- **Interactions:** App shell loader -> `getAuthMe()` -> `demoMode: false` -> `getVisibleNavigation(false)` filters out demo-only items
|
||||
|
||||
### Test 9: Settings page loads in production mode (browser)
|
||||
|
||||
- **Name:** The settings page loads successfully in production mode since /settings is implemented in the real server
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running, no demo cookie.
|
||||
- **Actions:** Navigate to `/settings`.
|
||||
- **Expected outcome:** Page loads without "Not implemented" or "500" error text. Screenshot captured at `test-results/settings-prod.png`. Source of truth: Real server route table has `get(get_server_settings)` for `/settings`.
|
||||
- **Interactions:** Settings route loader -> `apiJson("/settings")` -> real `get_server_settings` handler
|
||||
|
||||
### Test 10: Demo mode runs board shows demo data (browser)
|
||||
|
||||
- **Name:** Navigating to the runs board with the demo cookie set renders demo run data
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running. `fabro-demo=1` cookie set for localhost.
|
||||
- **Actions:** Navigate to `/runs`.
|
||||
- **Expected outcome:** Page loads without error. Body content is not empty/blank (confirms demo data rendered). Screenshot captured at `test-results/runs-demo.png`. Source of truth: Plan Decision 2 (demo `/boards/runs` returns demo run list items).
|
||||
- **Interactions:** Demo cookie -> server `X-Fabro-Demo` middleware -> demo `list_board_runs` -> demo run data
|
||||
|
||||
### Test 11: Navigation shows all items in demo mode (browser)
|
||||
|
||||
- **Name:** The navigation shows Workflows, Runs, and Insights links when in demo mode
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running. Demo cookie set.
|
||||
- **Actions:** Navigate to `/runs`. Inspect `nav` element.
|
||||
- **Expected outcome:** `nav` contains "Workflows", "Runs", and "Insights". Source of truth: Plan Decision 4 -- all nav items visible in demo mode.
|
||||
- **Interactions:** App shell loader -> `getAuthMe()` -> `demoMode: true` -> `getVisibleNavigation(true)` includes all items
|
||||
|
||||
### Test 12: Workflows page loads in demo mode (browser)
|
||||
|
||||
- **Name:** The workflows page renders successfully when in demo mode
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running. Demo cookie set.
|
||||
- **Actions:** Navigate to `/workflows`.
|
||||
- **Expected outcome:** Page loads without "error" or "500" text. Screenshot captured at `test-results/workflows-demo.png`. Source of truth: Demo routes include workflow handlers.
|
||||
- **Interactions:** Workflows route loader -> demo workflow handlers
|
||||
|
||||
### Test 13: Toggling demo mode changes navigation (browser)
|
||||
|
||||
- **Name:** Clicking the demo toggle button switches between production and demo navigation
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running. No demo cookie initially.
|
||||
- **Actions:**
|
||||
1. Navigate to `/runs`
|
||||
2. Verify nav does NOT contain "Workflows"
|
||||
3. Click the beaker button (demo toggle -- `button[title*="demo"], button[title*="Demo"]`)
|
||||
4. Wait for page to revalidate
|
||||
5. Verify nav now DOES contain "Workflows"
|
||||
- **Expected outcome:** Before toggle: no "Workflows" in nav. After toggle: "Workflows" appears in nav. Screenshot captured at `test-results/after-toggle-demo.png`. Source of truth: Plan Decision 4 -- `toggleDemoMode()` posts to `/api/v1/demo/toggle`, sets cookie, revalidates, `demoMode` changes, nav re-renders.
|
||||
- **Interactions:** Demo toggle button -> `POST /demo/toggle` -> cookie set -> revalidate -> `getAuthMe()` returns `demoMode: true` -> `getVisibleNavigation(true)`
|
||||
|
||||
### Test 14: Run detail page loads in production mode (browser)
|
||||
|
||||
- **Name:** Navigating to a run detail page in production mode renders without crashing, even when no runs exist
|
||||
- **Type:** scenario
|
||||
- **Disposition:** new
|
||||
- **Harness:** Playwright browser harness
|
||||
- **Preconditions:** Server running with in-memory store, no demo cookie, no runs created.
|
||||
- **Actions:** Navigate to `/runs/nonexistent-id`.
|
||||
- **Expected outcome:** Page renders (may show "Run not found" message). Does NOT crash with unhandled error or blank page. Source of truth: Plan Decision 6 -- run-detail loader uses `/runs/{id}` which returns 404, and component handles `run: null`.
|
||||
- **Interactions:** Run detail loader -> `apiJson("/runs/nonexistent-id")` -> 404 -> graceful error handling
|
||||
|
||||
### Test 15: `mapRunSummaryToRunItem` correctly maps StoreRunSummary fields to RunItem
|
||||
|
||||
- **Name:** The mapping function converts server run summary response fields to the UI's RunItem shape
|
||||
- **Type:** unit
|
||||
- **Disposition:** new
|
||||
- **Harness:** TypeScript unit test harness (bun test)
|
||||
- **Preconditions:** None (pure function).
|
||||
- **Actions:** Call `mapRunSummaryToRunItem()` with a complete `RunSummaryResponse` object containing `run_id`, `goal`, `workflow_slug`, `host_repo_path`, `duration_ms`.
|
||||
- **Expected outcome:** Returns `RunItem` with `id` equal to `run_id`, `title` equal to `goal`, `workflow` equal to `workflow_slug`, `repo` equal to last segment of `host_repo_path`, `elapsed` formatted from `duration_ms`. Source of truth: Plan Decision 6 field mapping specification.
|
||||
- **Interactions:** `formatElapsedSecs()` from `lib/format.ts`
|
||||
|
||||
### Test 16: `mapRunSummaryToRunItem` handles null optional fields
|
||||
|
||||
- **Name:** The mapping function provides sensible defaults when optional fields are null
|
||||
- **Type:** boundary
|
||||
- **Disposition:** new
|
||||
- **Harness:** TypeScript unit test harness (bun test)
|
||||
- **Preconditions:** None (pure function).
|
||||
- **Actions:** Call `mapRunSummaryToRunItem()` with all optional fields set to null (`goal: null`, `workflow_slug: null`, `host_repo_path: null`, `duration_ms: null`).
|
||||
- **Expected outcome:** Returns `RunItem` with `title: "Untitled run"`, `workflow: "unknown"`, `repo: "unknown"`, `elapsed: undefined`. Source of truth: Plan Task 4 step 3 default values.
|
||||
- **Interactions:** None
|
||||
|
||||
### Test 17: `DemoModeProvider` provides demo mode value to children
|
||||
|
||||
- **Name:** The React context correctly propagates the demo mode boolean to consumer components
|
||||
- **Type:** unit
|
||||
- **Disposition:** new
|
||||
- **Harness:** TypeScript unit test harness (bun test)
|
||||
- **Preconditions:** None.
|
||||
- **Actions:** Render `<DemoModeProvider value={true}><TestConsumer /></DemoModeProvider>` using `renderToString`. `TestConsumer` reads `useDemoMode()`.
|
||||
- **Expected outcome:** Rendered HTML contains `data-demo="true"` and text "demo". Source of truth: Plan Decision 7 -- `DemoModeProvider` wraps `Outlet` with context value.
|
||||
- **Interactions:** React context system
|
||||
|
||||
### Test 18: `getVisibleNavigation` filters demo-only items in production mode
|
||||
|
||||
- **Name:** The navigation filtering function excludes demo-only navigation items when not in demo mode
|
||||
- **Type:** unit
|
||||
- **Disposition:** new
|
||||
- **Harness:** TypeScript unit test harness (bun test)
|
||||
- **Preconditions:** None (pure function).
|
||||
- **Actions:** Call `getVisibleNavigation(false)` and `getVisibleNavigation(true)`.
|
||||
- **Expected outcome:** `getVisibleNavigation(false)` returns items that include "Runs" but NOT "Workflows" or "Insights". `getVisibleNavigation(true)` returns items that include "Runs", "Workflows", and "Insights". Source of truth: Plan Decision 4 -- Workflows and Insights are `demoOnly: true`.
|
||||
- **Interactions:** None
|
||||
|
||||
---
|
||||
|
||||
## Coverage summary
|
||||
|
||||
### Covered areas
|
||||
|
||||
| Area | Tests | Coverage approach |
|
||||
|---|---|---|
|
||||
| Demo `/boards/runs` endpoint (new) | 1, 10 | Server integration + browser |
|
||||
| Demo `GET /runs/{id}` shape fix | 2, 3 | Server integration |
|
||||
| Real `/boards/runs` RunListItem enrichment | 4, 5, 6 | Server integration |
|
||||
| Real `/boards/runs` board column mapping | 4, 5, 6 | Server integration |
|
||||
| Run detail loader using `/runs/{id}` | 14, 15, 16 | Browser + unit |
|
||||
| Demo mode toggle | 13 | Browser |
|
||||
| Navigation filtering by demo mode | 8, 11, 18 | Browser + unit |
|
||||
| DemoModeProvider context | 17 | Unit |
|
||||
| mapRunSummaryToRunItem | 15, 16 | Unit |
|
||||
| Runs board in production mode | 7 | Browser |
|
||||
| Settings page in production mode | 9 | Browser |
|
||||
| Workflows page in demo mode | 12 | Browser |
|
||||
|
||||
### Explicitly excluded (per agreed strategy)
|
||||
|
||||
| Area | Reason | Risk |
|
||||
|---|---|---|
|
||||
| Run stages tab rendering | Hidden in production mode; demo-only route. Unchanged code. | Low -- existing demo data path untouched. |
|
||||
| Run files tab | Always hidden (endpoint does not exist). Tab removed from UI. | None. |
|
||||
| Insights page deep interaction | Demo-only route. Unchanged code. Out of scope per "remove UI for removed functionality." | Low. |
|
||||
| Workflow detail/diagram/runs pages | Demo-only routes. Static data, unchanged. | Low. |
|
||||
| Run overview graph rendering (Graphviz) | Depends on `@viz-js/viz` WASM, hard to test in headless browser. Loader resilience tested via browser smoke. | Medium -- if WASM fails to load, graph won't render, but the page will still load with "No workflow graph available" fallback. |
|
||||
| Run billing tab | Unchanged, already works in both modes. | None. |
|
||||
| SSE event streaming | Unchanged, not part of this task. | None. |
|
||||
| Performance benchmarks | Low performance risk -- no new hot paths, board query is bounded by in-memory run count. | Low. |
|
||||
| Existing server test regressions from `/boards/runs` shape change | Existing tests that assert `status_reason`/`pending_control` from `/boards/runs` will need updating. Covered by implementation plan Task 3 Step 5, verified by running full `cargo nextest run -p fabro-server`. | Medium -- if missed, existing tests fail, caught immediately by CI. |
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,334 +0,0 @@
|
|||
# Settings TOML Redesign Implementation Plan
|
||||
|
||||
## Summary
|
||||
|
||||
Use `docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md` as the source of truth and land this as a hard cut: replace the flat and organic config schema everywhere, update all loaders and consumers to the new namespaced model, and regenerate all outward-facing examples and contracts in the same change.
|
||||
|
||||
Fabro is still greenfield. This plan intentionally optimizes for the best steady-state code rather than backwards compatibility:
|
||||
|
||||
- one user-facing schema, not old and new in parallel
|
||||
- one hard-cut contract update for config files and settings payloads
|
||||
- no user-facing compatibility layer
|
||||
|
||||
This can still land as one cohesive PR. The staged sequence below is an internal implementation order so the work stays mechanically sane while the refactor is in flight.
|
||||
|
||||
This refactor is centered on four seams:
|
||||
|
||||
- schema and parsing in `lib/crates/fabro-types/src/settings/` and `lib/crates/fabro-config/src/config.rs`
|
||||
- layering and trust-boundary resolution in `lib/crates/fabro-config/src/effective_settings.rs`
|
||||
- CLI, workflow, agent, MCP, sandbox, and server consumers across the Rust workspace
|
||||
- public contracts in `docs/api-reference/fabro-api.yaml`, generated clients, generated config files, and `apps/fabro-web`
|
||||
|
||||
## Public Types And Interfaces
|
||||
|
||||
- Replace the flat `fabro_types::Settings` shape with a resolved namespaced settings tree matching the redesign:
|
||||
- `_version`
|
||||
- `project`
|
||||
- `workflow`
|
||||
- `run`
|
||||
- `cli`
|
||||
- `server`
|
||||
- `features`
|
||||
- Replace the current `ConfigLayer` shape with a sparse namespaced parse tree. A temporary in-repo bridge between old and new internal types is acceptable only to keep intermediate stages compiling; it must not become a user-visible compatibility layer and must be deleted by the end of the cut.
|
||||
- Treat `cli.*` and `server.*` as schema-valid everywhere but runtime-consumed only from local `settings.toml` plus explicit process-local overrides.
|
||||
- Replace legacy flat run sections and fields with namespaced equivalents, including:
|
||||
- `goal` and `working_dir` under `[run]`
|
||||
- `vars` to `[run.inputs]`
|
||||
- `labels` to `project.metadata`, `workflow.metadata`, and `run.metadata`
|
||||
- `llm` to `[run.model]`
|
||||
- `setup` to `[run.prepare]`
|
||||
- `mcp_servers` to `[run.agent.mcps.<name>]` or `[cli.exec.agent.mcps.<name>]`, depending on the consumer
|
||||
- `exec` to `[cli.exec]`
|
||||
- flat server sections to `[server.*]`
|
||||
- Treat `vars -> run.inputs` as a behavioral change, not just a rename. `run.inputs` intentionally replaces the inherited map wholesale rather than merging by key.
|
||||
- Replace legacy project shape `[fabro].root` with `[project].directory`.
|
||||
- Replace hook merge identity from effective-name semantics to optional explicit `id`, while keeping `name` human-facing only.
|
||||
- Replace string-command hook and launcher shorthand with one execution-language rule:
|
||||
- `script = "..."` for shell-evaluated commands
|
||||
- `command = ["..."]` for argv launches
|
||||
- mutually exclusive
|
||||
- Treat `script` and `command` fields as trusted executable config. Repo-scoped config using these fields executes with the consuming process privileges. Env interpolation inside `script` is raw string substitution, not shell-escaped templating.
|
||||
- Replace old MCP shapes with agent-scoped MCPs:
|
||||
- `[run.agent.mcps.<name>]`
|
||||
- `[cli.exec.agent.mcps.<name>]`
|
||||
- Keep `SecretStore` and provider ambient auth as the credential sources for secrets. The redesigned config should describe selectors and non-secret knobs, not become a general secret transport.
|
||||
- Keep `/api/v1/settings` as the endpoint path, but replace broad `Settings` serialization with an explicit public DTO. The hard cut is the schema and payload shape, not the path name.
|
||||
|
||||
## Resolved Deferred Questions
|
||||
|
||||
- `run.scm` first pass:
|
||||
- core fields are `provider`, `owner`, and `repository`
|
||||
- provider-specific capability leaves live under `[run.scm.<provider>]`
|
||||
- branch and PR behavior stay out of `run.scm` in this cut and remain on `[run.pull_request]` or runtime context
|
||||
- object-store envelope first pass:
|
||||
- provider-neutral envelope fields are `provider` and optional `prefix`
|
||||
- provider-specific tables live under `[server.artifacts.<provider>]` and `[server.slatedb.<provider>]`
|
||||
- `local` uses `root`, defaulting to `server.storage.root` when omitted
|
||||
- `s3` carries bucket and region plus optional endpoint and path-style settings
|
||||
- provider credentials come from `SecretStore`, `${env.NAME}`, or ambient provider auth rather than first-pass secret fields in TOML
|
||||
- MCP surface first pass:
|
||||
- common fields are `enabled`, `type`, `startup_timeout`, and `tool_timeout`
|
||||
- `startup_timeout` and `tool_timeout` use the shared duration type from the value-language helpers
|
||||
- `type = "http"` uses `url` plus optional `headers`
|
||||
- `type = "stdio"` requires exactly one of `script` or `command` and may include `env`
|
||||
- `type = "sandbox"` requires exactly one of `script` or `command`, requires `port` as an integer, and may include `env`
|
||||
- notification route surface first pass:
|
||||
- route envelope fields are `enabled`, `provider`, and `events`
|
||||
- provider-specific destination fields live under `[run.notifications.<name>.<provider>]`
|
||||
- first-pass Slack destinations use `channel`
|
||||
- duration parser first pass:
|
||||
- one shared parser accepts a single unit suffix per value: `ms`, `s`, `m`, `h`, or `d`
|
||||
- composed values like `1h30m` are not supported in first pass; use the smallest needed unit instead
|
||||
- one shared canonical renderer prints human-readable durations in the same single-unit form
|
||||
- size parser first pass:
|
||||
- one shared parser accepts bare integers plus `B`, `KB`, `MB`, `GB`, `TB`, and `KiB`, `MiB`, `GiB`, `TiB`
|
||||
- `KB`, `MB`, `GB`, and `TB` are decimal (powers of 1000); `KiB`, `MiB`, `GiB`, and `TiB` are binary (powers of 1024)
|
||||
- bare values default to `GB`
|
||||
- fractional values are not supported in first pass
|
||||
- one shared canonical renderer prints human-readable sizes using the largest decimal unit that represents the value as an integer multiple
|
||||
- config-language parsing stays permissive; provider layers remain responsible for stricter admissible-value validation such as Daytona-specific CPU and memory limits
|
||||
- object-store `provider` field is a closed enum. First-pass variants are `local` and `s3`. Unknown providers hard-fail against the schema rather than passing through as opaque strings.
|
||||
- `SecretStore` access is not referenced from user TOML in first pass. Consumers read secrets via existing server-side `SecretStore` code paths; the config schema does not introduce a `${secret.NAME}` interpolation form. If TOML-level secret references become necessary later, they are a separate schema bump.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
### 1. Replace the config parse tree and resolved types
|
||||
|
||||
- Introduce a new namespaced parse tree for `_version`, `project`, `workflow`, `run`, `cli`, `server`, and `features`; do not alias old field names forward.
|
||||
- Redesign `fabro_types::Settings` to match the new resolved schema rather than preserving the old flat representation internally.
|
||||
- Treat strict unknown-key handling as a parse-architecture change, not just a derive tweak. The loader must validate against the full union schema before consumer-specific filtering and must surface targeted rename hints for legacy keys.
|
||||
- Add explicit `_version` handling before deeper validation:
|
||||
- missing defaults to `1`
|
||||
- legacy `version` hard-fails with a rename hint
|
||||
- unsupported higher versions hard-fail with an upgrade hint
|
||||
- Stage the new value-language helpers explicitly instead of bundling them into one opaque parser rewrite:
|
||||
- one shared duration type and parser for config-facing time values
|
||||
- one shared size type and parser for memory and disk values
|
||||
- one model-reference parser for `run.model.fallbacks`
|
||||
- one interpolation representation for `${env.NAME}` tokens, including substring interpolation and multiple tokens per string
|
||||
- one splice-capable string-array helper for the exact `"..."` semantics in the requirements doc
|
||||
- Implement the resolved first-pass shapes from the previous section directly in the parse tree and resolved settings types rather than leaving them to implementer choice.
|
||||
- Redesign run model types to cover:
|
||||
- `run.metadata`
|
||||
- `run.inputs`
|
||||
- `run.model`
|
||||
- `run.git`
|
||||
- `run.prepare.steps`
|
||||
- `run.execution`
|
||||
- `run.checkpoint`
|
||||
- `run.sandbox`
|
||||
- `run.notifications.<name>`
|
||||
- `run.interviews`
|
||||
- `run.agent`
|
||||
- `run.agent.mcps.<name>`
|
||||
- `run.hooks`
|
||||
- `run.scm`
|
||||
- `run.scm.<provider>`
|
||||
- `run.pull_request`
|
||||
- `run.artifacts`
|
||||
- Redesign CLI types to cover:
|
||||
- `cli.target`
|
||||
- `cli.target.tls`
|
||||
- `cli.auth`
|
||||
- `cli.exec`
|
||||
- `cli.exec.model`
|
||||
- `cli.exec.agent`
|
||||
- `cli.exec.agent.mcps.<name>`
|
||||
- `cli.output`
|
||||
- `cli.updates`
|
||||
- `cli.logging`
|
||||
- Redesign server types to cover:
|
||||
- `server.listen`
|
||||
- `server.listen.tls`
|
||||
- `server.api`
|
||||
- `server.web`
|
||||
- `server.auth.api`
|
||||
- `server.auth.web.providers.<provider>`
|
||||
- `server.storage`
|
||||
- `server.artifacts`
|
||||
- `server.slatedb`
|
||||
- `server.scheduler`
|
||||
- `server.logging`
|
||||
- `server.integrations.<provider>`
|
||||
- Keep provider-neutral envelopes and provider-specific nested tables where the requirements already locked them:
|
||||
- sandbox
|
||||
- notifications
|
||||
- interviews
|
||||
- object stores
|
||||
- SCM provider leaves
|
||||
- Keep model config intentionally provider-neutral and implement the fallback grammar exactly as specified in the requirements doc.
|
||||
|
||||
### 2. Narrow merge changes to the paths whose behavior actually changes
|
||||
|
||||
- Keep `Combine` as the default layering mechanism where it still matches the requirements. Add explicit custom merge only for paths whose behavior changes.
|
||||
- Encode the merge matrix from the requirements doc directly in code, with custom logic only for:
|
||||
- replace-by-default maps like `run.inputs`, `project.metadata`, `workflow.metadata`, and `run.metadata`
|
||||
- sticky merge-by-key maps like `run.sandbox.env`
|
||||
- splice-aware string arrays
|
||||
- whole-list replacement for `run.prepare.steps`
|
||||
- field-merge keyed objects like notifications, MCPs, and web-auth providers
|
||||
- ordered hook merging by optional `id`
|
||||
- Make splice-capable arrays explicit in the implementation rather than shape-driven. In the first pass, the only splice-capable array paths are:
|
||||
- `run.model.fallbacks`
|
||||
- `run.notifications.<name>.events`
|
||||
- Treat `"..."` in all non-splice arrays as a hard error rather than data or a silent no-op.
|
||||
- Keep inactive provider and strategy subtables inert when the selected provider changes; validate and consume only the selected subtree.
|
||||
- Move env interpolation out of the current sandbox-only whole-value resolver and into a post-layering resolution pass that runs only on consumed string fields.
|
||||
- If any `${env.NAME}` token in a consumed string fails to resolve, fail the entire field with an error that identifies both the unresolved token and the config path.
|
||||
- Track interpolation provenance so env-sourced resolved values can be redacted consistently in outward-facing serialization, not just in the CLI.
|
||||
- Keep hook ordering stable:
|
||||
- `id`-matched replacement happens in place
|
||||
- anonymous hooks from higher-precedence files append after the fully merged inherited hook list
|
||||
- duplicate `id` values in one file hard-fail
|
||||
|
||||
### 3. Rebuild resolution, trust boundaries, and safe serialization
|
||||
|
||||
- Rework `EffectiveSettingsLayers` and `resolve_settings()` so owner-specific domains are consumed only from `~/.fabro/settings.toml` plus flags and env overrides.
|
||||
- Remove the current “merge everything, then strip server-owned fields” model. Build shared layered domains and owner-specific domains separately from the start.
|
||||
- Preserve today’s `exec` routing behavior:
|
||||
- configured CLI target defaults affect commands that use server targeting
|
||||
- `fabro exec` still requires explicit `--server`
|
||||
- Make the default server auth posture explicit and fail-closed:
|
||||
- if `server.auth` is absent or resolves to no enabled API or web auth configuration, normal server startup must refuse to start
|
||||
- demo and test helpers may continue to inject explicit insecure settings where needed, but insecure startup must be opt-in rather than accidental
|
||||
- Settings API exposure:
|
||||
- replace raw resolved settings serialization with explicit public DTOs
|
||||
- two distinct exposure scopes, each with its own DTO:
|
||||
- scope 1: `/api/v1/settings` (server configuration view)
|
||||
- first-pass allow-list:
|
||||
- `server.api.url`
|
||||
- `server.web.enabled`
|
||||
- `server.web.url`
|
||||
- enabled state for `server.auth.web.providers.*`
|
||||
- non-secret `server.scheduler` values
|
||||
- denies everything else, including all `project.*`, `workflow.*`, `run.*`, `cli.*`, and any `server.*` path not explicitly allowed (notably `server.listen`, `server.listen.tls.*`, `server.auth.api`, `server.integrations.*`, `server.artifacts*`, `server.slatedb*`, local secret-store paths, and any env-resolved secret values)
|
||||
- scope 2: `/api/v1/runs/:id/settings` and run-settings snapshots exposed via API (run configuration view)
|
||||
- allows the resolved `run.*` tree so the frontend run-settings page and equivalent consumers can render it
|
||||
- denies:
|
||||
- any resolved string value tagged as `${env.NAME}`-sourced (via the interpolation provenance tracking)
|
||||
- provider-credential fields under `run.notifications.*.<provider>` even when not env-sourced
|
||||
- env values under `run.agent.mcps.*.env` that were env-interpolated
|
||||
- any field explicitly marked sensitive in its type (for example, tokens or keys)
|
||||
- also denies all `project.*`, `workflow.*`, `cli.*`, and `server.*`; these are not part of a run-configuration view
|
||||
- Apply the matching exposure scope and redaction rules consistently across all outward-facing settings renderers:
|
||||
- `fabro settings` uses the server scope for server-facing rendering and the run scope for run-facing rendering
|
||||
- `/api/v1/settings` uses the server scope
|
||||
- `/api/v1/runs/:id/settings` and any API-exposed run-settings snapshots use the run scope
|
||||
- logs and emitted settings-like debug output use whichever scope matches the payload kind
|
||||
- Trust model:
|
||||
- `script` and `command` fields in repo-scoped config are trusted executable config and should be reviewed like code
|
||||
- those fields execute with the consuming process privileges; the config system does not sandbox them
|
||||
- `${env.NAME}` interpolation inside `script` is raw substitution, not shell quoting or shell-safe templating
|
||||
- Keep command-local override layering separate from machine settings loading:
|
||||
- `run`, `preflight`, and manifest code still build layered run defaults
|
||||
- `exec` still loads machine CLI defaults directly
|
||||
- `settings` still assembles effective layers deliberately
|
||||
- Classify server settings as startup-only vs live-reloadable in the first pass:
|
||||
- live-reloadable:
|
||||
- `server.logging`
|
||||
- `server.scheduler`
|
||||
- startup-only:
|
||||
- `server.listen`
|
||||
- `server.listen.tls`
|
||||
- `server.api`
|
||||
- `server.web`
|
||||
- `server.auth`
|
||||
- `server.storage`
|
||||
- `server.artifacts`
|
||||
- `server.slatedb`
|
||||
- `server.integrations`
|
||||
- Update server runtime application logic to stop assuming old flat fields like `storage_dir`, `artifact_storage`, `api`, and `web`.
|
||||
- Make the persisted-settings decision explicit: old run-settings snapshots and local dev state are not guaranteed to survive the hard cut. Tests, fixtures, and generated examples should be rewritten; no snapshot migration layer is planned.
|
||||
|
||||
### 4. Migrate all consumers, scaffolds, and contracts
|
||||
|
||||
- Update CLI overrides, run manifest building, workflow discovery, project discovery, and remote and local-daemon settings application to the new schema.
|
||||
- Update all crates that currently consume settings or config layers, not just the CLI and server entrypoints. At minimum this includes:
|
||||
- `fabro-cli`
|
||||
- `fabro-server`
|
||||
- `fabro-workflow`
|
||||
- `fabro-agent`
|
||||
- `fabro-mcp`
|
||||
- sandbox-facing config consumers
|
||||
- hook execution consumers
|
||||
- test helpers in `fabro-test`
|
||||
- Update server start and foreground command flows to read and apply the new server config shape.
|
||||
- Update `SecretStore` integration points so server and installer flows continue to source secrets out of band while the new config shape only carries non-secret selectors and toggles.
|
||||
- Update scaffolding and installers so generated `settings.toml`, `fabro.toml`, and `workflow.toml` use `_version` and the new namespaced sections.
|
||||
- Update install-time config writers to stop editing legacy `[git]`, `[web]`, `[api]`, and similar flat sections.
|
||||
- Update the server `/api/v1/settings` response and any run-settings snapshot payloads to the new allow-listed resolved shape, then regenerate Rust and TypeScript clients from OpenAPI.
|
||||
- Update `apps/fabro-web` and any generated TypeScript consumers to the new settings contract. The live `/settings` and `/runs/:id/settings` routes currently `JSON.stringify` the full response, so they remain shape-agnostic, but the static `workflowData` fallback in `apps/fabro-web/app/routes/workflow-detail.tsx` uses the old schema shape and must be rewritten against the new `RunSettings` type.
|
||||
- Update docs and examples in `docs/reference/`, especially:
|
||||
- `user-configuration.mdx`
|
||||
- `cli.mdx`
|
||||
- any other config examples that currently show `[llm]`, `[exec]`, `[server]`, `[sandbox]`, `[fabro]`, or `version = 1`
|
||||
- Update installer, repo-init, and workflow-create generated content so no new files are emitted in the old schema after the cutover lands.
|
||||
|
||||
## Sequencing
|
||||
|
||||
Implement in these internal compile-preserving stages:
|
||||
|
||||
1. Add the new value-language helpers and namespaced sparse parse structs alongside the current code so the repo still builds while parser architecture is being introduced.
|
||||
2. Add the new resolved settings tree plus a temporary internal bridge between old and new types so callers can migrate incrementally without freezing the repo in an unbuildable state.
|
||||
3. Switch parsing and layering to the new schema, strict validation, merge behavior, trust boundaries, and env interpolation. This is where legacy user config starts hard-failing.
|
||||
4. Migrate consumers crate by crate:
|
||||
- `fabro-cli`
|
||||
- `fabro-server`
|
||||
- `fabro-workflow`
|
||||
- `fabro-agent`
|
||||
- `fabro-mcp`
|
||||
- hook, sandbox, and test-helper consumers
|
||||
5. Update `/api/v1/settings`, OpenAPI, generated clients, `apps/fabro-web`, scaffolds, installers, and docs to the new contract.
|
||||
6. Remove the old flat settings types, the temporary bridge, legacy fixtures, and any now-dead merge logic.
|
||||
|
||||
This remains a hard cut. These stages describe implementation order, not a staged user rollout.
|
||||
|
||||
## Test Plan
|
||||
|
||||
- Add parser and unit coverage for:
|
||||
- `_version` defaulting and failure modes
|
||||
- representative hard failures for legacy keys and unknown keys
|
||||
- model fallback token parsing and ambiguity errors
|
||||
- duration and size parsing
|
||||
- substring and multi-token `${env.NAME}` interpolation
|
||||
- splice-array rules on allowed paths
|
||||
- hard failure for `"..."` on non-splice paths
|
||||
- hook `id` replacement and anonymous append ordering
|
||||
- Add layering and resolution coverage for:
|
||||
- `run.inputs` replace semantics
|
||||
- `run.sandbox.env` sticky merge semantics
|
||||
- keyed object merge and disable behavior
|
||||
- owner-specific trust boundaries for `cli.*` and `server.*`
|
||||
- inactive provider subtables remaining inert
|
||||
- default server auth fail-closed behavior when `server.auth` is absent
|
||||
- Add serialization and exposure coverage for:
|
||||
- `fabro settings` redaction
|
||||
- `/api/v1/settings` allow-list behavior
|
||||
- exclusion of TLS paths, auth internals, object-store credentials, and env-resolved secrets
|
||||
- any API-exposed run-settings snapshot redaction behavior
|
||||
- Add behavior coverage for:
|
||||
- `project.directory`-based workflow discovery
|
||||
- `run.inputs` replace semantics
|
||||
- hook identity via explicit `id`
|
||||
- Update CLI integration tests in:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/config.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/repo_init.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/workflow_create.rs`
|
||||
- Update server and API coverage for:
|
||||
- `/api/v1/settings`
|
||||
- startup-only vs live-reloadable server settings
|
||||
- run settings snapshots
|
||||
- any tests assuming old flat server settings fields
|
||||
- Update frontend and generated-client expectations after the OpenAPI change.
|
||||
- Update doc examples and snapshot tests that assert generated config files or `fabro settings` output.
|
||||
|
||||
## Assumptions And Defaults
|
||||
|
||||
- Hard cut only: one user-facing schema, no compatibility aliases, and no user-facing compatibility layer.
|
||||
- A temporary internal bridge between old and new settings types is acceptable only to keep intermediate stages compiling and must be removed before the work is done.
|
||||
- `run.inputs` replaces inherited values wholesale; `run.sandbox.env` remains merge-by-key and sticky.
|
||||
- `cli.*` and `server.*` remain schema-valid in all files but are runtime-inert outside local `settings.toml`.
|
||||
- Provider-specific subtables coexist inertly; only the selected provider or strategy subtree is validated and consumed.
|
||||
- Object-store and integration credentials continue to come from `SecretStore`, `${env.NAME}`, or ambient provider auth rather than new first-pass secret fields in TOML.
|
||||
- `/api/v1/settings` remains the endpoint path, but its payload shape becomes a new allow-listed public contract.
|
||||
|
|
@ -1,572 +0,0 @@
|
|||
---
|
||||
date: 2026-04-09
|
||||
status: active
|
||||
topic: settings-toml-redesign
|
||||
predecessor: docs/plans/2026-04-09-settings-toml-redesign-handoff.md
|
||||
---
|
||||
|
||||
# Settings TOML Redesign — Handoff 2 (post Stage 6.1–6.5 landing)
|
||||
|
||||
## TL;DR
|
||||
|
||||
Stages 6.1, 6.2, and 6.4 of the Stage 6 follow-up landed cleanly on `main`.
|
||||
Stages 6.3 and 6.5 are **partially** complete — they each hit a concrete
|
||||
blocker that requires Stage 6.6 to be done first. Stage 6.6 (OpenAPI DTO
|
||||
rewrite + fabro-web) is **not started**.
|
||||
|
||||
The workspace builds clean, all 3,756 tests pass, `cargo clippy --workspace
|
||||
-- -D warnings` and `cargo fmt --check --all` are green. There are known
|
||||
runtime behavior changes on the `/api/v1/settings` endpoint (see "Known
|
||||
wire-contract mismatches" below) that will affect fabro-web until 6.6
|
||||
lands.
|
||||
|
||||
The main work that remains is:
|
||||
|
||||
1. **Finish Stage 6.6** — rewrite `docs/api-reference/fabro-api.yaml`,
|
||||
regenerate the Rust progenitor and TypeScript Axios clients, update
|
||||
`fabro-web/app/routes/workflow-detail.tsx`, and rewrite the server's
|
||||
`/api/v1/settings` + `/api/v1/runs/:id/settings` handlers to build
|
||||
allow-list DTOs from the v2 tree without bridging.
|
||||
2. **Unblock Stage 6.3** — 6.6 removes the last reader of the legacy
|
||||
flat `Settings` struct (the progenitor-generated `api::types::ServerSettings`
|
||||
conversion path). Once that's gone, the whole `fabro_types::settings::{hook,
|
||||
mcp, project, run, sandbox, server, user}` module tree plus
|
||||
`fabro_types::combine::Combine` can be deleted.
|
||||
3. **Unblock Stage 6.5** — 6.3's deletion removes the filename collisions
|
||||
that currently prevent flattening `settings/v2/*.rs` up to `settings/*.rs`.
|
||||
4. **Revisit scoped TODOs** — see "Scoped TODOs" below.
|
||||
|
||||
## Source documents
|
||||
|
||||
Read these, in this order:
|
||||
|
||||
1. **Requirements (authoritative)** —
|
||||
[`docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md`](../brainstorms/2026-04-08-settings-toml-redesign-requirements.md).
|
||||
Source of truth for the v2 schema, merge matrix (R22 / R30 / R71 etc.),
|
||||
trust boundaries, disable semantics. Refer to requirement numbers when
|
||||
making schema decisions.
|
||||
|
||||
2. **Original implementation plan** —
|
||||
[`docs/plans/2026-04-08-settings-toml-redesign-implementation-plan.md`](./2026-04-08-settings-toml-redesign-implementation-plan.md).
|
||||
|
||||
3. **Stage 6 handoff (predecessor to this doc)** —
|
||||
[`docs/plans/2026-04-09-settings-toml-redesign-handoff.md`](./2026-04-09-settings-toml-redesign-handoff.md).
|
||||
This is the doc I worked from. It has the per-stage scope, the file
|
||||
maps, gotchas, and open design questions. **Still current** for the
|
||||
remaining work — read it before touching Stage 6.6.
|
||||
|
||||
## Commit trail (landed on main, most recent first)
|
||||
|
||||
```
|
||||
ace24c410 refactor(types): stage 6.5 promote v2 types to settings top level
|
||||
a3fd3b002 refactor(config): stage 6.4 delete fabro-config re-export shims
|
||||
34a481cd4 refactor(settings): stage 6.3 delete dead Settings helpers + v2 install TOML
|
||||
ea206e0e4 feat(settings): stage 6.2 delete bridge_to_old seam
|
||||
52c295cf7 test(settings): update fabro-cli test suite for v2 settings shape
|
||||
dc856d088 feat(settings): stage 6.1 consumer migration builds workspace-wide
|
||||
5d9aad85a wip(settings): stage 6.1 consumer migration (broken build)
|
||||
842ab71eb feat(types): expose bridge helpers and expand v2 accessors
|
||||
3f32bdb87 feat(types): add SettingsFile convenience accessors
|
||||
```
|
||||
|
||||
Total: 81 files changed, +3,718 / −2,423 lines (net +1,295).
|
||||
|
||||
Note: commit `5d9aad85a` was an explicit broken-build WIP checkpoint
|
||||
the user approved mid-session; `dc856d088` fixes the build. Subsequent
|
||||
commits are individually test-green.
|
||||
|
||||
## Current-state map (what's in the tree now)
|
||||
|
||||
```
|
||||
lib/crates/fabro-types/src/settings/
|
||||
├── mod.rs
|
||||
│ ├── legacy `Settings` struct (flat, _still present_ — see 6.3 status)
|
||||
│ ├── legacy type re-exports from hook/mcp/project/run/sandbox/server/user
|
||||
│ └── NEW: pub use v2::{SettingsFile, InterpString, Duration, ...} ← 6.5
|
||||
│
|
||||
├── hook.rs / mcp.rs / project.rs / run.rs / sandbox.rs / server.rs / user.rs
|
||||
│ └── LEGACY runtime type definitions, still used (see below)
|
||||
│
|
||||
└── v2/
|
||||
├── mod.rs — module root; no more `bridge_to_old` re-export
|
||||
├── tree.rs — SettingsFile top-level
|
||||
├── version.rs
|
||||
├── project.rs / workflow.rs / run.rs / cli.rs / server.rs / features.rs
|
||||
├── duration.rs / size.rs / model_ref.rs / interp.rs / splice_array.rs
|
||||
├── accessors.rs — NEW in 6.1 prep; ~35 flat-view accessors on SettingsFile
|
||||
└── to_runtime.rs — NEW in 6.2; narrow v2→runtime-type helpers
|
||||
(bridge_sandbox, bridge_mcp_entry, bridge_hook,
|
||||
bridge_pull_request, bridge_worktree_mode, etc.)
|
||||
REPLACES the deleted bridge.rs file
|
||||
```
|
||||
|
||||
```
|
||||
lib/crates/fabro-config/src/
|
||||
├── lib.rs — crate root; NEW: top-level `resolve_storage_dir(&SettingsFile)` helper
|
||||
├── config.rs — ConfigLayer newtype; NO MORE `.resolve()` / TryFrom<...> for Settings
|
||||
├── merge.rs — v2 merge matrix, unchanged
|
||||
├── effective_settings.rs — rewritten: returns SettingsFile, v2 merge for server defaults
|
||||
├── project.rs — resolve_working_directory takes &SettingsFile
|
||||
├── run.rs — workflow loaders only (parse_run_config / load_run_config / resolve_graph_path)
|
||||
├── user.rs — machine settings loader + path helpers, no type re-exports
|
||||
├── home.rs / storage.rs / legacy_env.rs — unchanged
|
||||
│
|
||||
└── DELETED in 6.4:
|
||||
hook.rs, mcp.rs, sandbox.rs, server.rs
|
||||
```
|
||||
|
||||
## Stage-by-stage status
|
||||
|
||||
### 6.1 — Migrate consumers off flat `Settings` ✅ **COMPLETE**
|
||||
|
||||
Every production read site in `fabro-workflow`, `fabro-server`,
|
||||
`fabro-cli`, and `fabro-config` reads from `SettingsFile` or walks v2
|
||||
subtrees via `settings::v2::accessors`. `RunRecord.settings`,
|
||||
`RunCreatedProps.settings`, `RunOptions.settings`, `CreateRunInput.settings`,
|
||||
`ValidateInput.settings`, `ResolveWorkflowInput.settings`,
|
||||
`ResolvedWorkflow.settings`, `AppState.settings`, and
|
||||
`CommandContext::machine_settings` are all `SettingsFile`-typed.
|
||||
|
||||
Where the `bridge_to_old`-style conversion to a legacy runtime type was
|
||||
still needed (e.g., `fabro_types::settings::sandbox::SandboxSettings`
|
||||
for `fabro-sandbox`, `fabro_types::settings::mcp::McpServerEntry` for
|
||||
`fabro-mcp`, `fabro_types::settings::hook::HookDefinition` for
|
||||
`fabro-hooks`), the new narrow helpers in
|
||||
`fabro_types::settings::v2::to_runtime` build them from single v2
|
||||
subtrees. Consumers call these explicitly at the point of use.
|
||||
|
||||
### 6.2 — Delete `bridge_to_old` seam ✅ **COMPLETE**
|
||||
|
||||
`lib/crates/fabro-types/src/settings/v2/bridge.rs` (818 LOC) is deleted.
|
||||
`ConfigLayer::resolve`, `TryFrom<ConfigLayer> for Settings`, and
|
||||
`TryFrom<&ConfigLayer> for Settings` are deleted. The full-tree
|
||||
conversion from a v2 `SettingsFile` to a legacy flat `Settings` no
|
||||
longer exists anywhere in the codebase.
|
||||
|
||||
The narrow runtime-type helpers that the bridge exported as public
|
||||
functions moved to `fabro_types::settings::v2::to_runtime` and are
|
||||
scoped per runtime type (one helper per runtime struct, not one
|
||||
all-in-one converter). They survive until Stage 6.3 deletes the
|
||||
runtime type targets.
|
||||
|
||||
### 6.3 — Delete legacy flat `Settings` types ⚠️ **PARTIAL (blocked on 6.6)**
|
||||
|
||||
**What landed** (`34a481cd4`):
|
||||
- Every inherent helper method on the legacy `Settings` struct
|
||||
(`app_id`, `slug`, `client_id`, `git_author`, `sandbox_settings`,
|
||||
`setup_settings`, `setup_commands`, `setup_timeout_ms`,
|
||||
`preserve_sandbox_enabled`, `github_permissions`, `mcp_server_entries`,
|
||||
`verbose_enabled`, `prevent_idle_sleep_enabled`, `upgrade_check_enabled`,
|
||||
`dry_run_enabled`, `auto_approve_enabled`, `no_retro_enabled`,
|
||||
`storage_dir`, `slack_settings`) is deleted. Callers migrated to the
|
||||
`SettingsFile` accessors with identical names.
|
||||
- `fabro-cli/src/commands/install.rs::merge_server_settings` now
|
||||
writes v2 TOML (with `[server.{api,listen.tls,web,auth.api.{jwt,mtls},
|
||||
auth.web}]` stanzas). Its tests parse the output through
|
||||
`ConfigLayer::parse` and assert v2 fields.
|
||||
|
||||
**What did NOT land** (blocked on 6.6):
|
||||
- The `Settings` struct itself is **still alive** in
|
||||
`lib/crates/fabro-types/src/settings/mod.rs`.
|
||||
- All seven legacy runtime type modules (`hook.rs`, `mcp.rs`,
|
||||
`project.rs`, `run.rs`, `sandbox.rs`, `server.rs`, `user.rs`) are
|
||||
**still alive** and used by runtime crates.
|
||||
- The `Combine` trait in `lib/crates/fabro-types/src/combine.rs` is
|
||||
**still alive** (only used by the legacy type `#[derive(Combine)]`
|
||||
attributes).
|
||||
- The `fabro-macros` crate's `Combine` derive macro is **still alive**.
|
||||
|
||||
**Why it's blocked on 6.6**: the progenitor-generated OpenAPI client
|
||||
in `lib/crates/fabro-api` deserializes `/api/v1/settings` responses
|
||||
into `api::types::ServerSettings`, which `fabro-cli/src/server_client.rs::
|
||||
retrieve_server_settings()` converts to `fabro_types::Settings` via
|
||||
`convert_type`. That conversion is the only remaining reader of the
|
||||
flat `Settings` shape in production code. Stage 6.6 rewrites the
|
||||
OpenAPI spec so the client returns a v2 DTO and this conversion path
|
||||
goes away.
|
||||
|
||||
**Remaining readers of the legacy `Settings` struct**:
|
||||
| File | Use |
|
||||
|---|---|
|
||||
| `lib/crates/fabro-cli/src/server_client.rs:282` | `retrieve_server_settings` return type |
|
||||
| `lib/crates/fabro-cli/src/commands/config/mod.rs:93` | `legacy_settings_to_v2` shim (takes `&fabro_types::Settings`) |
|
||||
| `lib/crates/fabro-cli/src/commands/install.rs` | gone (tests rewritten) |
|
||||
| `lib/crates/fabro-server/src/demo/mod.rs:1328, 1525` | demo route payloads |
|
||||
| `lib/crates/fabro-server/src/lib.rs:20` | `pub use fabro_types::Settings;` re-export |
|
||||
| `lib/crates/fabro-server/src/web_auth.rs:691` | test (or removed — double-check) |
|
||||
| `lib/crates/fabro-types/src/settings/mod.rs` | definition |
|
||||
|
||||
**Remaining readers of legacy runtime types** (imported via
|
||||
`fabro_types::settings::{hook,mcp,sandbox,server,user,run}`):
|
||||
| Consumer crate | Types it imports |
|
||||
|---|---|
|
||||
| `fabro-hooks` | `HookDefinition`, `HookEvent`, `HookSettings`, `HookType`, `TlsMode` |
|
||||
| `fabro-mcp` | `McpServerEntry`, `McpServerSettings`, `McpTransport`, timeouts |
|
||||
| `fabro-sandbox` | `SandboxSettings`, `DaytonaSettings`, `DaytonaSnapshotSettings`, `DaytonaNetwork`, `LocalSandboxSettings`, `WorktreeMode`, `DockerfileSource` |
|
||||
| `fabro-checkpoint` | `GitAuthorSettings` (plus the v2 `GitAuthorLayer` via new `From` impl) |
|
||||
| `fabro-workflow` | `PullRequestSettings`, `MergeStrategy`, `WorktreeMode` |
|
||||
| `fabro-server` | `ApiSettings`, `TlsSettings`, `ApiAuthStrategy`, `GitSettings`, plus `ServerSettings` for the CLI target |
|
||||
| `fabro-cli` | `ClientTlsSettings`, `OutputFormat`, `PermissionLevel`, `ExecSettings`, `ServerSettings` |
|
||||
| `fabro-agent` | `OutputFormat`, `PermissionLevel` (for `AgentArgs`) |
|
||||
|
||||
### 6.4 — Delete `fabro-config` re-export shims ✅ **COMPLETE**
|
||||
|
||||
Files deleted from `lib/crates/fabro-config/src/`:
|
||||
- `hook.rs`, `mcp.rs`, `sandbox.rs`, `server.rs` (pure pass-throughs)
|
||||
|
||||
Files shrunk:
|
||||
- `run.rs` — lost the type re-export block and the dead `resolve_env_refs`
|
||||
helper. Still exports `parse_run_config` / `load_run_config` /
|
||||
`resolve_graph_path` (used by fabro-cli and fabro-server).
|
||||
- `user.rs` — lost the runtime type re-export block. Still exports path
|
||||
helpers, `load_settings_config`, `active_settings_path`, etc.
|
||||
|
||||
`resolve_storage_dir` moved from `fabro-config/src/server.rs` (deleted)
|
||||
to the crate root in `fabro-config/src/lib.rs`. It takes `&SettingsFile`
|
||||
now.
|
||||
|
||||
All ~20 consumer crates updated to import runtime types directly from
|
||||
`fabro_types::settings::{hook,mcp,sandbox,server,user,run}` instead of
|
||||
`fabro_config::{hook,mcp,sandbox,server,user,run}`. The legacy import
|
||||
paths no longer compile.
|
||||
|
||||
### 6.5 — Flatten `settings::v2::*` → `settings::*` ⚠️ **PARTIAL (blocked on 6.3)**
|
||||
|
||||
**What landed** (`ace24c410`):
|
||||
Top-level re-exports of the v2 public surface at `fabro_types::settings`.
|
||||
Consumers can now write:
|
||||
|
||||
```rust
|
||||
use fabro_types::settings::{SettingsFile, InterpString, Duration, ...};
|
||||
```
|
||||
|
||||
Covers `{CURRENT_VERSION, CliLayer, Duration, FeaturesLayer, InterpString,
|
||||
ModelRef, ParseDurationError, ParseError, ParseModelRefError,
|
||||
ParseSizeError, ProjectLayer, Provenance, ResolveEnvError, Resolved,
|
||||
ResolvedModelRef, RunLayer, SchemaVersion, ServerLayer, SettingsFile,
|
||||
Size, SpliceArray, SpliceArrayError, VersionError, WorkflowLayer,
|
||||
parse_settings_file, validate_version}`.
|
||||
|
||||
**What did NOT land**:
|
||||
Actually moving the v2/*.rs files up to settings/*.rs. This is blocked
|
||||
because the v2 submodule filenames (`project.rs`, `run.rs`, `server.rs`,
|
||||
`cli.rs`) collide with the surviving legacy runtime type files with the
|
||||
same names. Once Stage 6.3 deletes the legacy files, a trivial follow-up
|
||||
commit can:
|
||||
|
||||
1. `git mv lib/crates/fabro-types/src/settings/v2/*.rs lib/crates/fabro-types/src/settings/`
|
||||
2. Delete `lib/crates/fabro-types/src/settings/v2/mod.rs`
|
||||
3. Update `lib/crates/fabro-types/src/settings/mod.rs` to replace
|
||||
`pub mod v2;` + the `pub use v2::{...}` block with direct
|
||||
`pub mod <name>;` declarations and a `pub use ...::*` re-export pass.
|
||||
4. Search-and-replace `::v2::` to nothing across the workspace.
|
||||
5. Update the accessors module and the `to_runtime` module to drop
|
||||
`super::` / `crate::` adjustments.
|
||||
|
||||
### 6.6 — Rewrite OpenAPI contracts and fabro-web DTOs ⏳ **NOT STARTED**
|
||||
|
||||
See the predecessor doc's Stage 6.6 section for the full scope. Key
|
||||
points and anything I've learned since:
|
||||
|
||||
**Files to rewrite**:
|
||||
- `docs/api-reference/fabro-api.yaml`:
|
||||
- Replace the `ServerSettings` schema (~lines 4238–4364 in the
|
||||
untouched version) with an explicit allow-list DTO that maps
|
||||
cleanly onto `SettingsFile`. See the handoff predecessor doc for
|
||||
the field allow-list guidance (R16 / R52 / R53 constraints).
|
||||
- Replace the `RunSettings` schema (~lines 3995–4032) similarly.
|
||||
- Regenerate clients:
|
||||
- Rust progenitor: `cargo build -p fabro-api` (auto-runs `build.rs`).
|
||||
- TypeScript: `cd lib/packages/fabro-api-client && bun run generate`.
|
||||
- `apps/fabro-web/app/routes/workflow-detail.tsx` — rewrite the static
|
||||
`workflowData` literal to match the new DTO.
|
||||
- `lib/crates/fabro-server/src/server.rs::get_server_settings`
|
||||
(around line 1062 — **note: this function was already edited in
|
||||
Stage 6.2** and now serializes the full v2 `SettingsFile` as JSON via
|
||||
`serde_json::to_value(&settings)` with `strip_nulls`. That's a
|
||||
temporary workaround, not the final state — see "Known wire-contract
|
||||
mismatches" below). Stage 6.6 replaces it with explicit allow-list
|
||||
DTO construction from the v2 tree.
|
||||
- `lib/crates/fabro-server/src/server.rs` `/api/v1/runs/:id/settings`
|
||||
handler — still returns `not_implemented` in the real router.
|
||||
- `lib/crates/fabro-server/src/demo/mod.rs` — demo routes still emit
|
||||
legacy Settings shapes. Either migrate to v2 or keep them as the
|
||||
"legacy demo" path.
|
||||
|
||||
**Known wire-contract mismatches** (will affect fabro-web until 6.6 lands):
|
||||
1. **`/api/v1/settings` response shape drift**. The server now emits the
|
||||
v2 `SettingsFile` JSON (e.g., `server.storage.root`,
|
||||
`run.execution.mode`, `cli.output.verbosity`) directly. The OpenAPI
|
||||
spec still declares the legacy `ServerSettings` schema (flat
|
||||
`storage_dir`, `dry_run`, `verbose`). Any client that relies on the
|
||||
spec will see missing fields or mis-typed values. The browser client
|
||||
is the main consumer; fabro-cli's `retrieve_server_settings` still
|
||||
goes through the progenitor client and round-trips through the old
|
||||
JSON shape — it will break on any v2 field the old schema doesn't
|
||||
declare.
|
||||
2. **`openapi_conformance` test**. Still passes because it asserts
|
||||
progenitor types match the YAML — but both sides are now stale
|
||||
relative to what the server actually emits. Stage 6.6 should
|
||||
rewrite this test or update it to cover the new DTOs.
|
||||
|
||||
## Scoped TODOs (stopgap code that needs revisiting)
|
||||
|
||||
Each of these is a deliberate short-term hack with a pointer to where
|
||||
it should land eventually. They're also marked in-line with
|
||||
`// Stage 6.x ...` comments.
|
||||
|
||||
### TODO-1: `legacy_settings_to_v2` shim in fabro-cli
|
||||
**File**: `lib/crates/fabro-cli/src/commands/config/mod.rs:91`
|
||||
**What**: Reverse mapping from `fabro_types::Settings` → `SettingsFile`.
|
||||
Covers `server.storage.root`, `server.scheduler.max_concurrent_runs`,
|
||||
`server.integrations.github.{app_id, client_id, slug}`,
|
||||
`server.integrations.slack.default_channel`, `run.model.{provider, name}`,
|
||||
`run.inputs`, and `cli.output.verbosity`. Does **not** cover most other
|
||||
fields.
|
||||
**Why**: `server_client::retrieve_server_settings` returns the legacy
|
||||
shape because the OpenAPI spec hasn't been rewritten.
|
||||
**Delete when**: Stage 6.6 rewrites the OpenAPI spec and the progenitor
|
||||
client returns v2 natively.
|
||||
|
||||
### TODO-2: `build_legacy_api_settings` in fabro-server
|
||||
**File**: `lib/crates/fabro-server/src/serve.rs:91`
|
||||
**What**: Projects the v2 `server.auth.api.{jwt,mtls}` + `server.listen.tls`
|
||||
subtrees onto the legacy `ApiSettings` struct that the existing
|
||||
`resolve_auth_mode_with_lookup` function still expects.
|
||||
**Why**: The auth resolver in `jwt_auth.rs` hasn't been migrated to v2
|
||||
yet. The v2 structure is different enough (no single `authentication_strategies`
|
||||
enum list; `jwt` and `mtls` are separate subtables with per-strategy
|
||||
`enabled` booleans) that a rewrite is warranted.
|
||||
**Delete when**: Stage 6.6 replaces `resolve_auth_mode_with_lookup` with
|
||||
a v2-aware resolver and deletes the legacy `ApiSettings` type.
|
||||
|
||||
### TODO-3: `get_server_settings` emits raw v2 JSON
|
||||
**File**: `lib/crates/fabro-server/src/server.rs:1063`
|
||||
**What**: The `/api/v1/settings` handler now serializes the full v2
|
||||
`SettingsFile` as JSON with `strip_nulls` instead of building a
|
||||
`ServerSettings` DTO. The spec still declares the old DTO.
|
||||
**Why**: Bridge deletion left no way to produce the old shape without
|
||||
re-introducing `bridge_to_old`.
|
||||
**Fix when**: Stage 6.6 rewrites the OpenAPI spec and builds an explicit
|
||||
allow-list DTO from v2 subtrees. Per R16/R52/R53 in the requirements doc:
|
||||
- **Allow**: `server.api.url`, `server.web.enabled`, `server.web.url`,
|
||||
per-provider enabled state under `server.auth.web.providers.*`,
|
||||
non-secret `server.scheduler` values.
|
||||
- **Deny**: `server.listen.*`, `server.listen.tls.*`, `server.auth.api`,
|
||||
`server.integrations.*`, `server.artifacts*`, `server.slatedb*`, any
|
||||
local `SecretStore` paths, any `InterpString` value whose
|
||||
`Provenance::EnvSourced` is set.
|
||||
|
||||
### TODO-4: `web_auth.rs` register flow
|
||||
**File**: `lib/crates/fabro-server/src/web_auth.rs:496-659`
|
||||
**What**: `setup_register` mutates a v2 TOML document via the new
|
||||
`merge_settings_keys` helper (which now writes v2 top-level stanzas
|
||||
under `[server.{web,auth,integrations.github}]`), writes it to disk,
|
||||
then re-parses it with `ConfigLayer::load` and swaps it into
|
||||
`state.settings`.
|
||||
**Why**: Previously the function wrote legacy v1 TOML (top-level
|
||||
`[web]`/`[api]`/`[git]`) that the v2 parser would reject. It had to be
|
||||
rewritten to stay functional.
|
||||
**Still TODO**: Stage 6.6 should decide whether the register flow
|
||||
belongs in the server at all, or whether the web UI should drive it
|
||||
directly via the HTTP API and a /api/v1/setup endpoint. The current
|
||||
implementation is a hand-rolled TOML writer and loses comments /
|
||||
formatting on round-trip.
|
||||
|
||||
### TODO-5: `check_crypto` in diagnostics walks v2 listen TLS
|
||||
**File**: `lib/crates/fabro-server/src/diagnostics.rs:469-574`
|
||||
**What**: Reads `server.auth.api.{jwt,mtls}.enabled` and
|
||||
`server.listen.tls.{cert,key,ca}` directly from `SettingsFile`.
|
||||
**Why**: Migrated off the bridge. Works, but the error messages
|
||||
reference v2 field paths (e.g., "mTLS configured but
|
||||
[server.listen.tls] is missing"); the `doctor` command hints may need
|
||||
updating for consistency.
|
||||
**Fix when**: Opportunistic, no blocker.
|
||||
|
||||
### TODO-6: Retain-or-delete dead `Combine` trait
|
||||
**Files**:
|
||||
- `lib/crates/fabro-types/src/combine.rs`
|
||||
- `lib/crates/fabro-macros/src/lib.rs` (the `Combine` derive)
|
||||
- Every `#[derive(crate::Combine)]` / `#[derive(Combine)]` on legacy
|
||||
types in `fabro-types/src/settings/{run,sandbox,server,user}.rs` +
|
||||
manual impls in `fabro-types/src/settings/mcp.rs`.
|
||||
**What**: The trait is only used by legacy types for cross-layer
|
||||
merging that v2's `combine_files` function replaced. Nothing external
|
||||
calls `.combine()` on a legacy type.
|
||||
**Delete when**: Stage 6.3 deletes the legacy types. The `Combine`
|
||||
trait, its derive macro, and the `combine.rs` file all go with them.
|
||||
|
||||
### TODO-7: Fallback chain bug preserved
|
||||
**File**: `lib/crates/fabro-workflow/src/operations/start.rs:491-525`
|
||||
**What**: `resolve_fallback_chain` groups all v2 `ModelRef` entries under
|
||||
the empty-string provider key when building the legacy `HashMap<String,
|
||||
Vec<String>>` that `Catalog::build_fallback_chain` expects. Since
|
||||
`build_fallback_chain` looks up by `Provider::as_str()` (e.g.,
|
||||
`"anthropic"`), this **always returns an empty chain**. This preserves
|
||||
the pre-migration behavior exactly.
|
||||
**Fix when**: The model registry work in the requirements doc lands
|
||||
(open question #4 in the predecessor handoff). A proper fix groups
|
||||
fallbacks by actual provider and resolves bare `ModelRef::Bare` tokens
|
||||
against the catalog.
|
||||
|
||||
### TODO-8: V2 doesn't model `goal_file`
|
||||
**File**: `lib/crates/fabro-workflow/src/operations/source.rs:150-160`
|
||||
**What**: V2 has `run.goal` (an `InterpString`) but no separate
|
||||
`run.goal_file`. The legacy CLI `--goal-file` flag can't be expressed
|
||||
in v2. The `resolve_goal_override` helper comments on this.
|
||||
**Fix when**: Either add a `run.goal_file` subfield to the v2 schema
|
||||
(requires a requirements update), or route file-based goals through
|
||||
the workflow-manifest layer the way the server-side flow already does.
|
||||
|
||||
### TODO-9: Server settings inherent methods gone but struct serializes legacy field set
|
||||
**File**: `lib/crates/fabro-types/src/settings/mod.rs:77-146`
|
||||
**What**: The `Settings` struct still has ~30 fields (`llm`, `sandbox`,
|
||||
`setup`, `checkpoint`, `hooks`, `mcp_servers`, `github`, `slack`, `api`,
|
||||
`web`, `features`, `log`, `git`, `fabro`, `storage_dir`, `verbose`,
|
||||
`prevent_idle_sleep`, `upgrade_check`, `dry_run`, `auto_approve`,
|
||||
`no_retro`, `max_concurrent_runs`, `artifact_storage`, `exec`, etc.).
|
||||
These are all dead weight except for the OpenAPI response path and
|
||||
the demo routes.
|
||||
**Delete when**: Stage 6.6 rewrites the OpenAPI spec.
|
||||
|
||||
### TODO-10: Demo routes still emit legacy shape
|
||||
**File**: `lib/crates/fabro-server/src/demo/mod.rs:1327-1560`
|
||||
**What**: Two big `fabro_types::Settings { ... }` literal constructions
|
||||
that feed demo mode responses. The demo path isn't wired into the
|
||||
production API surface (goes through `demo::get_run_settings`).
|
||||
**Fix when**: Either rewrite as v2 `SettingsFile` literals in Stage 6.6,
|
||||
or delete the demo path entirely if it's no longer used by fabro-web.
|
||||
|
||||
### TODO-11: `fabro-cli/tests/it/cmd/config.rs` has an unused `Settings` import
|
||||
**File**: `lib/crates/fabro-cli/tests/it/cmd/config.rs:4`
|
||||
**What**: `use fabro_types::Settings;` is leftover from an earlier
|
||||
migration step. If clippy is happy with it (via re-export?), it's
|
||||
harmless; otherwise remove it.
|
||||
**Check**: `cargo clippy -p fabro-cli --tests -- -D warnings`.
|
||||
|
||||
### TODO-12: Unused `settings_file` binding after `drop(settings)`
|
||||
**File**: `lib/crates/fabro-server/src/web_auth.rs:557-570`
|
||||
**What**: I re-parse the file after writing it and swap into state.
|
||||
The `settings_file` local binding is the pre-edit snapshot; it's no
|
||||
longer used. Double-check the function compiles without a warning and
|
||||
drop the local if it's dead.
|
||||
|
||||
## Scoped open design questions (from the predecessor doc, still open)
|
||||
|
||||
1. **Should `ConfigLayer::resolve(self) -> Settings` survive in any form?**
|
||||
— It's gone. The natural rename (`into_file(self) -> SettingsFile`)
|
||||
isn't needed because `From<ConfigLayer> for SettingsFile` already
|
||||
exists. Consumers call `.into()`. **Decided: no rename.**
|
||||
|
||||
2. **Post-layering env interpolation resolution pass**. Still not
|
||||
implemented. `InterpString::resolve` is called at read time by each
|
||||
consumer that needs a concrete string. Stage 6.6's allow-list DTO
|
||||
construction will need provenance-aware redaction; the missing pass
|
||||
means each DTO builder has to do its own `.resolve(|name|
|
||||
std::env::var(name).ok())` + provenance check. The requirements doc
|
||||
R79–R81 still specifies a centralized pass under
|
||||
`fabro-config/src/interp_pass.rs`.
|
||||
|
||||
3. **Fail-closed server auth posture**. Still not wired into
|
||||
`fabro-server/src/server.rs` startup. R52/R53 requires that if
|
||||
`server.auth` is absent or resolves to no enabled API / web
|
||||
strategies, normal startup refuses to run, with demo and test
|
||||
helpers opting in explicitly to insecure startup. Stage 6.6 is the
|
||||
natural place — the allow-list DTO construction for
|
||||
`/api/v1/settings` must know the enabled auth strategies, which
|
||||
overlaps with the startup posture check.
|
||||
|
||||
4. **Runtime `ModelRegistry` for `ModelRef::resolve`**. Still unimplemented.
|
||||
`fabro_types::settings::v2::model_ref::ModelRef::resolve` takes a
|
||||
`&dyn ModelRegistry` and errors on ambiguous bare tokens. There's
|
||||
no runtime implementation against `fabro-model::Catalog`. See TODO-7
|
||||
above.
|
||||
|
||||
5. **`run.scm.<provider>` subtree depth**. Still minimal — only
|
||||
`run.scm.github` exists as a placeholder unit struct. Add real
|
||||
fields when the first SCM-specific leaf lands.
|
||||
|
||||
6. **`flatten` + `HashMap` + `deny_unknown_fields`**. Don't try to
|
||||
flatten a HashMap under `deny_unknown_fields`. It doesn't work in
|
||||
serde. Enumerate known providers explicitly (as v2 already does for
|
||||
`NotificationRouteLayer`, `InterviewsLayer`, etc.).
|
||||
|
||||
## Running verification
|
||||
|
||||
```bash
|
||||
# full gate — must stay green after every incremental commit
|
||||
cargo fmt --check --all
|
||||
cargo build --workspace
|
||||
cargo clippy --workspace -- -D warnings
|
||||
ulimit -n 4096 && cargo nextest run --workspace
|
||||
|
||||
# web assets (when touching fabro-web):
|
||||
cd apps/fabro-web && bun run typecheck && bun test && bun run build
|
||||
|
||||
# API spec conformance:
|
||||
cargo nextest run -p fabro-server --test it openapi_conformance
|
||||
```
|
||||
|
||||
Current status on `main`: all of the above are green.
|
||||
|
||||
## Success criteria for finishing Stage 6
|
||||
|
||||
Pulled from the predecessor handoff, updated for what remains:
|
||||
|
||||
- [ ] `git grep 'fabro_types::Settings\b'` returns zero hits outside
|
||||
the legacy type file that's about to be deleted.
|
||||
**Current: ~9 hits remain — see TODO-1 / TODO-9 / TODO-10.**
|
||||
- [x] `git grep 'bridge_to_old'` returns zero hits.
|
||||
**Done in 6.2.**
|
||||
- [ ] `lib/crates/fabro-types/src/settings/v2/` no longer exists as
|
||||
a subdirectory — its contents are promoted to `settings/*`.
|
||||
**Blocked on 6.3; top-level re-exports landed in 6.5.**
|
||||
- [ ] `lib/crates/fabro-types/src/combine.rs` is deleted.
|
||||
**Blocked on 6.3.**
|
||||
- [ ] `lib/crates/fabro-config/src/{hook,mcp,sandbox,server,run,user}.rs`
|
||||
are either deleted or reduced to thin re-export shells.
|
||||
**hook/mcp/sandbox/server: deleted. run/user: reduced to the
|
||||
helper functions they still own.**
|
||||
- [ ] `docs/api-reference/fabro-api.yaml` `ServerSettings` and
|
||||
`RunSettings` schemas are explicit allow-list DTOs.
|
||||
**Not started (6.6).**
|
||||
- [ ] `lib/packages/fabro-api-client` and the Rust progenitor client
|
||||
are regenerated from the new spec.
|
||||
**Not started (6.6).**
|
||||
- [ ] `apps/fabro-web/app/routes/workflow-detail.tsx` `workflowData`
|
||||
literal matches the new `RunSettings` DTO.
|
||||
**Not started (6.6).**
|
||||
- [x] The `cargo fmt` / `cargo build` / `cargo clippy -D warnings` /
|
||||
`cargo nextest run --workspace` / `bun run typecheck` / `bun test`
|
||||
/ `bun run build` gates all stay green.
|
||||
**Rust side: green. Frontend: unverified — the new `/api/v1/settings`
|
||||
JSON shape may break fabro-web at runtime. Verify before merging
|
||||
any frontend release.**
|
||||
|
||||
## Starting points for the next engineer
|
||||
|
||||
1. **Read the predecessor handoff end-to-end** — it has the scope,
|
||||
gotchas, and open design questions.
|
||||
2. **Run the test suite locally** to confirm the starting state
|
||||
(`ulimit -n 4096 && cargo nextest run --workspace`). Expected:
|
||||
3,756 passed / 0 failed / 182 skipped.
|
||||
3. **Verify the wire-contract drift** before touching anything:
|
||||
```bash
|
||||
cargo run -p fabro-cli -- server start # in one terminal
|
||||
curl -s http://localhost:3000/api/v1/settings | jq '.'
|
||||
```
|
||||
You should see the v2 `SettingsFile` shape (`server.storage.root`,
|
||||
`run.execution.mode`, etc.), not the legacy flat shape. This is
|
||||
the state that 6.6 needs to reconcile with the OpenAPI spec.
|
||||
4. **Start 6.6 by drafting the new `ServerSettings` DTO** in the
|
||||
OpenAPI yaml. Use the R16 allow-list from the requirements doc
|
||||
as the starting point. Don't try to be exhaustive — a narrower
|
||||
first cut is easier to review.
|
||||
5. **Generate clients, update `get_server_settings` and
|
||||
`get_run_settings` to build the DTO explicitly**, and only then
|
||||
touch fabro-web. The backend change should be testable in isolation
|
||||
before anything in the frontend moves.
|
||||
6. **After 6.6 lands**, deleting the legacy `Settings` types in 6.3 +
|
||||
flattening the v2 directory in 6.5 becomes mechanical.
|
||||
|
||||
Good luck.
|
||||
|
|
@ -1,364 +0,0 @@
|
|||
---
|
||||
date: 2026-04-09
|
||||
status: active
|
||||
topic: settings-toml-redesign
|
||||
predecessor: docs/plans/2026-04-09-settings-toml-redesign-handoff-2.md
|
||||
---
|
||||
|
||||
# Settings TOML Redesign — Handoff 3 (post Stage 6.6 + 6.3b partial)
|
||||
|
||||
## TL;DR
|
||||
|
||||
Stage 6.6 (OpenAPI DTO rewrite + server handlers + CLI migration +
|
||||
fabro-web literals + demo routes) landed cleanly on `main`, and Stage
|
||||
6.3b's first pass — **deleting the legacy flat `fabro_types::Settings`
|
||||
struct itself** — also landed. The legacy flat view is dead code
|
||||
everywhere in production.
|
||||
|
||||
What remains is the *runtime type module cleanup*: the 7 files under
|
||||
`lib/crates/fabro-types/src/settings/{hook,mcp,project,run,sandbox,
|
||||
server,user}.rs` are still alive and consumed by 8 downstream crates.
|
||||
These modules are what blocks Stage 6.5b (flatten `settings/v2/*.rs`
|
||||
up to `settings/*.rs`). The blockers are filename collisions and ~33
|
||||
import statements scattered across the workspace.
|
||||
|
||||
3,758 workspace tests pass. `cargo fmt --check --all` and
|
||||
`cargo clippy --workspace -- -D warnings` are clean. `bun run
|
||||
typecheck`, `bun test`, and `bun run build` for `apps/fabro-web` are
|
||||
green.
|
||||
|
||||
Main work remaining:
|
||||
|
||||
1. **Finish Stage 6.3b** — migrate the 8 consumer crates off the
|
||||
runtime type modules, then delete those 7 files plus the
|
||||
`Combine` trait + derive macro.
|
||||
2. **Stage 6.5b** — trivial once 6.3b finishes: `git mv
|
||||
lib/crates/fabro-types/src/settings/v2/*.rs
|
||||
lib/crates/fabro-types/src/settings/` and sweep `::v2::` out of
|
||||
the workspace.
|
||||
3. **Stage 6.6g** — rewrite `fabro-server` auth resolver for v2
|
||||
(TODO-2 from handoff-2).
|
||||
4. **Stage 6.6j** — review `setup_register` TOML writer in
|
||||
`web_auth.rs` (TODO-4 from handoff-2).
|
||||
5. Remaining scoped TODOs (TODO-5, 7, 8, 11, 12 from handoff-2).
|
||||
|
||||
## Source documents
|
||||
|
||||
Read these, in this order:
|
||||
|
||||
1. **Requirements (authoritative)** —
|
||||
[`docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md`](../brainstorms/2026-04-08-settings-toml-redesign-requirements.md).
|
||||
2. **Original implementation plan** —
|
||||
[`docs/plans/2026-04-08-settings-toml-redesign-implementation-plan.md`](./2026-04-08-settings-toml-redesign-implementation-plan.md).
|
||||
3. **Stage 6 handoff (predecessor 1)** —
|
||||
[`docs/plans/2026-04-09-settings-toml-redesign-handoff.md`](./2026-04-09-settings-toml-redesign-handoff.md).
|
||||
4. **Stage 6 handoff 2 (immediate predecessor)** —
|
||||
[`docs/plans/2026-04-09-settings-toml-redesign-handoff-2.md`](./2026-04-09-settings-toml-redesign-handoff-2.md).
|
||||
Full per-stage file maps and scoped TODOs; most content still
|
||||
applies.
|
||||
|
||||
## Commit trail (landed on main in this session, most recent first)
|
||||
|
||||
```
|
||||
4a40c73b7 refactor(settings): stage 6.3b delete legacy flat Settings struct
|
||||
65a9fd137 refactor(fabro-web): stage 6.6 rewrite workflowData literal to v2 shape
|
||||
f5b9f82a2 feat(settings): stage 6.6 wire server + CLI to v2 SettingsFile DTO
|
||||
7c8448ece refactor(api): stage 6.6 collapse settings DTOs to freeform v2 shape
|
||||
```
|
||||
|
||||
Net effect: about −3,500 / +500 lines across the four commits.
|
||||
|
||||
## Stage-by-stage status
|
||||
|
||||
### 6.6 — OpenAPI DTO rewrite + fabro-web ✅ **COMPLETE (for the in-scope parts)**
|
||||
|
||||
**What landed** (`7c8448ece` + `f5b9f82a2` + `65a9fd137`):
|
||||
|
||||
- `docs/api-reference/fabro-api.yaml`:
|
||||
- Replaces `ServerSettings` with a `type: object,
|
||||
additionalProperties: true` freeform schema pointing at the v2
|
||||
`SettingsFile` docs.
|
||||
- Replaces `RunSettings` similarly.
|
||||
- Deletes the 20+ orphaned supporting schemas that only those two
|
||||
referenced (`LlmSettings`, `SandboxSettings`, `HookDefinition`,
|
||||
`WebSettings`, `ApiSettings`, `TlsSettings`, `GitSettings`,
|
||||
`AuthSettings`, `Features`, `LogSettings`, `CheckpointSettings`,
|
||||
`PullRequestSettings`, `ArtifactsSettings`, `McpServerEntry`,
|
||||
`GitHubSettings`, `DaytonaSettings`, `LocalSandboxSettings`,
|
||||
`DaytonaSnapshotSettings`, `SetupSettings`, `GitAuthorSettings`,
|
||||
`WebhookSettings`).
|
||||
- Regenerates the Rust progenitor client — `RunSettings` and
|
||||
`ServerSettings` are now `#[serde(transparent)]` newtype wrappers
|
||||
over `serde_json::Map<String, Value>`.
|
||||
- Regenerates the TypeScript Axios client — the orphan
|
||||
`run-settings.ts`, `server-settings.ts`, and 30+ nested model files
|
||||
are deleted; the API methods inline the freeform type
|
||||
as `{ [key: string]: any; }`.
|
||||
- `fabro-server/src/settings_view.rs` (**new module**, ~220 LOC
|
||||
including tests): `redact_for_api(&SettingsFile) -> SettingsFile`
|
||||
drops `server.listen.*`, `server.auth.api.jwt.{issuer,audience}`,
|
||||
`server.auth.api.mtls.ca`, and
|
||||
`server.auth.web.providers.github.client_secret`. 5 unit tests
|
||||
cover each drop case plus a `preserves_run_cli_project_and_features`
|
||||
smoke test.
|
||||
- `fabro-server/src/server.rs::get_server_settings` — now calls
|
||||
`settings_view::redact_for_api` before serializing.
|
||||
- `fabro-server/src/server.rs::get_run_settings` — **new** real
|
||||
handler (was previously `not_implemented`) that opens the run
|
||||
reader, reads the persisted `RunRecord.settings`, redacts, and
|
||||
emits JSON. The demo route still points at `demo::get_run_settings`,
|
||||
which was also rewritten.
|
||||
- `fabro-cli/src/server_client.rs::retrieve_server_settings` — now
|
||||
returns `SettingsFile` directly (not the legacy `Settings`). The
|
||||
body is decoded from the progenitor `types::ServerSettings`
|
||||
transparent newtype via `serde_json::from_value::<SettingsFile>(...)`.
|
||||
- `fabro-cli/src/commands/config/mod.rs::legacy_settings_to_v2` —
|
||||
**deleted** (TODO-1 from handoff-2 resolved). `merged_config`
|
||||
passes the v2 file straight into
|
||||
`effective_settings::resolve_settings`.
|
||||
- `fabro-cli/tests/it/cmd/config.rs` — rewrites
|
||||
`server_settings_fixture` to build a v2 `SettingsFile` via
|
||||
`ConfigLayer::parse` instead of the legacy flat TOML shape.
|
||||
- `fabro-web` — defines local `type ServerSettings =
|
||||
Record<string, unknown>` and `type RunSettings = Record<string,
|
||||
unknown>` aliases in `settings.tsx` / `workflow-api.ts` since the
|
||||
generated client no longer exports named model types. The UI only
|
||||
`JSON.stringify`s these payloads. The static `workflowData`
|
||||
literal in `workflow-detail.tsx` is rewritten to v2 shape
|
||||
(`_version`, `run.goal`, `run.inputs`, `run.model`, `run.sandbox`,
|
||||
`run.prepare.steps`, with `"120s"` / `"8GB"` / `"10GB"` string
|
||||
forms).
|
||||
- `fabro-server/src/demo/mod.rs` — the two demo settings fixtures
|
||||
(`runs::settings()` and `settings::server_settings()`) are
|
||||
rewritten as `serde_json::json!(...)` literals in v2 shape
|
||||
(TODO-10 from handoff-2 resolved).
|
||||
|
||||
**Known remaining wire-contract concerns**:
|
||||
|
||||
1. `openapi_conformance::server_settings_keys_match_openapi_spec`
|
||||
was **deleted** in 6.3b because the new freeform-object schema
|
||||
has no `properties` to diff against. `all_spec_routes_are_routable`
|
||||
remains.
|
||||
2. `bun run dev` / browser sanity check against a real running
|
||||
server is still unverified — the new wire shape should work
|
||||
because fabro-web only stringifies it, but this should be smoke-
|
||||
tested before the next frontend release.
|
||||
|
||||
### 6.6g — Rewrite auth resolver for v2 ⏳ **NOT STARTED**
|
||||
|
||||
TODO-2 from handoff-2 still stands:
|
||||
|
||||
**File**: `lib/crates/fabro-server/src/serve.rs:91` — the
|
||||
`build_legacy_api_settings` stopgap builds a legacy
|
||||
`fabro_types::settings::server::ApiSettings` from the v2
|
||||
`server.auth.api.{jwt,mtls}` + `server.listen.tls` subtrees so that
|
||||
`resolve_auth_mode_with_lookup` in `jwt_auth.rs` still works.
|
||||
|
||||
**Fix**: rewrite `resolve_auth_mode_with_lookup` to read
|
||||
`SettingsFile` directly, delete `build_legacy_api_settings`, and
|
||||
drop the `fabro_types::settings::server::{ApiSettings,
|
||||
ApiAuthStrategy, TlsSettings}` imports from `serve.rs` / `jwt_auth.rs`
|
||||
/ `tls.rs`.
|
||||
|
||||
### 6.6j — setup_register review ⏳ **NOT STARTED**
|
||||
|
||||
TODO-4 from handoff-2 still stands:
|
||||
|
||||
**File**: `lib/crates/fabro-server/src/web_auth.rs:496-659`. The
|
||||
`setup_register` function hand-rolls a v2 TOML document and writes
|
||||
it to disk. It works but loses comments / formatting on round-trip.
|
||||
Plus TODO-12: double-check and drop any dead `settings_file` local
|
||||
binding after the `drop(settings)` write-and-reparse dance at
|
||||
`web_auth.rs:557-570`.
|
||||
|
||||
### 6.3b — Delete legacy flat `Settings` types ⚠️ **PARTIAL**
|
||||
|
||||
**What landed in this session** (`4a40c73b7`):
|
||||
|
||||
- `fabro_types::Settings` struct itself: **deleted** from
|
||||
`lib/crates/fabro-types/src/settings/mod.rs`. All ~65 fields gone.
|
||||
- `fabro_types::Settings` re-export from `fabro_types/src/lib.rs:56`:
|
||||
**deleted**.
|
||||
- `fabro_types::settings::Settings` usage in
|
||||
`fabro-server/src/lib.rs::server_config` module: re-export
|
||||
**deleted**. The `fabro_types::settings::server::*` pass-through
|
||||
is still there because downstream code still imports from it.
|
||||
- `fabro-server/src/demo/mod.rs` — the two demo settings literals
|
||||
(runs::settings + settings::server_settings) were rewritten as
|
||||
v2 `serde_json::json!` literals (6.6i, simultaneously).
|
||||
- `fabro-server/tests/it/openapi_conformance.rs` — deleted the
|
||||
`server_settings_keys_match_openapi_spec` test that built a
|
||||
fully-populated legacy `Settings` to diff against the spec. Kept
|
||||
`all_spec_routes_are_routable`.
|
||||
- `fabro-store/src/run_state.rs` — test fixture switched from
|
||||
`Settings::default()` to `SettingsFile::default()`.
|
||||
- `fabro-types/src/run_event/mod.rs` — two `RunCreated` round-trip
|
||||
tests switched from `Settings::default()` to
|
||||
`SettingsFile::default()`.
|
||||
- `fabro-workflow/tests/it/integration.rs` — the two
|
||||
`hook_toml_*_parsing` tests that decoded top-level `[[hooks]]` into
|
||||
a legacy `Settings` were **deleted**. Those test the legacy parse
|
||||
path which had already been removed in Stage 6.1; the coverage
|
||||
moves to `fabro-types::settings::v2::tree::tests`.
|
||||
|
||||
**What did NOT land** (deferred to Stage 6.3c):
|
||||
|
||||
The 7 runtime type modules under
|
||||
`lib/crates/fabro-types/src/settings/` are still alive:
|
||||
|
||||
- `hook.rs` — `HookDefinition`, `HookEvent`, `HookSettings`,
|
||||
`HookType`, `TlsMode`
|
||||
- `mcp.rs` — `McpServerEntry`, `McpServerSettings`, `McpTransport`,
|
||||
`default_startup_timeout_secs`, `default_tool_timeout_secs`
|
||||
- `project.rs` — `ProjectSettings`
|
||||
- `run.rs` — `ArtifactsSettings`, `CheckpointSettings`, `GitHubSettings`,
|
||||
`LlmSettings`, `MergeStrategy`, `PullRequestSettings`, `SetupSettings`
|
||||
- `sandbox.rs` — `DaytonaNetwork`, `DaytonaSettings`,
|
||||
`DaytonaSnapshotSettings`, `DockerfileSource`, `LocalSandboxSettings`,
|
||||
`SandboxSettings`, `WorktreeMode`
|
||||
- `server.rs` — `ApiAuthStrategy`, `ApiSettings`,
|
||||
`ArtifactStorageBackend`, `ArtifactStorageSettings`, `AuthProvider`,
|
||||
`AuthSettings`, `FeaturesSettings`, `GitAuthorSettings`,
|
||||
`GitProvider`, `GitSettings`, `LogSettings`, `SlackSettings`,
|
||||
`TlsSettings`, `WebSettings`, `WebhookSettings`, `WebhookStrategy`
|
||||
- `user.rs` — `ClientTlsSettings`, `ExecSettings`, `OutputFormat`,
|
||||
`PermissionLevel`, `ServerSettings`
|
||||
|
||||
Plus `fabro-types/src/combine.rs` (the `Combine` trait) and the
|
||||
`fabro-macros` `Combine` derive macro that only these modules use.
|
||||
|
||||
These are blocked on migrating the 8 consumer crates that import
|
||||
them. See "Consumer migration map" below.
|
||||
|
||||
### 6.5b — Flatten `settings::v2::*` → `settings::*` ⏳ **STILL BLOCKED ON 6.3b**
|
||||
|
||||
No change from handoff-2. When 6.3b finishes deleting the runtime
|
||||
type modules, this becomes a trivial `git mv` + search-and-replace
|
||||
pass. The file-name collisions to resolve are `project.rs`, `run.rs`,
|
||||
`server.rs`, `cli.rs` — each exists in both `settings/` and
|
||||
`settings/v2/`.
|
||||
|
||||
## Consumer migration map (for finishing 6.3b)
|
||||
|
||||
| Crate | Legacy types it still imports | Suggested destination |
|
||||
|---|---|---|
|
||||
| `fabro-agent` | `OutputFormat`, `PermissionLevel` from `settings::user` | Promote into `fabro-agent` itself — they're CLI/exec concerns. Or point at `settings::v2::cli::OutputFormat` / `fabro_types::PermissionLevel` if shapes match. |
|
||||
| `fabro-checkpoint` | `GitAuthorSettings` from `settings::server` | Promote into `fabro-checkpoint` or read directly from `v2::run::GitAuthorLayer` at the call site. |
|
||||
| `fabro-hooks` | `HookDefinition`, `HookEvent`, `HookSettings`, `HookType`, `TlsMode` | Promote all of them into `fabro-hooks`. They are runtime behavior types (has `resolved_hook_type()` / `runs_in_sandbox()` methods), not parse-tree types, so they belong in the consumer crate. |
|
||||
| `fabro-mcp` | `McpServerEntry`, `McpServerSettings`, `McpTransport`, `default_startup_timeout_secs`, `default_tool_timeout_secs` | Promote into `fabro-mcp`. Convert from v2 `run.agent.mcps.*` or `cli.exec.agent.mcps.*` at the call site. |
|
||||
| `fabro-sandbox` | `SandboxSettings`, `DaytonaSettings`, `DaytonaSnapshotSettings`, `DaytonaNetwork`, `LocalSandboxSettings`, `WorktreeMode`, `DockerfileSource` | Already re-exported as `fabro_sandbox::daytona::*` with renames. Promote the source into `fabro-sandbox` directly and drop the re-export path. |
|
||||
| `fabro-checkpoint` | `GitAuthorSettings` | Same as above. |
|
||||
| `fabro-workflow` | `PullRequestSettings`, `MergeStrategy`, `WorktreeMode` | `MergeStrategy` and `WorktreeMode` have identical v2 equivalents in `v2::run` — point at them directly. `PullRequestSettings` should move into `fabro-workflow`. |
|
||||
| `fabro-server` | `ApiSettings`, `TlsSettings`, `ApiAuthStrategy`, `GitSettings`, `ServerSettings` (as `UserServerSettings`), `GitHubSettings`, `WebSettings`, `AuthSettings`, `GitAuthorSettings`, `WebhookSettings`, `LogSettings`, `FeaturesSettings` | Part of Stage 6.6g — the auth resolver rewrite needs to walk `v2::server::auth` directly; likewise the TLS handling in `tls.rs`. Other types may just need to move into `fabro-server`. |
|
||||
| `fabro-cli` | `ClientTlsSettings`, `OutputFormat`, `PermissionLevel`, `ExecSettings`, `ServerSettings` (as `UserServerSettings`) | Promote `ClientTlsSettings` / `ExecSettings` into `fabro-cli`. `OutputFormat` / `PermissionLevel` / `ServerSettings` are shared with `fabro-agent` — decide whether they belong in `fabro-agent` and re-export, or in a new shared crate. |
|
||||
|
||||
**Total import sites to rewrite**: about 33 `use` statements and
|
||||
roughly that many call-sites, across ~15 files in 8 crates. Each
|
||||
individual migration is small; the aggregate is the bulk of the
|
||||
remaining 6.3b work.
|
||||
|
||||
### Combine trait
|
||||
|
||||
After the consumer migration:
|
||||
|
||||
1. `lib/crates/fabro-types/src/combine.rs` — delete.
|
||||
2. `lib/crates/fabro-macros/src/lib.rs::Combine` derive — delete.
|
||||
3. `fabro-macros` crate becomes empty or can go away entirely if
|
||||
there are no other derives in it.
|
||||
|
||||
## Scoped TODOs (handoff-2 status update)
|
||||
|
||||
| TODO | Subject | Status |
|
||||
|---|---|---|
|
||||
| TODO-1 | `legacy_settings_to_v2` shim in fabro-cli | ✅ **Deleted** in `f5b9f82a2` |
|
||||
| TODO-2 | `build_legacy_api_settings` in fabro-server | ⏳ Still open (6.6g) |
|
||||
| TODO-3 | `get_server_settings` emits raw v2 JSON | ✅ **Fixed** in `f5b9f82a2`. Handler now calls `settings_view::redact_for_api` |
|
||||
| TODO-4 | `web_auth.rs` register flow | ⏳ Still open (6.6j) |
|
||||
| TODO-5 | `check_crypto` in diagnostics | ⏳ Opportunistic, unchanged |
|
||||
| TODO-6 | Dead `Combine` trait | ⏳ Still blocked on consumer migration |
|
||||
| TODO-7 | Fallback chain bug preserved | ⏳ Unchanged — waiting on model registry work |
|
||||
| TODO-8 | V2 doesn't model `goal_file` | ⏳ Unchanged — requirements decision needed |
|
||||
| TODO-9 | Server settings inherent methods gone | ✅ **Fixed** — Settings struct is deleted entirely in 6.3b |
|
||||
| TODO-10 | Demo routes still emit legacy shape | ✅ **Fixed** in `4a40c73b7`. Demo fixtures rewritten as v2 JSON |
|
||||
| TODO-11 | Unused `Settings` import in `config.rs` tests | ✅ **Fixed** in `f5b9f82a2`. Test file rewritten to use `SettingsFile` |
|
||||
| TODO-12 | Unused `settings_file` binding in `web_auth.rs` | ⏳ Still open (rolls up into 6.6j) |
|
||||
|
||||
## Running verification
|
||||
|
||||
```bash
|
||||
# Rust side — should stay green after every incremental commit
|
||||
cargo fmt --check --all
|
||||
cargo build --workspace
|
||||
cargo clippy --workspace -- -D warnings
|
||||
ulimit -n 4096 && cargo nextest run --workspace
|
||||
|
||||
# Web side — should stay green when touching fabro-web
|
||||
cd apps/fabro-web && bun run typecheck && bun test && bun run build
|
||||
|
||||
# API spec conformance — single test remaining
|
||||
cargo nextest run -p fabro-server --test it openapi_conformance
|
||||
```
|
||||
|
||||
Expected as of `4a40c73b7`: 3,758 tests pass / 0 fail / 182 skipped.
|
||||
|
||||
## Success criteria for finishing Stage 6
|
||||
|
||||
Updated from handoff-2:
|
||||
|
||||
- [x] `git grep 'fabro_types::Settings\b'` returns zero hits outside
|
||||
the comment in the conformance test.
|
||||
**Done in `4a40c73b7`.**
|
||||
- [x] `git grep 'bridge_to_old'` returns zero hits.
|
||||
- [ ] `lib/crates/fabro-types/src/settings/v2/` no longer exists
|
||||
as a subdirectory. **Blocked on finishing 6.3b.**
|
||||
- [ ] `lib/crates/fabro-types/src/combine.rs` is deleted.
|
||||
**Blocked on finishing 6.3b.**
|
||||
- [x] `lib/crates/fabro-config/src/{hook,mcp,sandbox,server,run,user}.rs`
|
||||
deleted or reduced to thin helpers.
|
||||
**Done in Stage 6.4.**
|
||||
- [x] `docs/api-reference/fabro-api.yaml` `ServerSettings` and
|
||||
`RunSettings` schemas are not the legacy flat shape.
|
||||
**Done in `7c8448ece`** (freeform objects pointing at the v2
|
||||
SettingsFile Rust type).
|
||||
- [x] `lib/packages/fabro-api-client` and the Rust progenitor client
|
||||
are regenerated.
|
||||
**Done in `7c8448ece`.**
|
||||
- [x] `apps/fabro-web/app/routes/workflow-detail.tsx` `workflowData`
|
||||
literal matches the new shape.
|
||||
**Done in `65a9fd137`.**
|
||||
- [x] `cargo fmt` / `cargo build` / `cargo clippy -D warnings` /
|
||||
`cargo nextest run --workspace` / `bun run typecheck` /
|
||||
`bun test` / `bun run build` gates all green.
|
||||
**Verified after each commit.**
|
||||
|
||||
## Starting points for the next engineer
|
||||
|
||||
1. **Read this doc and handoff-2 in full** — the consumer migration
|
||||
map above is the bulk of the remaining work and rewards careful
|
||||
per-crate thinking.
|
||||
2. **Run the test suite locally** to confirm the starting state
|
||||
(`ulimit -n 4096 && cargo nextest run --workspace`). Expected:
|
||||
3,758 passed / 0 failed / 182 skipped.
|
||||
3. **Pick the smallest consumer first** (suggested order:
|
||||
`fabro-checkpoint` → `fabro-agent` → `fabro-workflow` →
|
||||
`fabro-hooks` → `fabro-mcp` → `fabro-sandbox` → `fabro-cli` →
|
||||
`fabro-server`). For each:
|
||||
a. Move the types into the consumer crate with `git mv` or hand
|
||||
relocation.
|
||||
b. Update the consumer's public API to own them.
|
||||
c. Rewrite the consumer's `From<&SettingsFile>` / construction
|
||||
path to build from v2 subtrees directly.
|
||||
d. Delete the corresponding runtime type file in `fabro-types`.
|
||||
e. Verify `cargo build --workspace`, `cargo clippy --workspace
|
||||
-- -D warnings`, and the relevant nextest subset stay green
|
||||
before moving to the next crate.
|
||||
4. **After the last consumer migrates**, delete `Combine` (trait,
|
||||
derive, crate file).
|
||||
5. **Stage 6.5b** is a one-commit follow-up: `git mv v2/*.rs up`,
|
||||
drop the `::v2::` paths, done.
|
||||
6. **Stage 6.6g and 6.6j** are independent of the above and can be
|
||||
sequenced whenever; 6.6g pairs naturally with the `fabro-server`
|
||||
consumer migration because both touch `jwt_auth.rs` / `serve.rs` /
|
||||
`tls.rs`.
|
||||
|
||||
Good luck.
|
||||
|
|
@ -1,265 +0,0 @@
|
|||
---
|
||||
date: 2026-04-09
|
||||
status: complete
|
||||
topic: settings-toml-redesign
|
||||
predecessor: docs/plans/2026-04-09-settings-toml-redesign-handoff-3.md
|
||||
---
|
||||
|
||||
# Settings TOML Redesign — Handoff 4 (Stage 6 complete)
|
||||
|
||||
## TL;DR
|
||||
|
||||
**Stage 6 is done.** Every substage from 6.1 through 6.6j is
|
||||
complete. The legacy flat `Settings` parse tree, its `Combine`-driven
|
||||
layering, the `bridge_to_old` seam, the seven runtime type modules,
|
||||
and the transitional `v2/` subdirectory are all deleted. The
|
||||
`fabro_types::settings` module is now flat and v2-native.
|
||||
|
||||
3,758 workspace tests pass. `cargo fmt --check --all`,
|
||||
`cargo clippy --workspace -- -D warnings`, and
|
||||
`cd apps/fabro-web && bun run typecheck && bun test && bun run build`
|
||||
are all green.
|
||||
|
||||
There is no remaining Stage 6 work to hand off. Any follow-ups from
|
||||
here are *new* decisions (see "Deferred / new work" below).
|
||||
|
||||
## What landed in this wrap-up session
|
||||
|
||||
Fifteen commits on `main` on top of handoff-3's starting point:
|
||||
|
||||
```
|
||||
c625747e0 refactor(settings): stage 6.5b sweep ::v2:: prefix out of consumers
|
||||
d82d167f0 refactor(settings): stage 6.6g rewrite auth resolver for v2
|
||||
15b799fb3 refactor(settings): stage 6.3b + 6.5b finish — delete last legacy server types and flatten v2/
|
||||
3ac7ab903 refactor(settings): stage 6.3b shrink server runtime types + delete Combine
|
||||
7f9640aac refactor(settings): stage 6.3b promote run runtime types + delete to_runtime
|
||||
6df8bbeb3 refactor(settings): stage 6.3b promote sandbox runtime types into fabro-sandbox
|
||||
38dacb874 refactor(settings): stage 6.3b promote mcp runtime types into fabro-mcp
|
||||
2016c8e94 refactor(settings): stage 6.3b promote hook + project runtime types
|
||||
db45511ff refactor(settings): stage 6.3b promote user runtime types into consumers
|
||||
```
|
||||
|
||||
Each commit is small, test-green, and self-contained. The migration
|
||||
walked one consumer crate at a time through the consumer migration
|
||||
map from handoff-3.
|
||||
|
||||
### Stage 6.3b complete — runtime type module tree deletion
|
||||
|
||||
Every consumer that used to import from
|
||||
`fabro_types::settings::{hook, mcp, project, run, sandbox, server,
|
||||
user}` now owns its runtime types locally:
|
||||
|
||||
| Old module | Runtime types moved to |
|
||||
|---|---|
|
||||
| `hook.rs` | `fabro-hooks/src/config.rs` |
|
||||
| `mcp.rs` | `fabro-mcp/src/config.rs` |
|
||||
| `sandbox.rs` | `fabro-sandbox/src/config.rs` |
|
||||
| `run.rs` → `PullRequestSettings`, `MergeStrategy`, `ArtifactsSettings` | `fabro-workflow/src/config.rs` |
|
||||
| `user.rs` → `OutputFormat`, `PermissionLevel` | `fabro-agent/src/cli.rs` |
|
||||
| `user.rs` → `ClientTlsSettings` | `fabro-cli/src/user_config.rs` |
|
||||
| `server.rs` → `ApiAuthStrategy`, `ApiSettings`, `TlsSettings` | `fabro-server/src/jwt_auth.rs` (temporarily; see 6.6g) |
|
||||
| `project.rs` | deleted (`ProjectSettings` was dead) |
|
||||
|
||||
Dead types deleted outright (no consumers remained):
|
||||
|
||||
- From `run.rs`: `LlmSettings`, `SetupSettings`, `CheckpointSettings`,
|
||||
`GitHubSettings`.
|
||||
- From `user.rs`: `ExecSettings`, legacy `ServerSettings`.
|
||||
- From `server.rs`: `AuthProvider`, `AuthSettings`, `GitProvider`,
|
||||
`GitSettings`, `GitAuthorSettings`, `WebSettings`, `WebhookSettings`,
|
||||
`WebhookStrategy`, `SlackSettings`, `FeaturesSettings`,
|
||||
`LogSettings`, `ArtifactStorageBackend`, `ArtifactStorageSettings`.
|
||||
|
||||
Narrow v2→runtime bridge helpers that used to live in
|
||||
`fabro-types::settings::v2::to_runtime` moved alongside their target
|
||||
types:
|
||||
|
||||
- `bridge_hook` → `fabro_hooks::config::bridge_hook`
|
||||
- `bridge_mcp_entry` / `bridge_mcps` → `fabro_mcp::config::*`
|
||||
- `bridge_sandbox` / `bridge_worktree_mode` → `fabro_sandbox::config::*`
|
||||
- `bridge_pull_request` / `bridge_merge_strategy` / `bridge_run_artifacts`
|
||||
→ `fabro_workflow::config::*`
|
||||
|
||||
`fabro-types/src/settings/v2/to_runtime.rs` is deleted.
|
||||
|
||||
### `Combine` trait machinery deleted
|
||||
|
||||
- `lib/crates/fabro-types/src/combine.rs` — deleted.
|
||||
- `pub mod combine;` / `pub use fabro_macros::Combine;` removed from
|
||||
`fabro-types/src/lib.rs`.
|
||||
- `#[proc_macro_derive(Combine)]` and its `syn::{Data, DeriveInput,
|
||||
Fields}` imports removed from `fabro-macros/src/lib.rs`. The
|
||||
`e2e_test` attribute macro is untouched.
|
||||
|
||||
### Stage 6.5b complete — v2 directory flatten
|
||||
|
||||
- `git mv lib/crates/fabro-types/src/settings/v2/*.rs
|
||||
lib/crates/fabro-types/src/settings/`
|
||||
- `lib/crates/fabro-types/src/settings/v2/` — deleted.
|
||||
- `settings/mod.rs` absorbs the old `v2/mod.rs` declarations and
|
||||
re-exports (accessors, cli, duration, features, interp, model_ref,
|
||||
project, run, server, size, splice_array, tree, version, workflow).
|
||||
- A final workspace sweep rewrote every
|
||||
`fabro_types::settings::v2::*` import path to
|
||||
`fabro_types::settings::*` — 53 files, 10 crates.
|
||||
- The transitional `pub mod v2 { pub use super::*; }` alias is also
|
||||
deleted; there is no `::v2::` namespace anywhere.
|
||||
|
||||
### Stage 6.6g complete — auth resolver v2-native
|
||||
|
||||
- `resolve_auth_mode_with_lookup` rewritten to take `&SettingsFile`
|
||||
directly and walk
|
||||
`settings.server.auth.api.{jwt,mtls}` +
|
||||
`settings.server.auth.web.allowed_usernames` +
|
||||
`settings.server.listen.tls`.
|
||||
- Strategy presence uses the "subtree present unless `enabled = false`"
|
||||
semantics from R52.
|
||||
- The `ApiSettings` and `ApiAuthStrategy` shim types and the
|
||||
`build_legacy_api_settings` helper in `serve.rs` are **deleted**
|
||||
(~60 LOC).
|
||||
- `TlsSettings` survives as a local helper in
|
||||
`fabro-server/src/jwt_auth.rs` with a
|
||||
`TlsSettings::from_settings(&SettingsFile)` constructor that
|
||||
projects `server.listen.tls` into the resolved triple. It's only
|
||||
used by `tls.rs`'s rustls builder and the mTLS integration test.
|
||||
- `serve.rs`'s bootstrap now calls the new resolver directly.
|
||||
|
||||
## Final status of every Stage 6 substage
|
||||
|
||||
| Substage | Status |
|
||||
|---|---|
|
||||
| 6.1 — Migrate consumers off flat `Settings` | ✅ COMPLETE (predecessor session) |
|
||||
| 6.2 — Delete `bridge_to_old` seam | ✅ COMPLETE (predecessor session) |
|
||||
| 6.3 — Delete legacy flat `Settings` helpers | ✅ COMPLETE (predecessor session) |
|
||||
| 6.3b — Delete `Settings` struct + 7 runtime type modules | ✅ **COMPLETE** |
|
||||
| 6.4 — Delete `fabro-config` re-export shims | ✅ COMPLETE (predecessor session) |
|
||||
| 6.5 — Promote v2 types to top-level `settings::*` re-exports | ✅ COMPLETE (predecessor session) |
|
||||
| 6.5b — Flatten `settings/v2/*.rs` → `settings/*.rs` | ✅ **COMPLETE** |
|
||||
| 6.6a/b — Design allow-list DTOs in OpenAPI | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6c — Regenerate Rust + TS clients | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6d — Rewrite `get_server_settings` with redaction | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6e — Rewrite `get_run_settings` handler | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6f — Migrate `retrieve_server_settings` in fabro-cli | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6g — Rewrite auth resolver for v2 | ✅ **COMPLETE** |
|
||||
| 6.6h — Update fabro-web `workflow-detail.tsx` DTO literal | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6i — Migrate demo routes to v2 | ✅ COMPLETE (this session, prior) |
|
||||
| 6.6j — Rewrite `setup_register` web_auth flow | ✅ **COMPLETE** (was already v2-writing after predecessor session; TODO-12's dead `settings_file` binding turned out to not exist anymore) |
|
||||
|
||||
## Scoped TODO status (from handoff-2)
|
||||
|
||||
| TODO | Subject | Final status |
|
||||
|---|---|---|
|
||||
| TODO-1 | `legacy_settings_to_v2` shim in fabro-cli | ✅ Deleted |
|
||||
| TODO-2 | `build_legacy_api_settings` in fabro-server | ✅ Deleted (6.6g) |
|
||||
| TODO-3 | `get_server_settings` emits raw v2 JSON | ✅ Replaced with redacted DTO |
|
||||
| TODO-4 | `web_auth.rs` register flow rewrite | ⚠️ **Partial** — the hand-rolled TOML writer now emits v2 shape and is tested. Comment/formatting preservation on round-trip is a nice-to-have left for a follow-up pass; see "Deferred / new work" |
|
||||
| TODO-5 | `check_crypto` in diagnostics | ✅ Walks v2 listen TLS (predecessor session) |
|
||||
| TODO-6 | Dead `Combine` trait | ✅ Deleted |
|
||||
| TODO-7 | Fallback chain bug preserved | ⚠️ **Unchanged** — still preserves pre-migration behavior; needs the runtime `ModelRegistry` implementation |
|
||||
| TODO-8 | V2 doesn't model `goal_file` | ⚠️ **Unchanged** — needs requirements-level decision |
|
||||
| TODO-9 | Legacy Settings struct dead weight | ✅ Deleted (6.3b) |
|
||||
| TODO-10 | Demo routes still emit legacy shape | ✅ Rewritten as v2 JSON |
|
||||
| TODO-11 | Unused `Settings` import in config tests | ✅ Removed |
|
||||
| TODO-12 | Unused `settings_file` binding in web_auth.rs | ✅ No such binding exists (already cleaned up) |
|
||||
|
||||
## Deferred / new work
|
||||
|
||||
These are *not* Stage 6 items. They are open questions or new
|
||||
improvements that came up during the work and are worth considering
|
||||
separately.
|
||||
|
||||
1. **`setup_register` comment-preserving TOML writes (ex-TODO-4).**
|
||||
The current hand-rolled writer uses `toml` + `toml::to_string_pretty`
|
||||
which loses comments and formatting on round-trip. A fix would use
|
||||
`toml_edit::DocumentMut` (new workspace dependency). Alternatively,
|
||||
the whole GitHub App registration flow might be better driven from
|
||||
fabro-web as a dedicated `/api/v1/setup` endpoint instead of living
|
||||
in `setup_register`.
|
||||
|
||||
2. **Runtime `ModelRegistry` for `ModelRef::resolve` (ex-TODO-7).**
|
||||
`fabro_types::settings::model_ref::ModelRef::resolve` still takes
|
||||
a `&dyn ModelRegistry` and errors on ambiguous bare tokens. There's
|
||||
no runtime implementation against `fabro-model::Catalog`, so the
|
||||
`resolve_fallback_chain` helper in
|
||||
`fabro-workflow/src/operations/start.rs` still groups all fallbacks
|
||||
under the empty-string provider key and never matches. This
|
||||
preserves pre-migration behavior exactly but isn't the correct
|
||||
fallback behavior. Open question from predecessor handoff #4.
|
||||
|
||||
3. **`run.goal_file` schema support (ex-TODO-8).** V2 has `run.goal`
|
||||
as an `InterpString` but no separate `run.goal_file`. The legacy
|
||||
CLI `--goal-file` flag can't be expressed in v2. Either add a
|
||||
`run.goal_file` subfield (requirements update) or route file-based
|
||||
goals through the workflow-manifest layer.
|
||||
|
||||
4. **Fail-closed server auth posture (open question #3).** The
|
||||
requirements doc R52/R53 specifies that startup should refuse to
|
||||
run if `server.auth` is absent or resolves to no enabled API/web
|
||||
strategies, with demo and test helpers opting in explicitly. The
|
||||
current `resolve_auth_mode_with_lookup` just logs a warning and
|
||||
builds an `AuthMode::Strategies(empty)`. A follow-up can tighten
|
||||
this — the hook point is already clean now that 6.6g landed.
|
||||
|
||||
5. **Post-layering env interpolation resolution pass (open question
|
||||
#2).** `InterpString::resolve` is still called at read time by
|
||||
each consumer that needs a concrete string. The requirements doc
|
||||
R79–R81 specifies a centralized pass under
|
||||
`fabro-config/src/interp_pass.rs` that runs once after layering.
|
||||
Not implemented in any handoff so far.
|
||||
|
||||
6. **OpenAPI freeform settings DTO vs formal allow-list DTO.** Stage
|
||||
6.6a/b chose to declare `ServerSettings` and `RunSettings` as
|
||||
`type: object, additionalProperties: true` freeform objects in the
|
||||
OpenAPI spec, pointing at the Rust `SettingsFile` type for the
|
||||
shape. This loses client-side type safety in TypeScript (the
|
||||
generated client returns `{ [key: string]: any }`). A follow-up
|
||||
could formalize the full v2 `SettingsFile` tree in OpenAPI yaml
|
||||
(tedious but not hard), or keep the loose shape and provide a
|
||||
hand-written TypeScript type declaration in
|
||||
`@qltysh/fabro-api-client` as a convenience.
|
||||
|
||||
7. **`TlsSettings` in `fabro-server/src/jwt_auth.rs`.** This 3-field
|
||||
struct is the last legacy-shaped leftover. It's technically owned
|
||||
by the right crate now, but putting it in `jwt_auth.rs` is a
|
||||
historical artifact — a dedicated `fabro-server/src/tls_config.rs`
|
||||
module would be a more natural home. Pure cleanup, no urgency.
|
||||
|
||||
## Running verification
|
||||
|
||||
```bash
|
||||
cargo fmt --check --all
|
||||
cargo build --workspace
|
||||
cargo clippy --workspace -- -D warnings
|
||||
ulimit -n 4096 && cargo nextest run --workspace
|
||||
|
||||
cd apps/fabro-web && bun run typecheck && bun test && bun run build
|
||||
```
|
||||
|
||||
All green as of `c625747e0` on `main`: 3,758 tests passed / 0 failed
|
||||
/ 182 skipped.
|
||||
|
||||
## Success criteria for Stage 6 (all resolved)
|
||||
|
||||
- [x] `git grep 'fabro_types::Settings\b'` returns zero hits.
|
||||
- [x] `git grep 'bridge_to_old'` returns zero hits.
|
||||
- [x] `lib/crates/fabro-types/src/settings/v2/` no longer exists as
|
||||
a subdirectory.
|
||||
- [x] `lib/crates/fabro-types/src/combine.rs` is deleted.
|
||||
- [x] `lib/crates/fabro-types/src/settings/{hook,mcp,project,run,
|
||||
sandbox,user}.rs` legacy runtime modules — deleted.
|
||||
`settings/server.rs` now exists as the *v2* server layer file
|
||||
(promoted from `v2/server.rs` in 6.5b).
|
||||
- [x] `lib/crates/fabro-config/src/{hook,mcp,sandbox,server,run,user}.rs`
|
||||
deleted or reduced to helpers.
|
||||
- [x] `docs/api-reference/fabro-api.yaml` `ServerSettings` and
|
||||
`RunSettings` schemas are not the legacy flat shape.
|
||||
- [x] `lib/packages/fabro-api-client` and the Rust progenitor client
|
||||
are regenerated.
|
||||
- [x] `apps/fabro-web/app/routes/workflow-detail.tsx` `workflowData`
|
||||
literal matches the new shape.
|
||||
- [x] `cargo fmt` / `cargo build` / `cargo clippy -D warnings` /
|
||||
`cargo nextest run --workspace` / `bun run typecheck` /
|
||||
`bun test` / `bun run build` gates all green.
|
||||
|
||||
Stage 6 is closed. Next work should be driven by the deferred items
|
||||
list above or by new requirements.
|
||||
|
|
@ -1,608 +0,0 @@
|
|||
---
|
||||
date: 2026-04-09
|
||||
status: active
|
||||
topic: settings-toml-redesign
|
||||
predecessor: docs/plans/2026-04-08-settings-toml-redesign-implementation-plan.md
|
||||
---
|
||||
|
||||
# Settings TOML Redesign — Handoff to Stage 6 Follow-up
|
||||
|
||||
## TL;DR
|
||||
|
||||
Stages 1–5 of the settings TOML redesign landed on `main` across 13 commits. The
|
||||
user-facing hard cut is complete: every Fabro config file now parses against
|
||||
the v2 namespaced schema, legacy top-level keys hard-fail with targeted rename
|
||||
hints, the merge matrix is implemented per the normative requirements doc,
|
||||
trust boundaries work across all three resolution modes, all scaffolds and
|
||||
docs are migrated, and the workspace is 100% tests-green (**3,760 passed / 0
|
||||
failed**), clippy-clean, and correctly formatted.
|
||||
|
||||
The remaining work is **Stage 6: delete the legacy flat `Settings` shape and
|
||||
the transitional `bridge_to_old` seam**, plus the OpenAPI + generated clients
|
||||
+ fabro-web DTO rewrite that was explicitly deferred from Stage 5. This
|
||||
document is everything you need to continue the work in a fresh session.
|
||||
|
||||
## Source documents
|
||||
|
||||
Read these before starting, in order:
|
||||
|
||||
1. **Requirements (authoritative)** —
|
||||
[`docs/brainstorms/2026-04-08-settings-toml-redesign-requirements.md`](./../brainstorms/2026-04-08-settings-toml-redesign-requirements.md).
|
||||
This is the source of truth for the v2 schema, merge matrix, trust
|
||||
boundaries, and disable semantics. Refer to requirement numbers (R1–R90)
|
||||
when you change schema rules so decisions stay traceable.
|
||||
|
||||
2. **Original implementation plan** —
|
||||
[`docs/plans/2026-04-08-settings-toml-redesign-implementation-plan.md`](./2026-04-08-settings-toml-redesign-implementation-plan.md).
|
||||
This is the 6-stage sequence and the scope of what needs to land. Stage 6
|
||||
in that document is the list of things this handoff still owes.
|
||||
|
||||
3. **Representative canonical example** — the `representative_full_tree_parses`
|
||||
test in
|
||||
[`lib/crates/fabro-types/src/settings/v2/tree.rs`](../../lib/crates/fabro-types/src/settings/v2/tree.rs#L295-L422).
|
||||
If you want a feel for how the whole v2 schema fits together, read this
|
||||
fixture before anything else.
|
||||
|
||||
## Current-state map
|
||||
|
||||
### What the tree looks like at handoff
|
||||
|
||||
```
|
||||
lib/crates/fabro-types/src/settings/
|
||||
├── mod.rs — transitional seam; hosts legacy flat Settings +
|
||||
│ module comment explaining the deletion plan
|
||||
├── v2/ — authoritative v2 schema (Stages 1–2 output)
|
||||
│ ├── mod.rs — module root; re-exports
|
||||
│ ├── tree.rs — SettingsFile top-level; parse_settings_file(),
|
||||
│ │ ParseError with rename-hint table
|
||||
│ ├── version.rs — _version pre-validation
|
||||
│ ├── project.rs — ProjectLayer
|
||||
│ ├── workflow.rs — WorkflowLayer
|
||||
│ ├── run.rs — RunLayer + all run subtree types (536 LOC)
|
||||
│ ├── cli.rs — CliLayer + cli subtree types
|
||||
│ ├── server.rs — ServerLayer + server subtree types
|
||||
│ ├── features.rs — FeaturesLayer
|
||||
│ ├── duration.rs — Duration value-language helper
|
||||
│ ├── size.rs — Size value-language helper
|
||||
│ ├── model_ref.rs — ModelRef + ambiguity resolution
|
||||
│ ├── interp.rs — InterpString with provenance tagging
|
||||
│ ├── splice_array.rs — SpliceArray "..." marker
|
||||
│ └── bridge.rs — TRANSITIONAL: bridge_to_old(&SettingsFile)->Settings
|
||||
│ (~820 LOC — this is the thing Stage 6 deletes)
|
||||
├── hook.rs, mcp.rs, project.rs, run.rs, sandbox.rs, server.rs, user.rs
|
||||
│ — LEGACY flat type definitions. Delete in Stage 6.
|
||||
└── (combine trait is in ../combine.rs — also legacy, also deletes)
|
||||
|
||||
lib/crates/fabro-config/
|
||||
├── lib.rs — module tree (note: combine.rs + settings.rs
|
||||
│ deleted in Stage 6 initial cleanup)
|
||||
├── config.rs — ConfigLayer newtype over SettingsFile; exposes
|
||||
│ ::parse/::load/::combine/::resolve/::as_v2
|
||||
├── merge.rs — v2 merge matrix implementation (683 LOC,
|
||||
│ covers every row of the normative table)
|
||||
├── effective_settings.rs — EffectiveSettingsLayers + resolve_settings
|
||||
│ with LocalOnly/RemoteServer/LocalDaemon modes
|
||||
│ and trust-boundary stripping
|
||||
├── project.rs — workflow discovery + resolve_fabro_root
|
||||
├── user.rs — load_settings_config + legacy file warnings
|
||||
├── run.rs — parse_run_config + resolve_env_refs helper +
|
||||
│ re-export shim of resolved run types
|
||||
├── sandbox.rs, server.rs, — THIN re-export shims. Stage 6 deletes these
|
||||
│ hook.rs, mcp.rs once consumers stop importing through them.
|
||||
├── storage.rs — unrelated; stays
|
||||
├── home.rs — 1-line Home re-export
|
||||
└── legacy_env.rs — 12-line legacy env var helper
|
||||
```
|
||||
|
||||
### Dependency chain to understand
|
||||
|
||||
```
|
||||
TOML file
|
||||
│
|
||||
▼ parse_settings_file() (fabro-types/src/settings/v2/tree.rs)
|
||||
SettingsFile (v2)
|
||||
│
|
||||
▼ combine_files() (fabro-config/src/merge.rs)
|
||||
SettingsFile (v2, merged)
|
||||
│
|
||||
▼ bridge_to_old() (fabro-types/src/settings/v2/bridge.rs)
|
||||
Settings (legacy flat)
|
||||
│
|
||||
▼ every consumer that reads (~84 call sites across 15 files)
|
||||
settings.llm, settings.vars, settings.sandbox, ...
|
||||
```
|
||||
|
||||
The **bridge is the only producer of the legacy flat `Settings` shape**.
|
||||
Removing it requires every reader to consume `SettingsFile` directly.
|
||||
|
||||
## Commit log (Stages 1–5 landed on `main`)
|
||||
|
||||
```
|
||||
c6d515be4 fix(lint): clean up fabro-config test clippy warnings
|
||||
31db613aa docs(config): point new code at ConfigLayer::as_v2 rather than the bridge
|
||||
3dd3c7bf8 refactor(config): delete unused legacy shim modules, document transitional seam
|
||||
dba10e5e9 docs: migrate reference and guide examples to v2 config shape
|
||||
b57248236 test(migration): land final Stage 4 fixes — 100% workspace tests green
|
||||
2fc85282b fix(effective_settings): keep cli/server stanzas from user settings.toml
|
||||
a6047250c fix(lint): clippy cleanup for Stage 3/4 consumer migration
|
||||
f4a79b896 test(cli): migrate remaining config/exec/create fixtures to v2
|
||||
f467bd23c fix(bridge): use hook command shorthand to avoid duplicate serde key
|
||||
eabbca649 feat(tests): migrate fabro-cli fixtures and repo fabro.toml to v2
|
||||
a0eec6aee feat(config): switch parser and layering to v2 schema
|
||||
bb228643e feat(types): flesh out v2 subtrees and add legacy bridge
|
||||
288e73321 feat(types): add settings v2 parse tree scaffolding
|
||||
```
|
||||
|
||||
Total: 76 files changed, +6,413 / -2,151 lines.
|
||||
|
||||
## Stage 6 work breakdown
|
||||
|
||||
Stage 6 has **six independent subtasks**. Each subtask can land as its own PR
|
||||
on top of `main` — they have a natural dependency order but can be paused
|
||||
between steps because the transitional bridge keeps the workspace building at
|
||||
every intermediate state.
|
||||
|
||||
### 6.1 — Migrate consumer read sites from flat `Settings` to v2 `SettingsFile`
|
||||
|
||||
**Scope**: ~84 field-access sites across 15 files (grep below).
|
||||
|
||||
**Files to touch** (ordered easy → hard):
|
||||
|
||||
```
|
||||
lib/crates/fabro-workflow/src/run_options.rs — 5 sites, mostly behind accessor methods
|
||||
lib/crates/fabro-workflow/src/operations/source.rs — 3 sites
|
||||
lib/crates/fabro-workflow/src/operations/create.rs — ~8 sites, touches LLM mutation
|
||||
lib/crates/fabro-workflow/src/operations/start.rs — ~10 sites, touches setup/hooks/llm
|
||||
lib/crates/fabro-cli/src/commands/run/runner.rs — a few sites
|
||||
lib/crates/fabro-cli/src/commands/exec.rs — a few sites
|
||||
lib/crates/fabro-cli/src/manifest_builder.rs — 2 sites (goal, goal_file)
|
||||
lib/crates/fabro-server/src/run_manifest.rs — ~11 sites in handlers + tests
|
||||
lib/crates/fabro-server/src/server.rs — ~14 sites (biggest file)
|
||||
lib/crates/fabro-server/src/web_auth.rs — ~20 sites (git settings heavy)
|
||||
lib/crates/fabro-server/src/serve.rs — a few sites
|
||||
lib/crates/fabro-config/src/effective_settings.rs — apply_server_defaults copies every field
|
||||
lib/crates/fabro-config/src/project.rs — resolve_working_directory reads settings.work_dir
|
||||
lib/crates/fabro-cli/tests/it/cmd/create.rs — 7 sites in assertions
|
||||
lib/crates/fabro-cli/tests/it/cmd/runner.rs — 4 sites in assertions
|
||||
```
|
||||
|
||||
Exact grep:
|
||||
|
||||
```bash
|
||||
grep -rn 'settings\.llm\|settings\.vars\|settings\.sandbox\|settings\.setup\|settings\.hooks\|settings\.checkpoint\|settings\.pull_request\|settings\.mcp_servers\|settings\.artifacts\|settings\.git\|settings\.exec\|settings\.fabro\|settings\.goal\|settings\.work_dir\|settings\.labels\|settings\.github' lib/crates --include='*.rs'
|
||||
```
|
||||
|
||||
**Migration pattern** (before → after):
|
||||
|
||||
```rust
|
||||
// BEFORE (legacy flat)
|
||||
let model = settings.llm.as_ref().and_then(|llm| llm.model.clone());
|
||||
let provider = settings.llm.as_ref().and_then(|llm| llm.provider.clone());
|
||||
```
|
||||
|
||||
```rust
|
||||
// AFTER (v2 via ConfigLayer::as_v2())
|
||||
let model = layer
|
||||
.as_v2()
|
||||
.run
|
||||
.as_ref()
|
||||
.and_then(|r| r.model.as_ref())
|
||||
.and_then(|m| m.name.as_ref())
|
||||
.map(InterpString::as_source);
|
||||
```
|
||||
|
||||
**Recommended sequence**:
|
||||
|
||||
1. **Start with receive-side accessor methods** on `ConfigLayer` and
|
||||
`RunOptions`. For every flat field that consumers read, add an accessor
|
||||
method that walks the v2 tree. Land these additively (no caller changes
|
||||
yet). Example:
|
||||
```rust
|
||||
impl ConfigLayer {
|
||||
pub fn run_model_name(&self) -> Option<String> {
|
||||
self.file.run.as_ref()
|
||||
.and_then(|r| r.model.as_ref())
|
||||
.and_then(|m| m.name.as_ref())
|
||||
.map(InterpString::as_source)
|
||||
}
|
||||
}
|
||||
```
|
||||
2. **Migrate one caller at a time**, file-by-file, smallest first. After each
|
||||
file: `cargo build -p <crate>` + `cargo nextest run -p <crate>` before
|
||||
moving on. Do not try to cover 15 files at once — incremental commits.
|
||||
3. **Delete the flat-field helper methods on `Settings`** as nothing reads
|
||||
them. They are in
|
||||
[`lib/crates/fabro-types/src/settings/mod.rs`](../../lib/crates/fabro-types/src/settings/mod.rs#L111-L196):
|
||||
`app_id()`, `slug()`, `client_id()`, `git_author()`, `sandbox_settings()`,
|
||||
`setup_settings()`, `setup_commands()`, `setup_timeout_ms()`,
|
||||
`preserve_sandbox_enabled()`, `github_permissions()`,
|
||||
`mcp_server_entries()`, `verbose_enabled()`, `prevent_idle_sleep_enabled()`,
|
||||
`upgrade_check_enabled()`, `dry_run_enabled()`, `auto_approve_enabled()`,
|
||||
`no_retro_enabled()`, `storage_dir()`, `slack_settings()`. These will
|
||||
cascade compiler errors into callers that you can then migrate.
|
||||
|
||||
**Gotchas**:
|
||||
|
||||
- **`settings.vars` vs v2 `run.inputs`**: v2 replaces wholesale (R22). If a
|
||||
consumer was relying on `vars` merging across layers, its behavior was
|
||||
ambiguous before and is now explicit — it sees whichever layer set `inputs`
|
||||
last. Check tests after migration.
|
||||
- **`settings.setup.commands` vs v2 `run.prepare.steps`**: v2 replaces the
|
||||
whole ordered list (R30). Several tests were re-asserted in Stage 4;
|
||||
similar audits will be needed for any newly-migrated code path.
|
||||
- **`settings.work_dir`** is the bridge output of `run.working_dir`
|
||||
(`InterpString`). When consumers want the raw string, call
|
||||
`InterpString::as_source()`. When they want an env-resolved value, call
|
||||
`InterpString::resolve(|name| std::env::var(name).ok())` — the v2
|
||||
interpolation pass is not yet wired into the default resolve path.
|
||||
- **`settings.github.permissions`** maps to
|
||||
`server.integrations.github.permissions` in v2, which means it lives in
|
||||
the owner-specific domain and is stripped from fabro.toml / workflow.toml
|
||||
layers per R16. Consumers in `fabro-workflow` that read it will need to
|
||||
either lift the read to a call site that has access to the server-local
|
||||
layer, or accept that workflow-level config cannot ask for GitHub token
|
||||
permissions. Flag this as an open design question if you hit it.
|
||||
|
||||
### 6.2 — Delete the `bridge_to_old` seam
|
||||
|
||||
**Files**:
|
||||
- `lib/crates/fabro-types/src/settings/v2/bridge.rs` (818 LOC) — delete
|
||||
entirely.
|
||||
- `lib/crates/fabro-types/src/settings/v2/mod.rs` — drop the
|
||||
`pub mod bridge;` and `pub use bridge::bridge_to_old;` lines.
|
||||
- `lib/crates/fabro-config/src/config.rs` — delete the
|
||||
`TryFrom<ConfigLayer> for Settings` and `TryFrom<&ConfigLayer> for Settings`
|
||||
impls, the `bridge_to_old` import, and change `ConfigLayer::resolve(self) ->
|
||||
Settings` to `ConfigLayer::into_file(self) -> SettingsFile` (or just
|
||||
encourage `From<ConfigLayer> for SettingsFile` which already exists).
|
||||
|
||||
**Prerequisite**: 6.1 must be complete — there must be zero readers of flat
|
||||
`Settings` left. `git grep 'fabro_types::Settings\b'` should return nothing
|
||||
outside of the legacy type definitions themselves.
|
||||
|
||||
**Known consumer of `bridge_to_old`**: only `ConfigLayer::resolve` in
|
||||
[`lib/crates/fabro-config/src/config.rs`](../../lib/crates/fabro-config/src/config.rs#L133-L140).
|
||||
No external callers. This is the last thing to unwire before the bridge can
|
||||
be deleted.
|
||||
|
||||
### 6.3 — Delete the legacy flat types
|
||||
|
||||
**Files to delete** (and remove from `mod.rs` re-export lists):
|
||||
|
||||
```
|
||||
lib/crates/fabro-types/src/settings/mod.rs — Settings struct, impls, tests
|
||||
lib/crates/fabro-types/src/settings/hook.rs — HookDefinition, HookEvent, HookType, HookSettings, TlsMode
|
||||
lib/crates/fabro-types/src/settings/mcp.rs — McpServerEntry, McpServerSettings, McpTransport
|
||||
lib/crates/fabro-types/src/settings/project.rs — ProjectSettings
|
||||
lib/crates/fabro-types/src/settings/run.rs — LlmSettings, SetupSettings, CheckpointSettings,
|
||||
PullRequestSettings, ArtifactsSettings,
|
||||
GitHubSettings, MergeStrategy
|
||||
lib/crates/fabro-types/src/settings/sandbox.rs — SandboxSettings, DaytonaSettings, DaytonaSnapshotSettings,
|
||||
LocalSandboxSettings, DaytonaNetwork, WorktreeMode,
|
||||
DockerfileSource
|
||||
lib/crates/fabro-types/src/settings/server.rs — ApiSettings, WebSettings, GitSettings, GitAuthorSettings,
|
||||
AuthSettings, AuthProvider, ApiAuthStrategy, TlsSettings,
|
||||
WebhookSettings, WebhookStrategy, GitProvider,
|
||||
FeaturesSettings, LogSettings, SlackSettings,
|
||||
ArtifactStorageSettings, ArtifactStorageBackend
|
||||
lib/crates/fabro-types/src/settings/user.rs — ClientTlsSettings, ExecSettings, OutputFormat,
|
||||
PermissionLevel, ServerSettings
|
||||
lib/crates/fabro-types/src/combine.rs — Combine trait (unused after deletes above)
|
||||
lib/crates/fabro-macros/src/lib.rs — keep `#[derive(Combine)]` if any non-legacy use;
|
||||
otherwise delete the derive macro entry
|
||||
```
|
||||
|
||||
**Prerequisite**: 6.2 must be complete (bridge deleted).
|
||||
|
||||
**Dependency chain**: `Combine` is used _only_ by legacy flat type derives
|
||||
today. Search with
|
||||
```bash
|
||||
grep -rn '#\[derive(.*Combine\|impl Combine\|fabro_types::combine\|fabro_types::Combine' lib/crates --include='*.rs'
|
||||
```
|
||||
If the only hits are inside `fabro-types/src/settings/*.rs` legacy files, the
|
||||
trait + derive are safe to delete in the same PR.
|
||||
|
||||
### 6.4 — Delete the `fabro-config` re-export shims
|
||||
|
||||
**Files** (all are 1–62 LOC thin pass-throughs):
|
||||
|
||||
```
|
||||
lib/crates/fabro-config/src/hook.rs — re-exports fabro_types::settings::hook::*
|
||||
lib/crates/fabro-config/src/mcp.rs — re-exports fabro_types::settings::mcp::*
|
||||
lib/crates/fabro-config/src/sandbox.rs — re-exports fabro_types::settings::sandbox::*
|
||||
lib/crates/fabro-config/src/server.rs — re-exports fabro_types::settings::server::* + resolve_storage_dir()
|
||||
lib/crates/fabro-config/src/user.rs — re-exports fabro_types::settings::user::* + path helpers
|
||||
lib/crates/fabro-config/src/run.rs — re-exports fabro_types::settings::run::* +
|
||||
parse_run_config + resolve_env_refs + resolve_graph_path
|
||||
```
|
||||
|
||||
**Before deleting**, migrate callers off them. The callers are listed in the
|
||||
file-level commit `3dd3c7bf8` — summary: `fabro-hooks`, `fabro-mcp`,
|
||||
`fabro-sandbox`, `fabro-agent`, `fabro-cli`, `fabro-server`,
|
||||
`fabro-workflow`, plus a handful of test files import via
|
||||
`fabro_config::<module>::...` paths. Each should import directly from
|
||||
`fabro_types::settings::v2::...` once the legacy types are gone.
|
||||
|
||||
**Retain**:
|
||||
- `fabro-config/src/run.rs` **`resolve_graph_path()`** — still used, not
|
||||
legacy. Move it to `fabro-config/src/project.rs` or `fabro-config/src/lib.rs`.
|
||||
- `fabro-config/src/run.rs` **`parse_run_config()`** — still used by
|
||||
`fabro-server/src/run_manifest.rs` and `fabro-cli/src/manifest_builder.rs`.
|
||||
It's already a thin `ConfigLayer::parse` wrapper. Either keep it as a
|
||||
top-level function in `fabro-config/src/lib.rs` or inline at call sites.
|
||||
- `fabro-config/src/run.rs` **`resolve_env_refs()`** — the legacy minimal env
|
||||
resolver. Once consumers use `InterpString::resolve` directly, delete.
|
||||
- `fabro-config/src/user.rs` **path helpers** (`default_settings_path`,
|
||||
`default_socket_path`, `active_settings_path`, legacy path helpers,
|
||||
`load_settings_config`) — still used by CLI commands. Move them to
|
||||
`fabro-config/src/lib.rs` or a new `fabro-config/src/paths.rs`.
|
||||
|
||||
### 6.5 — Flatten `settings::v2::*` → `settings::*`
|
||||
|
||||
Once Stages 6.3 + 6.4 are done and `fabro-types/src/settings/` only contains
|
||||
the old `v2/` directory plus a mostly-empty `mod.rs`, rename everything to
|
||||
be the primary namespace:
|
||||
|
||||
```
|
||||
fabro-types/src/settings/
|
||||
├── mod.rs (re-exports direct from subdirs, no more v2 prefix)
|
||||
├── tree.rs
|
||||
├── version.rs
|
||||
├── project.rs
|
||||
├── workflow.rs
|
||||
├── run.rs
|
||||
├── cli.rs
|
||||
├── server.rs
|
||||
├── features.rs
|
||||
├── duration.rs
|
||||
├── size.rs
|
||||
├── model_ref.rs
|
||||
├── interp.rs
|
||||
└── splice_array.rs
|
||||
```
|
||||
|
||||
Rewrite imports across the workspace — `use fabro_types::settings::v2::...`
|
||||
becomes `use fabro_types::settings::...`.
|
||||
|
||||
**Recommendation**: one big mechanical commit with just the rename; do not
|
||||
mix with behavior changes.
|
||||
|
||||
### 6.6 — Rewrite OpenAPI contracts + regenerate clients + fix fabro-web
|
||||
|
||||
This is the piece that was explicitly deferred from Stage 5 because the
|
||||
current bridge-backed `/api/v1/settings` response still works against the
|
||||
existing `ServerSettings` schema. Owning the explicit allow-list DTOs is the
|
||||
end-state the plan calls for (requirements doc "Validation Boundary" +
|
||||
implementation plan Stage 5).
|
||||
|
||||
**Files to rewrite**:
|
||||
|
||||
- `docs/api-reference/fabro-api.yaml` — replace the current flat
|
||||
`ServerSettings` schema (lines ~4238–4364) and `RunSettings` schema
|
||||
(lines ~3995–4032) with explicit allow-list DTOs. The allow-lists are
|
||||
spelled out in the implementation plan under "Rebuild resolution, trust
|
||||
boundaries, and safe serialization":
|
||||
- **`/api/v1/settings` (server scope)**: allow only `server.api.url`,
|
||||
`server.web.enabled`, `server.web.url`, per-provider enabled state for
|
||||
`server.auth.web.providers.*`, and non-secret `server.scheduler` values.
|
||||
Deny everything else — notably `server.listen.*`, `server.listen.tls.*`,
|
||||
`server.auth.api`, `server.integrations.*`, `server.artifacts*`,
|
||||
`server.slatedb*`, any local SecretStore paths, and any env-resolved
|
||||
values tagged via `InterpString` provenance.
|
||||
- **`/api/v1/runs/{id}/settings` (run scope)**: allow the resolved `run.*`
|
||||
tree. Deny: any `InterpString` value whose resolution provenance shows
|
||||
it was sourced from `${env.NAME}`, provider-credential fields under
|
||||
`run.notifications.*.<provider>`, env values under
|
||||
`run.agent.mcps.*.env` that were env-interpolated, and any field
|
||||
explicitly marked sensitive. Deny all `project.*`, `workflow.*`,
|
||||
`cli.*`, and `server.*` — they're not part of a run view.
|
||||
- **Then regenerate**:
|
||||
- Rust progenitor client: `cargo build -p fabro-api` (auto-runs via
|
||||
`build.rs`).
|
||||
- TypeScript client: `cd lib/packages/fabro-api-client && bun run generate`.
|
||||
- **Update fabro-web**:
|
||||
- `apps/fabro-web/app/routes/workflow-detail.tsx` has a static
|
||||
`workflowData` literal (lines 18+) typed as `RunSettings`. Rewrite each
|
||||
entry to match the new run-scope DTO shape. The live `/settings` and
|
||||
`/runs/:id/settings` routes use `JSON.stringify` and are shape-agnostic —
|
||||
they don't need code changes, just the type alignment that falls out of
|
||||
the client regen.
|
||||
- **Update server handlers**:
|
||||
- `lib/crates/fabro-server/src/server.rs` `get_server_settings` (around
|
||||
line 1062) currently serializes the flat Settings into the legacy
|
||||
`ServerSettings` shape via `serde_json::to_value` and `strip_nulls`.
|
||||
Rewrite to build the new allow-list DTO explicitly from
|
||||
`state.settings` — it must _not_ use `serde_json::to_value` on the full
|
||||
Settings, otherwise the allow-list is leaky. There is a redaction
|
||||
helper path in `fabro-types/src/settings/v2/interp.rs`
|
||||
(`Provenance::EnvSourced`) — consult it when you build the run-scope DTO.
|
||||
- `/api/v1/runs/:id/settings` currently returns `not_implemented` in the
|
||||
real (non-demo) router (grep `server.rs:1012`). The run-scope DTO rebuild
|
||||
is the same mechanical shape as the server-scope one, just different
|
||||
fields. The demo router wires `demo::get_run_settings` around
|
||||
`server.rs:934` — don't confuse the two during migration.
|
||||
|
||||
**Provenance redaction helper you'll need**:
|
||||
|
||||
`InterpString::resolve` returns a `Resolved { value, provenance }`. When
|
||||
`provenance == Provenance::EnvSourced`, the caller knows the field came
|
||||
from an env var and must redact it before serializing into the run-scope
|
||||
DTO. If you find yourself building the same `Resolved` → DTO conversion in
|
||||
multiple handlers, pull it into `fabro-types/src/settings/v2/redact.rs` as
|
||||
a new helper module.
|
||||
|
||||
## Verification recipe (run on every incremental step)
|
||||
|
||||
```bash
|
||||
# full gate — must stay green between every sub-step
|
||||
cargo fmt --check --all
|
||||
cargo build --workspace
|
||||
cargo clippy --workspace -- -D warnings
|
||||
ulimit -n 4096 && cargo nextest run --workspace
|
||||
cd apps/fabro-web && bun run typecheck && bun test && cd -
|
||||
|
||||
# sanity: no legacy top-level TOML keys remain in real config files
|
||||
git grep -n '^version = 1' -- docs/ lib/ apps/ fabro/ test/ | \
|
||||
grep -v 'changelog\|_version'
|
||||
|
||||
# sanity: after Stage 6.2 the bridge should have no callers
|
||||
git grep 'bridge_to_old' lib/
|
||||
```
|
||||
|
||||
## Testing gotchas I hit
|
||||
|
||||
These are lessons learned during Stages 1–5. Save yourself the pain.
|
||||
|
||||
1. **`fabro-cli` integration tests use a shared CLI test daemon under
|
||||
parallel nextest load**. Raise the shell FD limit and cap threads:
|
||||
```bash
|
||||
ulimit -n 4096
|
||||
cargo nextest run -p fabro-cli --no-fail-fast --test-threads=4
|
||||
```
|
||||
macOS inherited sessions default to `ulimit -n 256`, which surfaces as
|
||||
misleading EMFILE test timeouts.
|
||||
|
||||
2. **Insta snapshots** — when you update a snapshot, check the pending
|
||||
diffs before bulk-accepting. `cargo insta pending-snapshots` lists
|
||||
what's about to change. `cargo insta accept` accepts everything;
|
||||
`cargo insta accept --snapshot <path>` accepts one at a time. During
|
||||
Stage 4 we chose bulk accept for the run / attach JSON snapshots after
|
||||
confirming the only diffs were `server.target` + `_version` leakage
|
||||
(which we then filtered out explicitly in the per-test filter code).
|
||||
|
||||
3. **Hook shorthand vs `#[serde(flatten)]`** — the legacy
|
||||
`HookDefinition` struct has `command: Option<String>` and
|
||||
`#[serde(flatten)] hook_type: Option<HookType>`, and `HookType::Command`
|
||||
_also_ has a `command: String` field. Setting both
|
||||
`hook_type = Some(HookType::Command { command: ... })` and trying to
|
||||
serialize (or round-trip through YAML) produces a duplicate `command`
|
||||
key and fails deserialization. The bridge emits script/command hooks
|
||||
via the shorthand (`HookDefinition.command`) and leaves
|
||||
`HookDefinition.hook_type` as `None` to work around this. See commit
|
||||
`f467bd23c`.
|
||||
|
||||
4. **`fabro-test` managed settings marker** — the helper writes a
|
||||
`# fabro-test managed storage_dir` comment as the first line of
|
||||
injected settings.toml files. Functions that read the file (like
|
||||
`settings_storage_dir` for `isolated_server`) must detect the marker
|
||||
and treat the managed storage root as _not_ user-explicit, or
|
||||
`isolated_server` will pick up the shared storage dir and the test
|
||||
will fail with `assertion left != right` on the storage dir. See
|
||||
commit `b57248236`.
|
||||
|
||||
5. **`effective_settings::apply_server_defaults`** copies the **full**
|
||||
server-side Settings shape (llm, sandbox, setup, checkpoint,
|
||||
pull_request, artifacts, hooks, mcp_servers, github, slack, fabro)
|
||||
into the resolved CLI settings in RemoteServer / LocalDaemon modes.
|
||||
This is intentional — it matches the pre-Stage-3 behavior and makes
|
||||
`fabro-server::server::tests::start_run_persists_full_settings_snapshot`
|
||||
work. If you refactor the bridge during Stage 6, make sure the
|
||||
equivalent propagation lands in whatever replaces it.
|
||||
|
||||
6. **User layer trust boundary**: `effective_settings` strips `cli` and
|
||||
`server` from the `workflow.toml` and `fabro.toml` layers in
|
||||
RemoteServer / LocalDaemon modes, but **the user layer
|
||||
(`~/.fabro/settings.toml`) is never stripped** — owner-specific
|
||||
domains are only legal there. If you're tempted to strip them
|
||||
uniformly, re-read R16 and commit `2fc85282b`.
|
||||
|
||||
7. **Clippy test warnings**: `cargo clippy --workspace --tests -- -D warnings`
|
||||
has two pre-existing issues in `fabro-interview/src/control.rs`
|
||||
(absolute paths for `tokio::task::yield_now`). They're unrelated to
|
||||
the settings refactor — leave them alone or fix them in a tiny
|
||||
side-quest PR. The workspace-level (non-tests) clippy is already
|
||||
green.
|
||||
|
||||
## Open design questions for you to decide
|
||||
|
||||
1. **Should `ConfigLayer::resolve(self) -> Settings` survive in any form?**
|
||||
The natural rename is `into_file(self) -> SettingsFile`, but many
|
||||
callers genuinely want a "final resolved view" that has applied env
|
||||
interpolation, applied defaults, etc. Decide whether that's an
|
||||
explicit `ResolvedSettings` type (new, v2-shaped) or whether it's
|
||||
just `SettingsFile` with a contract that consumers resolve
|
||||
`InterpString` themselves at read time.
|
||||
|
||||
2. **Post-layering env interpolation resolution pass** — the original
|
||||
plan calls for a pass in `fabro-config/src/interp_pass.rs` that
|
||||
resolves every `InterpString` in the merged `SettingsFile` using
|
||||
provenance tagging. I left this undone because `InterpString::resolve`
|
||||
is adequate for the bridge output. Stage 6 is the right moment to
|
||||
build the proper pass so the DTOs in Stage 6.6 can rely on
|
||||
provenance. Requirements R79–R81 and the "Validation Boundary"
|
||||
section of the requirements doc cover the rules.
|
||||
|
||||
3. **Fail-closed server auth posture** — R52/R53 + "Default server
|
||||
auth posture" in the plan say that if `server.auth` is absent or
|
||||
resolves to no enabled API / web auth strategies, normal server
|
||||
startup must refuse to start, with demo and test helpers free to
|
||||
opt in to insecure startup. I did not wire this into
|
||||
`fabro-server/src/server.rs`. Decide when it should land — doing it
|
||||
in the same PR as Stage 6.6 keeps auth-related changes together.
|
||||
|
||||
4. **`runtime.rs` model-ref ambiguity registry** — `ModelRef::resolve`
|
||||
takes a `&dyn ModelRegistry` and errors on ambiguous bare tokens.
|
||||
There's no runtime implementation of `ModelRegistry` yet. Decide
|
||||
whether to implement it against `fabro-model::Catalog` in Stage 6,
|
||||
or leave model-ref resolution as a consumption-time concern the
|
||||
model selector already handles.
|
||||
|
||||
5. **`run.scm.<provider>` subtree depth** — only `run.scm.github` is
|
||||
defined as a unit struct placeholder right now. Requirements R64 says
|
||||
"provider-specific details live in provider-specific nested tables".
|
||||
When the first real SCM provider leaf lands, add fields under
|
||||
`v2::run::ScmGitHubLayer` and mirror the pattern for future
|
||||
providers.
|
||||
|
||||
6. **`flatten` + `HashMap` + `deny_unknown_fields`** does NOT work
|
||||
together in serde. Every time you think "I can just flatten a
|
||||
HashMap here for provider-specific fields," resist. Use an
|
||||
enumerated list of known-provider subfields instead (that's why
|
||||
`RunSandboxLayer`, `NotificationRouteLayer`, `InterviewsLayer`,
|
||||
`RunScmLayer`, `ServerIntegrationsLayer`, etc. have explicit
|
||||
`github`/`slack`/`local`/`s3` fields). Adding a new
|
||||
provider means adding a new field.
|
||||
|
||||
## Repo conventions you'll hit
|
||||
|
||||
- **Rust import style** (from `CLAUDE.md`): types imported by name,
|
||||
functions via parent module, no glob imports in production code
|
||||
except in test modules. The v2 schema code follows this throughout.
|
||||
- **Shell quoting in sandbox code**: always `shell_quote()` /
|
||||
`shlex::try_quote`. Don't hand-roll `.replace('\'', "'\\''")`.
|
||||
- **Commits**: conventional style. Incremental commits per logical
|
||||
unit. Do not force-push. Do not amend. Stage 1–5 commits are the
|
||||
model.
|
||||
- **Tests**: match existing patterns in each crate. `insta` for
|
||||
snapshots. `e2e_test` attribute for dual-mode tests. Use
|
||||
`fabro_test::test_http_client()` rather than `reqwest::Client::new()`
|
||||
for local HTTP in tests (macOS proxy discovery overhead).
|
||||
|
||||
## Success criteria for Stage 6
|
||||
|
||||
The refactor is **done** when:
|
||||
|
||||
- [ ] `git grep 'fabro_types::Settings\b'` returns zero hits outside of
|
||||
the legacy type file that's about to be deleted.
|
||||
- [ ] `git grep 'bridge_to_old'` returns zero hits.
|
||||
- [ ] `lib/crates/fabro-types/src/settings/v2/` no longer exists as a
|
||||
subdirectory — its contents are promoted to `settings/*`.
|
||||
- [ ] `lib/crates/fabro-types/src/combine.rs` is deleted (the trait
|
||||
only existed to serve legacy flat types).
|
||||
- [ ] `lib/crates/fabro-config/src/{hook,mcp,sandbox,server,run,user}.rs`
|
||||
are either deleted or reduced to a thin `pub use ...::v2::...`
|
||||
re-export shell, depending on your preference for the external
|
||||
surface.
|
||||
- [ ] `docs/api-reference/fabro-api.yaml` `ServerSettings` and
|
||||
`RunSettings` schemas are explicit allow-list DTOs, not reflections
|
||||
of the flat legacy shape.
|
||||
- [ ] `lib/packages/fabro-api-client` and the Rust progenitor client are
|
||||
regenerated from the new spec.
|
||||
- [ ] `apps/fabro-web/app/routes/workflow-detail.tsx` `workflowData`
|
||||
literal matches the new `RunSettings` DTO.
|
||||
- [ ] The `cargo fmt` / `cargo build` / `cargo clippy -D warnings` /
|
||||
`cargo nextest run --workspace` / `bun run typecheck` / `bun test`
|
||||
/ `bun run build` gates all stay green.
|
||||
|
||||
Good luck! The hard cut is behind you — Stage 6 is mechanical from
|
||||
here.
|
||||
|
|
@ -1,439 +0,0 @@
|
|||
---
|
||||
title: "feat: Add IP address allowlist to server"
|
||||
type: feat
|
||||
status: active
|
||||
date: 2026-04-15
|
||||
origin: docs/brainstorms/2026-04-15-ip-whitelist-requirements.md
|
||||
deepened: 2026-04-18
|
||||
---
|
||||
|
||||
# feat: Add IP address allowlist to server
|
||||
|
||||
## Overview
|
||||
|
||||
Add configurable IP address allowlisting to the fabro server so users without network-level controls (VPN, firewall) can restrict access by client IP. The allowlist is configured via `[server.ip_allowlist]` in settings.toml, validated at startup (fail-closed), and enforced as request middleware after tracing but before auth. To preserve TOML compatibility for an upcoming GitHub webhook endpoint, the config shape also reserves an optional GitHub-specific webhook overlay at `[server.integrations.github.webhooks.ip_allowlist]` plus a reserved `github_meta_hooks` entry keyword for GitHub-origin webhook traffic.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Some fabro users deploy on infrastructure without firewalls or VPNs. They need fabro itself to restrict which IP addresses can reach the web UI and API. (see origin: docs/brainstorms/2026-04-15-ip-whitelist-requirements.md)
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Non-allowlisted IPs receive 403 before auth, for all requests (API, web UI, static assets)
|
||||
- R2. No allowlist configured = all IPs allowed (current behavior)
|
||||
- R3. Health check endpoint `/health` is exempt from IP filtering
|
||||
- R4. Support individual IPv4 and IPv6 addresses
|
||||
- R5. Support CIDR notation for ranges
|
||||
- R6. Detect client IP from X-Forwarded-For behind reverse proxies (X-Real-IP is not used — no positional trust model)
|
||||
- R7. Proxy header trust must be explicitly configured; default uses TCP remote address
|
||||
- R8. Configured via settings.toml / environment variables only
|
||||
- R9. No hot-reload; read once at startup
|
||||
- R10. Log rejected requests at warn level with client IP and path
|
||||
- R11. Unix socket + allowlist requires trusted_proxy_count > 0 or server refuses to start
|
||||
- R12. Invalid entries (malformed CIDR) cause startup failure (fail-closed)
|
||||
- R13. The TOML schema must support provider-specific webhook IP allowlist overrides in integration-owned namespaces without breaking existing `[server.ip_allowlist]` configs
|
||||
- R14. Webhook-specific entries may include the reserved keyword `github_meta_hooks`, which resolves to GitHub's current webhook delivery ranges from `GET /meta`
|
||||
- R15. `github_meta_hooks` is only valid in `[server.integrations.github.webhooks.ip_allowlist].entries`; using it outside the GitHub webhook allowlist is a config error
|
||||
- R16. `[server.integrations.github.webhooks.ip_allowlist].trusted_proxy_count` inherits from `[server.ip_allowlist].trusted_proxy_count` unless explicitly overridden
|
||||
- R17. GitHub webhook IP allowlist config falls back to `[server.ip_allowlist]` when the GitHub-specific block or one of its fields is omitted, so webhook routes inherit the server allowlist by default
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No web UI management
|
||||
- No per-user/per-role IP rules
|
||||
- No blocklist (deny-list)
|
||||
- No hot-reload of IP rules
|
||||
- No implicit loopback exemption
|
||||
- This plan does not add the webhook endpoint itself; it only reserves the config and resolution shape needed so GitHub webhook-specific enforcement can be wired later without a TOML break
|
||||
- `/health/diagnostics` is NOT exempt (requires auth, probes server internals)
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- **Config layer/resolved pattern**: `ServerLayer` (sparse, `deny_unknown_fields`) -> `resolve_server()` -> `ServerSettings` (fully populated) in `lib/crates/fabro-types/src/settings/server.rs` and `lib/crates/fabro-config/src/resolve/server.rs`
|
||||
- **Nested integration webhook config already exists**: GitHub webhook delivery strategy already lives under `[server.integrations.github.webhooks]`, so a provider-specific IP allowlist fits the existing integration-owned namespace
|
||||
- **Middleware pattern**: `middleware::from_fn_with_state` used for `cookie_and_demo_middleware` at `lib/crates/fabro-server/src/server.rs:971`
|
||||
- **Router structure**: `/health` registered on outer router (line 948), dispatch service_fn routes to demo/real sub-routers (line 914)
|
||||
- **Serve paths**: Three listener branches in `lib/crates/fabro-server/src/serve.rs:492` — Unix, TCP+TLS, TCP plain. None currently use `ConnectInfo`
|
||||
- **TLS accept loop**: `lib/crates/fabro-server/src/tls.rs:61` captures `remote_addr` but does not inject it into requests
|
||||
- **Auth mode resolution**: `auth_mode` is resolved once at startup (serve.rs:315) and passed to the router, not hot-reloaded — same pattern for IP allowlist
|
||||
- **Test pattern**: `tower::ServiceExt::oneshot()` with `Request::builder()` in server.rs test module (line 6561+)
|
||||
|
||||
### External References
|
||||
|
||||
- `ipnet` crate (v2.11.0 already transitive dep) — `IpNet::contains(&IpAddr)` for CIDR matching
|
||||
- Axum `ConnectInfo<SocketAddr>` via `into_make_service_with_connect_info::<SocketAddr>()`
|
||||
- X-Forwarded-For rightmost-minus-N: the secure approach is to count N trusted proxies from the right of the comma-separated list
|
||||
- GitHub `GET /meta` returns service-specific IP ranges including `hooks`; GitHub recommends querying it directly for current webhook source ranges
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Custom proxy IP extraction over `axum-client-ip`**: The crate's `RightmostXForwardedFor` takes only the single rightmost value, not rightmost-minus-N. Since R7 specifies trusted proxy count support, a simple custom extractor is more appropriate than adding a dependency that doesn't cover the requirement
|
||||
- **No X-Real-IP fallback**: X-Real-IP has no positional trust model — any client can forge it. When `trusted_proxy_count > 0`, only X-Forwarded-For is used for IP extraction. If the header is absent or has too few entries, the request is rejected (fail-closed)
|
||||
- **Fail-closed on short X-Forwarded-For chain**: If `X-Forwarded-For` has fewer entries than `trusted_proxy_count`, the request is rejected (403) rather than falling back to a potentially spoofable entry
|
||||
- **Generic 403 response body**: Use `"Access denied."` (matching existing `ApiError::forbidden()`) rather than a message that reveals the filtering mechanism
|
||||
- **TLS ConnectInfo must use Axum newtype**: The TLS accept loop must inject `axum::extract::ConnectInfo<SocketAddr>` (the wrapper type), not a bare `SocketAddr`, or the middleware extractor will silently fail
|
||||
- **`ipnet` as direct dependency**: Present in Cargo.lock as a transitive dependency (v2.11.0); added as a direct dependency to fabro-types, fabro-config, and fabro-server for CIDR parsing and matching
|
||||
- **`[server.ip_allowlist]` remains the global default scope, and GitHub webhook overrides live under `[server.integrations.github.webhooks.ip_allowlist]`**: This matches the existing integration-owned webhook config shape and avoids inventing a parallel top-level webhook namespace
|
||||
- **The GitHub webhook allowlist is an overlay on the global allowlist, not a separate root policy**: If `[server.integrations.github.webhooks.ip_allowlist]` is absent, GitHub webhook requests use `[server.ip_allowlist]`. If the GitHub block is present but omits `entries` or `trusted_proxy_count`, the omitted field inherits from `[server.ip_allowlist]`
|
||||
- **`entries` resolves to a typed enum, not raw strings**: User-provided strings parse into `IpAllowEntry`, with `Literal(IpNet)` for direct IP/CIDR values and `GitHubMetaHooks` for the reserved keyword `github_meta_hooks`
|
||||
- **`github_meta_hooks` is GitHub-webhook-only**: The reserved keyword is accepted only in `[server.integrations.github.webhooks.ip_allowlist].entries`, where it means "expand to GitHub's current `/meta` `hooks` ranges". Using it elsewhere is invalid config
|
||||
- **GitHub meta expansion should use startup-time fetch plus cache-aware reuse**: Resolve `github_meta_hooks` at startup, using `GET /meta` and the `hooks` array. Reuse cached data on `304 Not Modified`; if GitHub is unavailable and there is no usable cache, fail startup
|
||||
- **Middleware after TraceLayer, before cookie middleware**: Rejected requests still get trace spans (including 403 status), but no cookie/demo processing for blocked IPs
|
||||
- **Health exemption inside middleware**: The middleware checks the request path for `/health` rather than selectively applying to route sets, keeping router structure simple
|
||||
- **IPv4-mapped IPv6 normalization**: Convert `::ffff:x.x.x.x` to IPv4 equivalent before matching, so `10.0.0.0/8` matches regardless of how the OS reports the address
|
||||
- **Land the schema before the webhook route if convenient**: The default-scope middleware can ship first. The GitHub-specific webhook overlay and `github_meta_hooks` resolution model should land now so the later webhook feature can wire into it without a TOML migration
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Which Axum ecosystem tools for IP detection?** Custom implementation. `axum-client-ip` doesn't support trusted-proxy-count. `ConnectInfo<SocketAddr>` for TCP remote address, manual X-Forwarded-For parsing for proxy support
|
||||
- **Config shape?** `[server.ip_allowlist]` is the global default scope. `[server.integrations.github.webhooks.ip_allowlist]` is an optional GitHub-specific overlay, which fits the existing integration-owned webhook namespace and `deny_unknown_fields` constraint
|
||||
- **How should GitHub webhook origins be represented?** As the reserved keyword `github_meta_hooks` inside `[server.integrations.github.webhooks.ip_allowlist].entries`, resolved into concrete IP nets from GitHub `GET /meta`
|
||||
- **Which health endpoints to exempt?** Only `/health`. Not `/health/diagnostics` (requires auth, exposes server internals)
|
||||
- **IPv4-mapped IPv6 handling?** Normalize to IPv4 before matching
|
||||
- **X-Forwarded-For position?** Rightmost-minus-N where N = `trusted_proxy_count`. If N=0, use TCP remote address (ConnectInfo)
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Cross-domain config validation sequencing**: The Unix socket + allowlist check requires both `listen` and `ip_allowlist` to be resolved. Perform this check in `resolve_server()` after both `resolve_listen()` and `resolve_ip_allowlist()` return, not inside the IP allowlist resolver itself
|
||||
- **Whether `ipnet` version needs bumping**: Currently 2.11.0 as transitive; verify `contains()` API availability at implementation time
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
```
|
||||
Representative TOML:
|
||||
|
||||
[server.ip_allowlist]
|
||||
entries = ["10.0.0.0/8"]
|
||||
trusted_proxy_count = 1
|
||||
|
||||
[server.integrations.github]
|
||||
strategy = "app"
|
||||
app_id = "123456"
|
||||
client_id = "Iv1.abc123"
|
||||
slug = "fabro-app"
|
||||
|
||||
[server.integrations.github.webhooks]
|
||||
strategy = "tailscale_funnel"
|
||||
|
||||
[server.integrations.github.webhooks.ip_allowlist]
|
||||
entries = ["github_meta_hooks"]
|
||||
# trusted_proxy_count inherits as 1 unless overridden here
|
||||
|
||||
Request flow with IP allowlist:
|
||||
|
||||
Client -> [TCP/TLS Accept] -> ConnectInfo<SocketAddr> injected
|
||||
-> [TraceLayer] -> trace span created
|
||||
-> [IP Allowlist] -> select active scope
|
||||
- current routes: default `[server.ip_allowlist]`
|
||||
- future GitHub webhook route:
|
||||
`[server.integrations.github.webhooks.ip_allowlist]`
|
||||
overlaid on `[server.ip_allowlist]`
|
||||
if path == "/health": pass through
|
||||
else: extract client IP
|
||||
(ConnectInfo or X-Forwarded-For rightmost-minus-N)
|
||||
normalize IPv4-mapped IPv6
|
||||
check against Vec<IpNet>
|
||||
if miss: warn!(...), return 403
|
||||
-> [Cookie/Demo] -> parse cookies, demo header
|
||||
-> [Router] -> dispatch to demo/real sub-router
|
||||
-> [Auth extractor] -> per-handler auth check
|
||||
|
||||
Startup validation:
|
||||
settings.toml -> parse [server.ip_allowlist]
|
||||
-> parse optional [server.integrations.github.webhooks.ip_allowlist]
|
||||
-> parse each entry string into IpAllowEntry
|
||||
- IP/CIDR -> Literal(IpNet)
|
||||
- `github_meta_hooks` -> GitHubMetaHooks
|
||||
-> reject `github_meta_hooks` outside the GitHub webhook allowlist
|
||||
-> when resolving a GitHub webhook scope containing `GitHubMetaHooks`,
|
||||
call `GET /meta`, read `hooks`, parse into IpNet list
|
||||
-> for GitHub webhook requests, build the effective scope by overlaying
|
||||
`[server.integrations.github.webhooks.ip_allowlist]` on
|
||||
`[server.ip_allowlist]`
|
||||
-> if Unix socket && active scope has entries && trusted_proxy_count == 0:
|
||||
error
|
||||
-> resolve to IpAllowlistConfig (Arc, read-once)
|
||||
-> pass to build_router_with_options
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [ ] **Unit 1: Config types and resolution**
|
||||
|
||||
**Goal:** Define the settings.toml schema for `[server.ip_allowlist]` plus the GitHub webhook overlay, and wire up typed entry parsing/validation.
|
||||
|
||||
**Requirements:** R4, R5, R8, R11, R12, R13, R14, R15, R16, R17
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-types/src/settings/server.rs`
|
||||
- Modify: `lib/crates/fabro-config/src/resolve/server.rs`
|
||||
- Modify: `lib/crates/fabro-config/Cargo.toml` (add `ipnet` direct dependency)
|
||||
- Modify: `lib/crates/fabro-types/Cargo.toml` (add `ipnet` for the resolved type)
|
||||
- Test: `lib/crates/fabro-config/src/resolve/server.rs` (inline tests)
|
||||
|
||||
**Approach:**
|
||||
- Add `ServerIpAllowlistLayer` for the root `[server.ip_allowlist]` table with `entries: Option<Vec<String>>` and `trusted_proxy_count: Option<u32>`. Apply `#[serde(deny_unknown_fields)]`
|
||||
- Add `ServerIpAllowlistOverrideLayer` with the same fields for provider-local webhook overlays
|
||||
- Add `ip_allowlist: Option<ServerIpAllowlistLayer>` to `ServerLayer`
|
||||
- Add `ip_allowlist: Option<ServerIpAllowlistOverrideLayer>` to `IntegrationWebhooksLayer` so GitHub webhook config can live at `[server.integrations.github.webhooks.ip_allowlist]`
|
||||
- Add `IpAllowEntry` enum with `Literal(IpNet)` and `GitHubMetaHooks`
|
||||
- Add `ServerIpAllowlistSettings` with `entries: Vec<IpAllowEntry>` and `trusted_proxy_count: u32` for the global scope
|
||||
- Add `ServerIpAllowlistOverrideSettings` with `entries: Option<Vec<IpAllowEntry>>` and `trusted_proxy_count: Option<u32>` for GitHub webhook overlay settings
|
||||
- Default when absent: empty `entries` vec, `trusted_proxy_count: 0`
|
||||
- Add `resolve_ip_allowlist()` to parse the global scope into `ServerIpAllowlistSettings`
|
||||
- Add `resolve_ip_allowlist_override()` to parse provider-local overlays into `ServerIpAllowlistOverrideSettings`, preserving omitted fields as `None`
|
||||
- Extend `resolve_integrations()` to parse `server.integrations.github.webhooks.ip_allowlist` into the resolved GitHub webhook settings
|
||||
- Reject `github_meta_hooks` outside the GitHub webhook allowlist path
|
||||
- Add `ip_allowlist` field to `ServerSettings`, and extend the resolved integration webhook settings to carry the optional overlay
|
||||
- Perform cross-domain validation in `resolve_server()` after `resolve_listen()`, `resolve_ip_allowlist()`, and `resolve_integrations()` return: compute the effective GitHub webhook scope by overlaying the GitHub webhook config on the global allowlist, then check Unix socket + effective scope with non-empty entries + resolved `trusted_proxy_count == 0` → push error
|
||||
|
||||
**Patterns to follow:**
|
||||
- `ServerAuthLayer` / `ServerAuthSettings` in same file for layer/resolved struct pattern
|
||||
- `IntegrationWebhooksLayer` / `IntegrationWebhooksSettings` in the same file for nested integration-owned config
|
||||
- `resolve_auth()` in `lib/crates/fabro-config/src/resolve/server.rs` for validation with `ResolveError`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: valid IPv4, IPv6, and CIDR entries parse correctly into `IpAllowEntry::Literal`
|
||||
- Happy path: absent `[server.ip_allowlist]` section resolves to empty entries (R2)
|
||||
- Happy path: `trusted_proxy_count` defaults to 0 when not specified
|
||||
- Happy path: `[server.integrations.github.webhooks.ip_allowlist]` resolves as an optional overlay independent from the global scope
|
||||
- Happy path: GitHub webhook entries fall back to the global scope when the GitHub block is absent
|
||||
- Happy path: GitHub webhook entries fall back to the global scope when the GitHub block omits `entries`
|
||||
- Happy path: `server.integrations.github.webhooks.ip_allowlist.trusted_proxy_count` inherits the global value when omitted
|
||||
- Happy path: `server.integrations.github.webhooks.ip_allowlist.trusted_proxy_count` overrides the global value when explicitly set
|
||||
- Happy path: `github_meta_hooks` is accepted in `server.integrations.github.webhooks.ip_allowlist.entries`
|
||||
- Error path: malformed CIDR string (e.g., `10.0.0.0/33`) produces ResolveError
|
||||
- Error path: unparseable address (e.g., `not-an-ip`) produces ResolveError
|
||||
- Error path: `github_meta_hooks` in the default scope produces ResolveError
|
||||
- Error path: `github_meta_hooks` outside the GitHub webhook allowlist path produces ResolveError
|
||||
- Error path: Unix socket listener + non-empty allowlist + `trusted_proxy_count: 0` produces ResolveError
|
||||
- Edge case: empty `entries` list (present but empty) resolves to empty vec (equivalent to no filtering)
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-config` passes
|
||||
- `cargo nextest run -p fabro-types` passes
|
||||
- Invalid config entries cause resolution errors, not panics
|
||||
|
||||
- [ ] **Unit 2: Effective scope resolution, entry expansion, IP matching, and client IP extraction**
|
||||
|
||||
**Goal:** Create the core IP matching logic, effective scope overlay logic, dynamic entry expansion, and client IP extraction (from ConnectInfo or proxy headers).
|
||||
|
||||
**Requirements:** R4, R5, R6, R7, R14, R17
|
||||
|
||||
**Dependencies:** Unit 1 (needs `ServerIpAllowlistSettings`)
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/ip_allowlist.rs`
|
||||
- Modify: `lib/crates/fabro-server/src/lib.rs` (add module declaration)
|
||||
- Modify: `lib/crates/fabro-server/Cargo.toml` (add `ipnet` direct dependency)
|
||||
- Test: `lib/crates/fabro-server/src/ip_allowlist.rs` (inline test module)
|
||||
- Test fixture or mock HTTP support as needed for GitHub `/meta` resolution tests
|
||||
|
||||
**Approach:**
|
||||
- `IpAllowlist` struct wrapping `Vec<IpNet>` with a `contains(&IpAddr) -> bool` method
|
||||
- Add a helper that computes an effective scope from the global allowlist plus an optional provider-specific overlay:
|
||||
- `entries = override.entries.unwrap_or(global.entries.clone())`
|
||||
- `trusted_proxy_count = override.trusted_proxy_count.unwrap_or(global.trusted_proxy_count)`
|
||||
- Add a resolution step that turns the effective scope's `Vec<IpAllowEntry>` into concrete `Vec<IpNet>` for a chosen route:
|
||||
- `Literal(IpNet)` passes through directly
|
||||
- `GitHubMetaHooks` fetches GitHub `GET /meta`, reads the `hooks` array, and parses each item as `IpNet`
|
||||
- Use cache-aware startup fetch for `GitHubMetaHooks`: send `If-None-Match` when cache exists, reuse cached ranges on `304`, and fail startup when the source cannot be resolved and no usable cache exists
|
||||
- Before matching, normalize IPv4-mapped IPv6 (`::ffff:x.x.x.x` → IPv4 equivalent) using `to_canonical()` or manual mapping
|
||||
- `extract_client_ip(req, trusted_proxy_count) -> Option<IpAddr>` function:
|
||||
- If `trusted_proxy_count > 0`: parse `X-Forwarded-For` header, split by comma, take the entry at zero-indexed position `len - 1 - trusted_proxy_count` (skipping N trusted proxy entries from the right to reach the client IP). If `X-Forwarded-For` is absent or has fewer entries than `trusted_proxy_count + 1`, return `None` (fail-closed)
|
||||
- If `trusted_proxy_count == 0`: extract `ConnectInfo<SocketAddr>` from request extensions, return `addr.ip()`
|
||||
- `IpAllowlist::is_empty()` method to efficiently skip checking when no allowlist is configured (R2)
|
||||
- `IpAllowlistConfig` struct containing `IpAllowlist` + `trusted_proxy_count: u32`, constructed from the effective scope for a chosen route. This is the type used as middleware state (`Arc<IpAllowlistConfig>`) in Units 3, 4, and the later GitHub webhook wiring step
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-server/src/jwt_auth.rs` for module structure and inline test organization
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: IPv4 address matches an individual IPv4 entry
|
||||
- Happy path: IPv4 address matches a CIDR range (e.g., `10.1.2.3` matches `10.0.0.0/8`)
|
||||
- Happy path: IPv6 address matches an IPv6 CIDR range
|
||||
- Happy path: effective GitHub webhook scope falls back to global entries when the GitHub overlay is absent
|
||||
- Happy path: effective GitHub webhook scope falls back to global entries when the GitHub overlay omits `entries`
|
||||
- Happy path: effective GitHub webhook scope inherits the global `trusted_proxy_count` when the GitHub overlay omits it
|
||||
- Happy path: effective GitHub webhook scope overrides `trusted_proxy_count` when the GitHub overlay sets it
|
||||
- Happy path: `GitHubMetaHooks` expands to the `hooks` ranges from a mocked `/meta` response
|
||||
- Happy path: cached GitHub metadata is reused on `304 Not Modified`
|
||||
- Happy path: `extract_client_ip` with `trusted_proxy_count: 0` returns ConnectInfo IP
|
||||
- Happy path: `extract_client_ip` with `trusted_proxy_count: 1` and header `client, proxy1` returns `client` (second-from-right, skipping 1 trusted proxy)
|
||||
- Happy path: `extract_client_ip` with `trusted_proxy_count: 2` and header `client, proxy1, proxy2` returns `client` (third-from-right, skipping 2 trusted proxies)
|
||||
- Edge case: IPv4-mapped IPv6 (`::ffff:10.1.2.3`) matches plain IPv4 entry `10.0.0.0/8`
|
||||
- Edge case: X-Forwarded-For with fewer entries than `trusted_proxy_count` — returns None (fail-closed)
|
||||
- Edge case: X-Forwarded-For entries with whitespace around commas are trimmed
|
||||
- Edge case: empty allowlist `is_empty()` returns true
|
||||
- Edge case: single host IP as `/32` CIDR matches exactly
|
||||
- Error path: GitHub `/meta` response contains an invalid range — resolution fails closed
|
||||
- Error path: GitHub `/meta` is unavailable and there is no usable cache — startup fails
|
||||
- Error path: missing ConnectInfo extension when `trusted_proxy_count: 0` — returns None
|
||||
- Error path: malformed IP in X-Forwarded-For — returns None (fail-closed)
|
||||
- Error path: X-Forwarded-For absent when `trusted_proxy_count > 0` — returns None (no X-Real-IP fallback)
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server -- ip_allowlist` passes
|
||||
- All matching and extraction edge cases covered
|
||||
|
||||
- [ ] **Unit 3: IP filter middleware**
|
||||
|
||||
**Goal:** Create the Axum middleware function that enforces the IP allowlist on incoming requests.
|
||||
|
||||
**Requirements:** R1, R2, R3, R10
|
||||
|
||||
**Dependencies:** Unit 2 (needs `IpAllowlist` and `extract_client_ip`)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/ip_allowlist.rs` (add middleware function)
|
||||
- Test: `lib/crates/fabro-server/src/ip_allowlist.rs` (middleware integration tests in inline module)
|
||||
|
||||
**Approach:**
|
||||
- `ip_allowlist_middleware` async function with signature compatible with `middleware::from_fn_with_state`:
|
||||
- State: `Arc<IpAllowlistConfig>` containing the `IpAllowlist` and `trusted_proxy_count`
|
||||
- If allowlist is empty: call `next.run(req).await` immediately (R2 — zero overhead when unconfigured)
|
||||
- If request path is `/health`: pass through regardless (R3)
|
||||
- Extract client IP using `extract_client_ip()`
|
||||
- If IP is in allowlist: pass through
|
||||
- If IP is not in allowlist or extraction failed: `warn!(client_ip = %ip, path = %path, "request rejected: IP not in allowlist")`, return 403 response. Log only the parsed `IpAddr`, not raw header values, to prevent log injection
|
||||
- Return `ApiError::forbidden().into_response()` (generic "Access denied." — does not reveal IP filtering as the mechanism; `.into_response()` needed since `from_fn_with_state` middleware must return `Response`)
|
||||
|
||||
**Patterns to follow:**
|
||||
- `cookie_and_demo_middleware` at `lib/crates/fabro-server/src/server.rs:1994` for `from_fn_with_state` middleware signature and request inspection
|
||||
- Logging strategy: `warn!` with structured fields per `docs-internal/logging-strategy.md`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: request from allowlisted IP passes through to handler
|
||||
- Happy path: request to `/health` from any IP passes through (R3)
|
||||
- Happy path: empty allowlist allows all requests (R2)
|
||||
- Error path: request from non-allowlisted IP returns 403 with appropriate body
|
||||
- Error path: request with no extractable IP (missing ConnectInfo, no proxy headers) returns 403
|
||||
- Integration: middleware runs before auth — a blocked IP never reaches auth extractor
|
||||
- Edge case: request to `/health/diagnostics` from non-whitelisted IP returns 403 (not exempt)
|
||||
- Edge case: request to `/health/` (trailing slash) from non-whitelisted IP returns 403 (not exempt — exact path match only)
|
||||
- Edge case: static asset request from non-whitelisted IP returns 403
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server -- ip_allowlist` passes
|
||||
- Rejected requests logged at warn level with structured fields
|
||||
|
||||
- [ ] **Unit 4: Router and serve integration**
|
||||
|
||||
**Goal:** Wire the default-scope IP allowlist middleware into the router and enable ConnectInfo extraction in all serve paths.
|
||||
|
||||
**Requirements:** R1, R7, R9
|
||||
|
||||
**Dependencies:** Unit 3 (needs middleware function), Unit 1 (needs resolved config)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (add middleware layer in `build_router_with_options`, update `build_router()` convenience wrapper to pass default empty allowlist)
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs` (read allowlist config at startup, pass to router, update TCP serve call to use `into_make_service_with_connect_info`)
|
||||
- Modify: `lib/crates/fabro-server/src/tls.rs` (inject `ConnectInfo<SocketAddr>` into request extensions in TLS accept loop)
|
||||
- Test: `lib/crates/fabro-server/src/server.rs` (integration tests in existing test module)
|
||||
|
||||
**Approach:**
|
||||
- In `serve.rs` `serve_command()`: resolve the default-scope IP allowlist config from `resolved_server_settings` once at startup (like `auth_mode` at line 315). Wrap in `Arc<IpAllowlistConfig>` and pass to `build_router_with_options` as a separate parameter (not in `RouterOptions`, to keep it lightweight and `Copy`-compatible — mirrors how `auth_mode` is passed separately)
|
||||
- In `server.rs` `build_router_with_options()`: apply `middleware::from_fn_with_state(ip_allowlist_config, ip_allowlist_middleware)` as a layer AFTER `trace_layer` but BEFORE `cookie_and_demo_middleware`. Layer ordering (outermost to innermost): TraceLayer → IP allowlist → cookie/demo → router
|
||||
- In `serve.rs` TCP plain path (line 519): change `axum::serve(listener, router)` to `axum::serve(listener, router.into_make_service_with_connect_info::<SocketAddr>())`
|
||||
- In `tls.rs` accept loop (line 78): inject `axum::extract::ConnectInfo<SocketAddr>` (the Axum newtype wrapper, NOT a bare `SocketAddr`) as a request extension before calling the router. If the wrong type is inserted, `extract_client_ip` will silently fail and all requests will be rejected
|
||||
- In `serve.rs` Unix socket path (line 498): no ConnectInfo change needed — the startup validation (Unit 1) ensures `trusted_proxy_count > 0` when using Unix socket with an allowlist, so the middleware will use proxy headers
|
||||
- IP allowlist config is NOT added to `AppState` or `shared_settings` — it is captured by the middleware closure at construction time, ensuring R9 (no hot-reload)
|
||||
- Do not wire `server.integrations.github.webhooks.ip_allowlist` here yet unless the GitHub webhook route already exists in the same change; the root middleware should continue to represent the global default scope for current routes
|
||||
|
||||
**Patterns to follow:**
|
||||
- `auth_mode` resolution at `serve.rs:315` for resolve-once-at-startup pattern
|
||||
- `cookie_and_demo_middleware` layer application at `server.rs:971` for middleware wiring
|
||||
- `auth_mode` parameter passing for how `build_router_with_options` accepts separate config
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: full router with allowlist configured blocks non-allowlisted IP, allows allowlisted IP
|
||||
- Happy path: full router without allowlist configured allows all IPs
|
||||
- Happy path: `/health` accessible from any IP when allowlist is configured
|
||||
- Integration: ConnectInfo extension is available in request when using TCP serve
|
||||
- Integration: IP filtering works with demo mode — blocked IPs cannot access demo routes
|
||||
- Integration: existing tests with non-empty allowlist must inject `ConnectInfo<SocketAddr>` into request extensions via `Request::builder().extension(ConnectInfo(...))`, or fail-closed will reject all requests
|
||||
- Edge case: TLS path injects ConnectInfo correctly so IP filtering works over HTTPS
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes (all existing tests + new integration tests)
|
||||
- `cargo clippy --workspace -- -D warnings` passes
|
||||
- `cargo +nightly fmt --check --all` passes
|
||||
|
||||
- [ ] **Unit 5: Webhook scope wiring**
|
||||
|
||||
**Goal:** When the GitHub webhook endpoint is added, route those requests through the GitHub-specific overlay without changing the TOML schema.
|
||||
|
||||
**Requirements:** R1, R7, R9, R13, R14, R15, R16, R17
|
||||
|
||||
**Dependencies:** Unit 1 (typed config), Unit 2 (dynamic entry resolution), webhook endpoint implementation
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs`
|
||||
- Modify: `lib/crates/fabro-server/src/github_webhooks.rs` and/or webhook handler/router files added by the webhook feature
|
||||
- Test: GitHub webhook integration tests alongside the webhook endpoint
|
||||
|
||||
**Approach:**
|
||||
- Select the active allowlist scope by route:
|
||||
- normal routes use `resolved_server_settings.ip_allowlist`
|
||||
- GitHub webhook routes compute an effective scope by overlaying `resolved_server_settings.integrations.github.webhooks.ip_allowlist` on `resolved_server_settings.ip_allowlist`
|
||||
- Reuse the same middleware and `IpAllowlistConfig` shape; only the chosen scope changes
|
||||
- If the GitHub webhook scope contains `GitHubMetaHooks`, resolve it at startup the same way as any other typed entry before constructing the webhook middleware state
|
||||
- Keep the GitHub webhook route's HMAC verification; IP allowlisting is additive defense, not a replacement
|
||||
|
||||
**Patterns to follow:**
|
||||
- Reuse the default-scope middleware wiring rather than introducing a second bespoke path
|
||||
- Keep route selection explicit near the router definition so reviewers can see which requests use which scope
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: GitHub webhook request uses the global allowlist when `server.integrations.github.webhooks.ip_allowlist` is absent
|
||||
- Happy path: GitHub webhook request uses global entries when the GitHub overlay omits `entries`
|
||||
- Happy path: GitHub webhook request uses the inherited global `trusted_proxy_count` when the GitHub overlay omits it
|
||||
- Happy path: GitHub webhook request uses the overlay `trusted_proxy_count` when explicitly configured
|
||||
- Happy path: `github_meta_hooks` allows a GitHub webhook request from a GitHub hook range
|
||||
- Error path: GitHub webhook request from a non-allowlisted IP returns 403 before webhook auth/HMAC handling
|
||||
- Integration: non-webhook routes continue using the global scope even when GitHub webhook IP allowlist config is present
|
||||
|
||||
**Verification:**
|
||||
- GitHub webhook integration tests pass once the endpoint exists
|
||||
- Existing non-webhook allowlist tests still pass unchanged
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** The default middleware sits between TraceLayer and cookie/demo middleware. It reads `ConnectInfo` extensions (set by `into_make_service_with_connect_info` or manually in TLS path). The GitHub webhook-specific overlay reuses the same machinery once the GitHub webhook route exists
|
||||
- **Error propagation:** 403 responses from the middleware short-circuit the request pipeline. They appear in TraceLayer output as normal 403 responses. The middleware also emits its own `warn!` log
|
||||
- **State lifecycle risks:** None — the allowlist is immutable after startup (Arc, no hot-reload). No shared mutable state
|
||||
- **API surface parity:** The global scope applies uniformly to all current routes (except `/health`). A later GitHub webhook route can opt into the reserved provider-local overlay without changing the global config surface
|
||||
- **Integration coverage:** Key scenario: full request through TCP listener → ConnectInfo injection → IP filter → handler. This must be tested via `oneshot()` with manually injected `ConnectInfo` extensions
|
||||
- **Unchanged invariants:** Auth middleware (extractors), demo mode dispatch, SSE streaming, and existing API routes remain unchanged. The GitHub webhook endpoint is still added separately; this plan only reserves and later wires the scope it will use
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| `into_make_service_with_connect_info` changes the `axum::serve` return type | Straightforward migration; Axum docs show the pattern. Test all serve paths |
|
||||
| TLS path ConnectInfo injection uses wrong type (bare `SocketAddr` instead of `ConnectInfo<SocketAddr>`) | Explicitly documented constraint in Unit 4 approach; dedicated test verifies extraction works through TLS path |
|
||||
| IPv4-mapped IPv6 normalization bugs | Comprehensive test coverage in Unit 2 with explicit mapped-address test cases |
|
||||
| Existing tests may break if they rely on the serve signature | Tests use `oneshot()` against the router, not `axum::serve`, so they are unaffected |
|
||||
| `github_meta_hooks` makes startup depend on an external service | Use GitHub's ETag-capable `/meta` endpoint with cached reuse; fail closed only when the keyword is configured and no usable data can be resolved |
|
||||
| A future GitHub webhook-specific schema could force a TOML migration | Reserve `[server.integrations.github.webhooks.ip_allowlist]` now so the later GitHub webhook feature only consumes existing config rather than renaming it |
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin document:** [docs/brainstorms/2026-04-15-ip-whitelist-requirements.md](docs/brainstorms/2026-04-15-ip-whitelist-requirements.md)
|
||||
- Related code: `lib/crates/fabro-server/src/server.rs` (router, middleware)
|
||||
- Related code: `lib/crates/fabro-server/src/serve.rs` (serve paths)
|
||||
- Related code: `lib/crates/fabro-server/src/tls.rs` (TLS accept loop)
|
||||
- Related code: `lib/crates/fabro-types/src/settings/server.rs` (config types)
|
||||
- Related code: `lib/crates/fabro-config/src/resolve/server.rs` (config resolution)
|
||||
- External: [ipnet crate](https://docs.rs/ipnet/latest/ipnet/) for CIDR matching
|
||||
- External: [Axum ConnectInfo](https://docs.rs/axum/0.8/axum/extract/struct.ConnectInfo.html)
|
||||
- External: [GitHub REST API meta endpoint](https://docs.github.com/en/rest/meta/meta) for `GET /meta` and the `hooks` IP list
|
||||
- External: [GitHub webhook best practices](https://docs.github.com/en/enterprise-cloud@latest/webhooks/using-webhooks/best-practices-for-using-webhooks) for the recommendation to allow GitHub's current webhook IPs
|
||||
|
|
@ -1,359 +0,0 @@
|
|||
# Focused `Blocked` Run Status Plan
|
||||
|
||||
## Summary
|
||||
|
||||
- Add `Blocked` as a first-class run lifecycle status for runs that are waiting on external intervention.
|
||||
- Keep `Paused` separate. `Paused` is operator intent; `Blocked` is an execution condition.
|
||||
- Keep existing engine concepts in scope: `Succeeded` and `Dead` remain real statuses in this pass.
|
||||
- Make `/api/v1/runs`, `/api/v1/runs/{id}`, mutation responses, and `/api/v1/runs/{id}/state` use one truthful operator vocabulary.
|
||||
- Keep `/api/v1/boards/runs` explicitly lossy and web-optimized.
|
||||
- Add `BlockedReason`, starting with `human_input_required`.
|
||||
- Add explicit lifecycle events for `run.runnable`, `run.blocked`, and `run.unblocked`.
|
||||
- No alerting/email work in this pass.
|
||||
|
||||
## Scope And Decisions
|
||||
|
||||
### Canonical Operator Status Vocabulary
|
||||
|
||||
Use one shared run status vocabulary across the durable projection, operator APIs, generated clients, and CLI:
|
||||
|
||||
- `submitted`
|
||||
- `runnable`
|
||||
- `starting`
|
||||
- `running`
|
||||
- `blocked`
|
||||
- `paused`
|
||||
- `removing`
|
||||
- `succeeded`
|
||||
- `failed`
|
||||
- `dead`
|
||||
|
||||
Additional decisions:
|
||||
|
||||
- `cancelled` remains `failed` plus `status_reason=cancelled`; it is not a new top-level run status in this pass.
|
||||
- `status` becomes required/non-null on operator-facing surfaces.
|
||||
- If a run exists but the projection has no lifecycle status yet, synthesize `submitted` rather than returning `null`.
|
||||
- `/api/v1/boards/runs` remains a derived UI projection and does not need to preserve the full operator vocabulary.
|
||||
- This is an accepted breaking contract change. The app is greenfield with no prod installs, so do not add versioning, migration work, serde aliases, or compatibility shims for the status-enum changes or `reason -> status_reason` rename.
|
||||
|
||||
### `Blocked` Semantics
|
||||
|
||||
- `Blocked` means the run cannot proceed until some external condition is resolved.
|
||||
- In this pass the only `BlockedReason` is `human_input_required`, but the enum and event shapes should allow more reasons later.
|
||||
- `blocked_reason` is a separate field everywhere; do not overload `status_reason`.
|
||||
- A paused run may still retain `blocked_reason` if the underlying block is unresolved.
|
||||
- `Paused` wins as the visible status while a run is paused.
|
||||
- If a blocked run is unpaused and the block is still unresolved, the visible state returns to `blocked` (via the `paused -> running -> blocked` event sequence in Section 2).
|
||||
- If the block resolves while the run is paused, clear `blocked_reason` and emit `run.unblocked`, but leave `status=paused`.
|
||||
|
||||
### Board Contract
|
||||
|
||||
`/api/v1/boards/runs` remains a Trello-style projection for the web UI only.
|
||||
|
||||
Board columns after this change:
|
||||
|
||||
- `initializing`
|
||||
- `running`
|
||||
- `blocked`
|
||||
- `succeeded`
|
||||
- `failed`
|
||||
|
||||
Board mapping rules:
|
||||
|
||||
- `submitted`, `runnable`, `starting` -> `initializing`
|
||||
- `running`, `paused` -> `running`
|
||||
- `blocked` -> `blocked`
|
||||
- `succeeded` -> `succeeded`
|
||||
- `failed`, `dead` -> `failed`
|
||||
- `removing` -> off-board
|
||||
|
||||
Additional board decisions:
|
||||
|
||||
- Replace the current `waiting` column with `blocked`.
|
||||
- Replace the older `working | review | merge` board schema entirely. Update OpenAPI `BoardColumn`, server responses, and web `ColumnStatus` types to use only `initializing | running | blocked | succeeded | failed`.
|
||||
- Keep failed behavior as-is.
|
||||
- Keep paused runs visually indistinguishable from running in this pass.
|
||||
- Blocked cards should show the oldest unresolved pending interview question text.
|
||||
- That question text should be derived only in `/api/v1/boards/runs`, not added to `StoreRunSummary`.
|
||||
- Known limitation for this pass: a run that is both paused and still blocked appears in the `running` column. A follow-up can add a paused attention indicator or richer board card state.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
### 1. Shared Types And OpenAPI
|
||||
|
||||
Update the shared contract in:
|
||||
|
||||
- [docs/api-reference/fabro-api.yaml](/Users/bhelmkamp/p/fabro-sh/fabro/docs/api-reference/fabro-api.yaml)
|
||||
- [lib/crates/fabro-types/src/status.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-types/src/status.rs)
|
||||
- [lib/crates/fabro-types/src/run_event/mod.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-types/src/run_event/mod.rs)
|
||||
- generated Rust client/types under `lib/crates/fabro-api`
|
||||
- generated TypeScript models under `lib/packages/fabro-api-client/src/models/`
|
||||
|
||||
Required changes:
|
||||
|
||||
- Collapse OpenAPI `RunStatus` and `InternalRunStatus` into one shared `RunStatus` schema with the canonical operator vocabulary above.
|
||||
- Add `Runnable` and `Blocked` variants to the Rust `RunStatus` enum in `status.rs`. Update `is_active()` to include both (they are incomplete active states). Update `is_terminal()`, `can_transition_to()`, `Display`, and `FromStr` accordingly.
|
||||
- This is an intentional breaking API change: remove public `completed` and `cancelled`, add public `blocked`, `removing`, `succeeded`, and `dead`, and rename `RunStatusRecord.reason` to `status_reason` with no compatibility layer.
|
||||
- Add `BlockedReason` schema with initial value `human_input_required`.
|
||||
- Add `blocked_reason` to:
|
||||
- `RunStatusResponse`
|
||||
- `RunStatusRecord`
|
||||
- `StoreRunSummary`
|
||||
- Rename `RunStatusRecord.reason` to `status_reason` and keep `blocked_reason` separate.
|
||||
- Make `StoreRunSummary.status` a non-null `RunStatus` reference instead of `string | null`.
|
||||
- Keep `status_reason` on responses and summaries.
|
||||
- Expose `pending_interviews` on the `RunProjection` schema for `/api/v1/runs/{id}/state`.
|
||||
- Regenerate Rust and TypeScript API clients after the spec update.
|
||||
|
||||
### 2. Lifecycle Events And Transition Rules
|
||||
|
||||
Add event-backed lifecycle support in:
|
||||
|
||||
- [lib/crates/fabro-workflow/src/event.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-workflow/src/event.rs)
|
||||
- [lib/crates/fabro-types/src/run_event/mod.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-types/src/run_event/mod.rs)
|
||||
- [lib/crates/fabro-workflow/src/handler/human.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-workflow/src/handler/human.rs)
|
||||
- [lib/crates/fabro-workflow/src/operations/start.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-workflow/src/operations/start.rs)
|
||||
- [lib/crates/fabro-workflow/src/run_control.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-workflow/src/run_control.rs)
|
||||
- [lib/crates/fabro-types/src/status.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-types/src/status.rs)
|
||||
|
||||
Add new explicit lifecycle events:
|
||||
|
||||
- `run.runnable`
|
||||
- `run.blocked`
|
||||
- `run.unblocked`
|
||||
|
||||
Payload decisions:
|
||||
|
||||
- `run.blocked` carries `blocked_reason`.
|
||||
- `run.unblocked` is a minimal effect event; it does not repeat `blocked_reason`.
|
||||
- `run.runnable` mirrors existing status-transition event style.
|
||||
|
||||
Event ordering and rules:
|
||||
|
||||
- Emit `run.runnable` from the server `start`/`resume` path at the moment the run is inserted into managed runnable state. Persist it to the durable run event log there; do not synthesize `runnable` later in projection replay.
|
||||
- Emit `run.started` later, when execution begins.
|
||||
- Keep `run.starting` and `run.running` as the worker bootstrap/execution transitions.
|
||||
- `run.blocked` and `run.unblocked` must be durable `run.*` events appended through the normal workflow event sink, not SSE-only notifications and not projection-synthesized state.
|
||||
- Add a run-scoped blocked-state tracker in the workflow runtime, owned by `StartServices`/`RunSession` in `operations/start.rs` and passed into `HumanHandler` through a new `EngineServices` field such as `blocked_state_tracker: Option<Arc<BlockedStateTracker>>`. The tracker should guard unresolved interview count with a mutex so parallel human stages can safely detect `0 -> 1` and `1 -> 0` transitions.
|
||||
- On first pending interview (`0 -> 1` unresolved questions), the workflow runtime emits `interview.started` and then appends `run.blocked`.
|
||||
- While already blocked, additional `interview.started` events do not emit another `run.blocked`.
|
||||
- On final interview resolution (`1 -> 0` unresolved questions), the workflow runtime emits `interview.completed` or `interview.timeout` or `interview.interrupted` and then appends `run.unblocked`.
|
||||
- Do not emit `run.unblocked` when a blocked run reaches `failed`, `succeeded`, or `dead`; terminal events end the blocked condition implicitly.
|
||||
|
||||
Pause/unpause decisions:
|
||||
|
||||
- Keep existing cooperative pause behavior for actively running work.
|
||||
- In this pass, make pause immediate only when the current visible status is `blocked`.
|
||||
- For immediate pause from blocked:
|
||||
- append `run.pause.requested`
|
||||
- append `run.paused` immediately
|
||||
- do not emit `run.unblocked`
|
||||
- this direct server-appended `run.paused` may race with worker-emitted interview resolution and `run.unblocked`; accept that race in this pass and make projection logic order-insensitive so either ordering converges on the same final paused-or-unblocked state
|
||||
- For unpause when the underlying human block is still unresolved:
|
||||
- append `run.unpause.requested`
|
||||
- append `run.unpaused`
|
||||
- append `run.blocked`
|
||||
- this is explicitly `paused -> running -> blocked`; do not add a direct `paused -> blocked` transition
|
||||
- For unpause when the underlying block has already resolved:
|
||||
- append `run.unpause.requested`
|
||||
- append `run.unpaused`
|
||||
- If the blocked condition resolves while paused:
|
||||
- emit the interview resolution event
|
||||
- emit `run.unblocked`
|
||||
- keep `status=paused`
|
||||
|
||||
Transition helper updates in `status.rs`:
|
||||
|
||||
- add `submitted -> runnable`
|
||||
- add `runnable -> starting`
|
||||
- add `running -> blocked`
|
||||
- add `blocked -> running`
|
||||
- add `blocked -> paused` (immediate pause from blocked)
|
||||
- preserve `running -> paused`
|
||||
- preserve `paused -> running`
|
||||
- preserve non-terminal `-> failed` (including from `blocked`)
|
||||
- keep `dead` as a real terminal status in this pass
|
||||
|
||||
### 3. Durable Projection And Truthful Run APIs
|
||||
|
||||
Update durable state and operator-facing API behavior in:
|
||||
|
||||
- [lib/crates/fabro-store/src/run_state.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-store/src/run_state.rs)
|
||||
- [lib/crates/fabro-store/src/types.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-store/src/types.rs)
|
||||
- [lib/crates/fabro-store/src/slate/mod.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-store/src/slate/mod.rs)
|
||||
- [lib/crates/fabro-server/src/server.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/server.rs)
|
||||
- [lib/crates/fabro-server/src/demo/mod.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/demo/mod.rs)
|
||||
|
||||
Projection changes:
|
||||
|
||||
- Extend `RunStatusRecord` and `StoreRunSummary` (Rust: `RunSummary`) with `blocked_reason`.
|
||||
- Store `blocked_reason=human_input_required` while blocked on pending human input.
|
||||
- Preserve `blocked_reason` while the run is paused over an unresolved block.
|
||||
- Clear `blocked_reason` on `run.unblocked`.
|
||||
- Clear pending interviews on terminal completion/failure as today.
|
||||
- Synthesize `submitted` if a run exists but no lifecycle status has been projected yet.
|
||||
|
||||
Operator API changes:
|
||||
|
||||
- `/api/v1/runs` and `/api/v1/runs/{id}` become truthful operator surfaces.
|
||||
- Remove the lossy status remap that currently converts:
|
||||
- `removing -> running`
|
||||
- `succeeded -> completed`
|
||||
- `failed(cancelled) -> cancelled`
|
||||
- `dead -> failed`
|
||||
- Expose the canonical operator vocabulary directly on these endpoints.
|
||||
- Keep `status_reason=cancelled` on failed cancellations.
|
||||
- Include `blocked_reason` alongside `status_reason` and `pending_control`.
|
||||
- Because `ManagedRun.status` uses the generated API `RunStatus`, this enum collapse intentionally requires broad match-arm updates throughout `lib/crates/fabro-server/src/server.rs`, `lib/crates/fabro-server/src/demo/mod.rs`, and generated client consumers.
|
||||
- Return the actual current status from mutation endpoints rather than a target status:
|
||||
- `start` returns `runnable`
|
||||
- `pause` from `blocked` returns `paused`
|
||||
- `unpause` back to unresolved human input returns `blocked`
|
||||
- cooperative `pause` from `running` still returns `running` with `pending_control=pause` until the worker reaches a pause point
|
||||
|
||||
Raw state endpoint changes:
|
||||
|
||||
- `/api/v1/runs/{id}/state` remains the raw projection surface.
|
||||
- Make the schema truthful to the Rust payload by exposing `pending_interviews`.
|
||||
- Use `RunStatusRecord.status_reason` plus `blocked_reason` there too.
|
||||
|
||||
Live managed-run reconciliation:
|
||||
|
||||
- Update `update_live_run_from_event()` in `server.rs` for `run.runnable`, `run.blocked`, and `run.unblocked`.
|
||||
- Keep `Blocked` treated as an incomplete active state for shutdown/startup handling in this pass.
|
||||
- Allow blocked runs to be cancelled through the existing cancel endpoint.
|
||||
- Update `pause_run` to accept `Blocked` in addition to `Running`, implementing the immediate-pause path (appending `run.paused` directly rather than sending a control signal to the worker).
|
||||
- Update `should_reconcile_run_on_startup` to include `Blocked` and `Runnable`.
|
||||
|
||||
### 4. Web Board Projection And UI
|
||||
|
||||
Update the web-only board projection in:
|
||||
|
||||
- [lib/crates/fabro-server/src/server.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-server/src/server.rs)
|
||||
- [apps/fabro-web/app/data/runs.ts](/Users/bhelmkamp/p/fabro-sh/fabro/apps/fabro-web/app/data/runs.ts)
|
||||
- [apps/fabro-web/app/routes/runs.tsx](/Users/bhelmkamp/p/fabro-sh/fabro/apps/fabro-web/app/routes/runs.tsx)
|
||||
- [apps/fabro-web/app/routes/run-detail.tsx](/Users/bhelmkamp/p/fabro-sh/fabro/apps/fabro-web/app/routes/run-detail.tsx)
|
||||
|
||||
Required changes:
|
||||
|
||||
- Replace `waiting` with `blocked` in the board projection and UI types.
|
||||
- Add `runnable` and `blocked` to the `RunStatus` type and `runStatusDisplay` record in `apps/fabro-web/app/data/runs.ts` with appropriate labels and colors.
|
||||
- Update OpenAPI `BoardColumn`, server board responses, and web `ColumnStatus` types to remove `working`, `review`, and `merge`.
|
||||
- Keep board columns `initializing | running | blocked | succeeded | failed`.
|
||||
- Map statuses per the board contract above.
|
||||
- Keep `removing` off-board.
|
||||
- Keep `paused` in the `running` column with no special indicator in this pass.
|
||||
- Keep `dead` in the `failed` column on the board.
|
||||
- Populate board card question text from the oldest unresolved pending interview only in `/api/v1/boards/runs`.
|
||||
- Implement that by having `list_board_runs` open run readers only for summaries whose mapped board column is `blocked`, inspect `RunProjection.pending_interviews`, and choose the oldest question by earliest `started_at`. Keep `StoreRunSummary` unchanged. This may replay or reload projection state per blocked run during board refresh; that performance profile is acceptable in this pass, and implementers should reuse existing `run_store.state()` / projection-cache behavior where available rather than introducing a new caching layer.
|
||||
- Do not add question text to `StoreRunSummary`.
|
||||
|
||||
Board refresh behavior:
|
||||
|
||||
- Preserve the current status-refresh triggers and add the new ones. `STATUS_EVENTS` in `apps/fabro-web/app/routes/runs.tsx` should include:
|
||||
- `run.submitted`
|
||||
- `run.runnable`
|
||||
- `run.starting`
|
||||
- `run.running`
|
||||
- `run.removing`
|
||||
- `run.paused`
|
||||
- `run.unpaused`
|
||||
- `run.blocked`
|
||||
- `run.unblocked`
|
||||
- `run.completed`
|
||||
- `run.failed`
|
||||
- `interview.started`
|
||||
- `interview.completed`
|
||||
- `interview.timeout`
|
||||
- `interview.interrupted`
|
||||
|
||||
Rationale:
|
||||
|
||||
- `run.blocked` and `run.unblocked` cover status changes.
|
||||
- `interview.*` still need to refresh the board because the displayed oldest unresolved question can change while the run remains blocked.
|
||||
|
||||
### 5. CLI Consumers
|
||||
|
||||
Update CLI consumers in:
|
||||
|
||||
- [lib/crates/fabro-cli/src/server_runs.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/server_runs.rs)
|
||||
- [lib/crates/fabro-cli/src/commands/runs/list.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/commands/runs/list.rs)
|
||||
- [lib/crates/fabro-cli/src/commands/run/wait.rs](/Users/bhelmkamp/p/fabro-sh/fabro/lib/crates/fabro-cli/src/commands/run/wait.rs)
|
||||
|
||||
Required changes:
|
||||
|
||||
- Treat `/api/v1/runs` as truthful and stop inventing fallback status in `server_runs.rs`.
|
||||
- Add display/color handling for `Runnable` and `Blocked`.
|
||||
- Keep `Succeeded` as the success exit state for CLI wait behavior in this pass.
|
||||
- Keep `Dead` as a real displayable terminal state when it is actually present.
|
||||
- Stop using `Dead` as a synthetic fallback for missing server summary status now that `status` is non-null.
|
||||
- Continue to show `status_reason=cancelled` for cancellations rather than inventing a `Cancelled` top-level status.
|
||||
|
||||
## Test Plan
|
||||
|
||||
### Shared Types And Event Model
|
||||
|
||||
- `lib/crates/fabro-types/src/run_event/mod.rs`
|
||||
- round-trip serialization for `run.runnable`, `run.blocked`, and `run.unblocked`
|
||||
- `run.blocked` payload includes `blocked_reason`
|
||||
- `lib/crates/fabro-types/src/status.rs`
|
||||
- transition tests for `submitted -> runnable`, `running -> blocked`, and `blocked -> running`
|
||||
- paused overlay path still flows through explicit event order rather than a direct `paused -> blocked` transition
|
||||
- `lib/crates/fabro-workflow/src/handler/human.rs`
|
||||
- first pending interview emits `interview.started` then durable `run.blocked`
|
||||
- second pending interview while already blocked does not emit another `run.blocked`
|
||||
- final resolution emits `interview.completed`/`timeout`/`interrupted` then durable `run.unblocked`
|
||||
- `lib/crates/fabro-workflow/src/operations/start.rs`
|
||||
- run-scoped blocked-state tracker emits exactly one `run.blocked` on `0 -> 1` and exactly one `run.unblocked` on `1 -> 0`, including parallel human-stage races
|
||||
|
||||
### Durable Projection And Server
|
||||
|
||||
- `lib/crates/fabro-store/src/run_state.rs`
|
||||
- `run.runnable` sets `status=Runnable`
|
||||
- `run.blocked` sets `status=Blocked` and `blocked_reason=HumanInputRequired`
|
||||
- `run.unblocked` while status is `Blocked` clears `blocked_reason` and restores `Running`
|
||||
- paused-over-blocked preserves `blocked_reason` while `status=Paused`
|
||||
- unpause-to-still-blocked yields `RunUnpaused` followed by `RunBlocked`
|
||||
- interview resolution while paused clears `blocked_reason` without changing visible `Paused`
|
||||
- missing lifecycle status synthesizes `Submitted`
|
||||
- `lib/crates/fabro-store/src/slate/mod.rs`
|
||||
- list/find summaries expose non-null `status`
|
||||
- summaries expose `blocked_reason`
|
||||
- `lib/crates/fabro-server/src/server.rs`
|
||||
- `/api/v1/runs` and `/api/v1/runs/{id}` expose `blocked`, `removing`, `succeeded`, and `dead` directly
|
||||
- mutation responses return actual current status
|
||||
- blocked runs are cancellable
|
||||
- startup/shutdown handling still treats blocked runs as incomplete active work in this pass
|
||||
- `/api/v1/runs/{id}/state` includes `pending_interviews`
|
||||
- `start`/`resume` append durable `run.runnable` when enqueueing
|
||||
- board response emits `blocked` column, blocked question text, paused-in-running, removing off-board, and dead-in-failed
|
||||
|
||||
### Web UI
|
||||
|
||||
- `apps/fabro-web/app/data/runs.test.ts`
|
||||
- accepts `blocked`, `runnable`, `removing`, `succeeded`, and `dead`
|
||||
- removes dependency on `waiting`
|
||||
- `apps/fabro-web/app/routes/runs.test.tsx`
|
||||
- blocked runs render in the `blocked` lane
|
||||
- paused runs remain in the `running` lane
|
||||
- blocked card shows oldest unresolved question text
|
||||
- `STATUS_EVENTS` retains `run.starting` and `run.running` while adding the new blocked/runnable events
|
||||
- question text refreshes correctly on `interview.*` events without a status change
|
||||
|
||||
### CLI
|
||||
|
||||
- `lib/crates/fabro-cli/src/commands/runs/list.rs`
|
||||
- `Runnable` and `Blocked` render with expected labels/colors
|
||||
- `Dead` remains renderable when actually returned by the API
|
||||
- `lib/crates/fabro-cli/src/commands/run/wait.rs`
|
||||
- `Succeeded` remains the success exit state
|
||||
- `Blocked` is non-terminal and continues waiting
|
||||
- no synthetic `Dead` fallback is used for server summary status
|
||||
|
||||
## Explicit Non-Goals
|
||||
|
||||
- No alerting, email, or notification policy in this pass.
|
||||
- No new paused indicator on the board in this pass.
|
||||
- No broader redesign of cooperative pause for actively running work.
|
||||
- No change to cancellation semantics beyond making blocked runs cancellable and keeping `failed + status_reason=cancelled`.
|
||||
- No attempt to make blocked runs survive restart as a durable parked state in this pass.
|
||||
|
|
@ -1,75 +0,0 @@
|
|||
# Feat: gate GitHub webhook exposure behind explicit strategy
|
||||
|
||||
Today the Rust server silently spawns a separate webhook listener on a random loopback port, shells out to `tailscale funnel`, and mutates the GitHub App's webhook URL whenever `integrations.github.strategy = "app"` and `integrations.github.webhooks` is present. Side effects are host-wide and externally visible. Require explicit opt-in, move the handler onto the main API router at `POST /api/v1/webhooks/github`, and add a `server_url` strategy for operators with a stable public URL.
|
||||
|
||||
## 1. Settings (`fabro-types/src/settings/server.rs`)
|
||||
|
||||
- Extend `WebhookStrategy` enum:
|
||||
- `TailscaleFunnel` (existing, serde `tailscale_funnel`)
|
||||
- `ServerUrl` (new, serde `server_url`)
|
||||
- `IntegrationWebhooksSettings` shape unchanged: `strategy: Option<WebhookStrategy>`.
|
||||
|
||||
## 2. Config resolve (`fabro-config/src/resolve/server.rs`)
|
||||
|
||||
- Thread new variant through layer merge.
|
||||
- Validation: `ServerUrl` requires `server.api.url` to be set. Missing → resolve error at startup.
|
||||
|
||||
## 3. OpenAPI + main router
|
||||
|
||||
- `docs/api-reference/fabro-api.yaml`: add `POST /api/v1/webhooks/github`.
|
||||
- Request body: `application/json`, raw (opaque bytes — verified by HMAC before parse).
|
||||
- Responses: `200` OK, `401` unauthorized.
|
||||
- No auth security scheme (signature-verified).
|
||||
- `cargo build -p fabro-api` regenerates Rust types + client.
|
||||
- `server.rs::build_router_with_options`: mount route outside the auth middleware layer. All `AuthMode` values still serve the endpoint; HMAC is the only gate.
|
||||
- Handler: reject missing/invalid `X-Hub-Signature-256` with 401; on success parse metadata, log event, 200.
|
||||
- Webhook secret plumbed into `AppState` from `server_secrets["GITHUB_APP_WEBHOOK_SECRET"]`. Route is mounted iff secret is present.
|
||||
|
||||
## 4. Rename + slim `github_webhooks.rs`
|
||||
|
||||
- Rename `WebhookManager` → `TailscaleFunnelManager` (single-purpose now).
|
||||
- Delete `spawn_webhook_listener`, `WebhookListener`, standalone router — handler lives on main router.
|
||||
- `TailscaleFunnelManager::start(main_server_port, app_id, private_key_pem)`:
|
||||
- `tailscale funnel <main_server_port>`
|
||||
- Parse funnel URL from `tailscale funnel status`
|
||||
- Best-effort `PATCH https://api.github.com/app/hook/config` with `{funnel_url}/api/v1/webhooks/github`
|
||||
- Log but don't fail on GitHub API errors
|
||||
- `shutdown()`: `tailscale funnel off <port>`.
|
||||
- Keep `verify_signature` and `parse_event_metadata` as `pub(crate)` helpers consumed by the new main-router handler.
|
||||
|
||||
## 5. `serve.rs` gating (`fabro-server/src/serve.rs:373-422`)
|
||||
|
||||
Match on `resolved_server_settings.integrations.github.webhooks.strategy`:
|
||||
|
||||
- `None` → no-op. (Route still mounted if secret present, but no funnel, no GitHub App mutation.)
|
||||
- `Some(TailscaleFunnel)` → `TailscaleFunnelManager::start(main_port, app_id, private_key_pem)`. Keep current best-effort error handling.
|
||||
- `Some(ServerUrl)` → best-effort `update_github_app_webhook({server.api.url}/api/v1/webhooks/github)`. Log failure, don't fail startup. No funnel, no manager.
|
||||
|
||||
Requires wiring the main server's bound port into this block.
|
||||
|
||||
## 6. Tests
|
||||
|
||||
- Router test (new, in `server.rs` or adjacent module):
|
||||
- Valid HMAC → 200
|
||||
- Missing `X-Hub-Signature-256` → 401
|
||||
- Invalid signature → 401
|
||||
- Works regardless of `AuthMode` (bearer header absent, wrong, and correct all behave identically for this route)
|
||||
- Delete `spawn_listener_serves_route` in `github_webhooks.rs` tests.
|
||||
- Settings resolve test: `strategy = "server_url"` without `server.api.url` → error.
|
||||
- Existing OpenAPI conformance test picks up spec addition automatically.
|
||||
|
||||
## 7. Docs
|
||||
|
||||
- `docs/integrations/github.mdx`: document both strategies, side effects (funnel, App URL mutation), recommended choice per environment.
|
||||
- `docs/administration/server-configuration.mdx`: reference `[server.integrations.github.webhooks] strategy` field.
|
||||
- `docs/changelog/2026-04-18.mdx`: **breaking** — funnel no longer auto-enables on App strategy with webhooks config present. Operators must set `strategy = "tailscale_funnel"` explicitly to restore prior behavior. New `server_url` strategy for production deployments with a stable public URL.
|
||||
|
||||
## 8. Migration
|
||||
|
||||
- None automated. Existing users implicitly relying on auto-funnel must add `strategy = "tailscale_funnel"` to `[server.integrations.github.webhooks]`. Call out in changelog.
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
1. Is `AppState` the right home for the webhook secret, or should it be injected into the handler via router state layering?
|
||||
2. Should `ServerUrl`'s GitHub App URL update run on every `serve.rs` start, or only when the current App URL differs? (Rate-limit/noise concern.)
|
||||
3. Where does the webhook route sit relative to `web_enabled` gating — always on, or only when `integrations.github.enabled`?
|
||||
|
|
@ -1,562 +0,0 @@
|
|||
---
|
||||
title: "feat: Add terminal `archived` status to workflow runs"
|
||||
type: feat
|
||||
status: completed
|
||||
date: 2026-04-19
|
||||
origin: docs/brainstorms/2026-04-19-run-archived-status-requirements.md
|
||||
---
|
||||
|
||||
# feat: Add terminal `archived` status to workflow runs
|
||||
|
||||
## Overview
|
||||
|
||||
Adds a new terminal `archived` status to the run lifecycle so users can explicitly mark finished runs "reviewed, no further action needed." Archived runs are hidden from default listings, read-only, and reversible via `unarchive`. The feature surfaces as two new top-level CLI commands (`fabro archive`, `fabro unarchive`), two new server endpoints, and a new `InternalRunStatus` enum variant carried through the event log, projection, and OpenAPI spec.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Terminal runs (`succeeded`, `failed`, `dead`) currently share the same shelf: they all appear with `-a`, clutter listings, and carry no signal about user triage. Users want an explicit action that (a) captures "I've reviewed this" intent, (b) drops the run out of default listings, and (c) leaves all data readable for reference. See origin: `docs/brainstorms/2026-04-19-run-archived-status-requirements.md`.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
Requirements carry forward from the origin requirements document unchanged. Summaries inline for verification convenience:
|
||||
|
||||
**Status & Transitions**
|
||||
- R1. Add `archived` as a new terminal variant of `RunStatus` → Unit 1
|
||||
- R2. Archiving permitted only from terminal statuses → Unit 1, Unit 3
|
||||
- R5. All three source terminal statuses archive identically → Unit 1, Unit 3
|
||||
|
||||
**Events & Projection**
|
||||
- R3. Archiving is reversible; unarchive restores the exact prior terminal status → Unit 2, Unit 3
|
||||
- R4. Prior terminal status retained durably (event payload or projection) → Unit 2
|
||||
- R9. Archive/unarchive appear on the event stream with actor → Unit 2
|
||||
|
||||
**CLI Commands**
|
||||
- R6. `fabro archive <id> [...]` with per-id failure semantics → Unit 6
|
||||
- R7. `fabro unarchive <id> [...]` with same semantics → Unit 6
|
||||
|
||||
**API Surface**
|
||||
- R8. HTTP API exposes archive/unarchive and bulk via CLI fan-out → Unit 5
|
||||
|
||||
**Visibility & Filtering**
|
||||
- R10. `fabro ps` / `runs list` hide archived by default; opt-in flag → Unit 7
|
||||
- R11. JSON listing API exposes equivalent archived-visibility control → Unit 5 (spec + handler), Unit 7 (filter plumbing)
|
||||
- R16. Explicit `status=archived` filter (where it exists) implies opt-in → forward-looking rule; no status filter exists today, deferred
|
||||
|
||||
**Read-Only Enforcement**
|
||||
- R12. Direct run-detail reads by ID still succeed regardless of archived state → Unit 4 (no gate added to read paths)
|
||||
- R13. Archived runs are read-only (read surfaces continue to work) → Unit 4
|
||||
- R14. Any mutation must reject with actionable "unarchive first" error → Unit 4
|
||||
|
||||
**Storage**
|
||||
- R15. No storage / retention / cleanup behavior change → implicit (no storage code is touched by this plan)
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
Carried forward from origin. Two plan-level notes:
|
||||
|
||||
- The web UI at `apps/fabro-web` gets a minimal update: the hand-maintained `RunStatus` union in `app/data/runs.ts` and the `runStatusDisplay` record learn `archived` so the status renders with a label and color. No board-view or list UI *behavior* changes beyond that — filtering, default-hide, and archive/unarchive buttons are deferred to a follow-up UI pass.
|
||||
- The full `InternalRunStatus` / public `RunStatus` enum unification remains deferred as a separate brainstorm. This plan only adds `archived` to both enums where the compile-time exhaustive matches force it; no other structural cleanup is attempted here.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- **Status enum and guard:** `lib/crates/fabro-types/src/status.rs` — `RunStatus` enum, `is_terminal()`, `can_transition_to()`. The one in-tree caller of `is_terminal()` *inside* the status module is the guard itself at `status.rs:36`.
|
||||
- **Internal event type:** `lib/crates/fabro-workflow/src/event.rs` — `Event::RunRemoving` (`event.rs:89-92`) is the closest shape precedent for new status-transition variants. `Event::RunCancelRequested` (`event.rs:93-96`) is the precedent for carrying `Option<ActorRef>` on an event.
|
||||
- **Public event wire type:** `lib/crates/fabro-types/src/run_event/mod.rs` — `EventBody::RunRemoving` at line 97-98; `ActorRef` at lines 37-44.
|
||||
- **Event props:** `lib/crates/fabro-types/src/run_event/run.rs` — `RunStatusTransitionProps { reason: Option<StatusReason> }` at lines 52-56 is the shared shape; `RunRewound` has its own `previous_status: Option<String>` field as a (stringly-typed, don't-repeat) precedent for carrying prior state on an event.
|
||||
- **Projection:** `lib/crates/fabro-store/src/run_state.rs:82-154` — event-body apply loop. Per-run monotonic `event_seq: AtomicU32` in `lib/crates/fabro-store/src/slate/run_store.rs:35`.
|
||||
- **Event-strategy checklist:** `docs-internal/events-strategy.md` — 7-step procedure for adding a new event variant (internal `Event`, `trace()`, `event_name()`, `EventBody`, `event_body_from_event()`, `stored_event_fields()`, consumers).
|
||||
- **Server routes:** `lib/crates/fabro-server/src/server.rs` — `build_router_with_options()` at `server.rs:1080-1155`. `start_run`, `cancel_run`, `pause_run`, `unpause_run` mutation handlers around `server.rs:3963-6150` — each status-gates today but returns a generic 409 on archived; they must switch to an archived-specific actionable error. `append_run_event` at `server.rs:4813-4852` is an event-producing endpoint with no status gate today — it must reject on archived.
|
||||
- **Operations layer:** `lib/crates/fabro-workflow/src/operations/resume.rs:17-22` checks `status == Succeeded`; `operations/rewind.rs` has no status check; `operations/fork.rs` has no status check.
|
||||
- **CLI list:** `lib/crates/fabro-cli/src/commands/runs/list.rs` + `lib/crates/fabro-cli/src/server_runs.rs:146-171` (`filter_server_runs(running_only)` via `run.status().is_active()`). `fabro ps` and any future `fabro runs list` share this one code path — the `#[command(flatten)]` on `RunsCommands` at `args.rs:986-987` collapses them.
|
||||
- **Server-side list filter:** `lib/crates/fabro-workflow/src/run_lookup.rs:261-298` — `filter_runs` with `StatusFilter::{RunningOnly, All}`.
|
||||
- **Bulk-by-ID CLI template:** `lib/crates/fabro-cli/src/commands/runs/rm.rs:26-101` — per-ID error collection, mixed JSON/human output, final `bail!` if any failed. Positional `Vec<String>` for IDs in `args.rs:286-288`. This is the template to mirror for archive/unarchive CLI.
|
||||
- **Top-level CLI shape:** `lib/crates/fabro-cli/src/args.rs:937-945` — `RunsCommands` enum with `Ps`, `Rm`, `Inspect` — flattened to top-level by `#[command(flatten)]` at `args.rs:986-987`. New `Archive`/`Unarchive` variants go here.
|
||||
- **OpenAPI spec:** `docs/api-reference/fabro-api.yaml` — `InternalRunStatus` at lines 2864-2875, `listRuns` operation at lines 121-136 (only pagination params today), `RunControlAction` not used for archive.
|
||||
- **Progenitor regen:** `lib/crates/fabro-api/build.rs:136-172` runs on `cargo build -p fabro-api`.
|
||||
- **TS client regen:** `lib/packages/fabro-api-client/package.json` — `bun run generate` with `@openapitools/openapi-generator-cli`.
|
||||
- **Conformance test:** `cargo nextest run -p fabro-server` catches spec/router drift.
|
||||
|
||||
### Callers of `is_terminal()` — semantic treatment for `Archived`
|
||||
|
||||
| Caller | Location | Treat `Archived` as |
|
||||
|---|---|---|
|
||||
| `can_transition_to` (self-caller) | `lib/crates/fabro-types/src/status.rs:36` | **Special-case** — see Unit 1 |
|
||||
| `wait.rs` poll loop | `lib/crates/fabro-cli/src/commands/run/wait.rs:59, 125-131, 288` | Terminal (stop polling); add `Archived` arm to the post-loop match |
|
||||
| `logs.rs` follow exit | `lib/crates/fabro-cli/src/commands/run/logs.rs:233` | Terminal |
|
||||
| `attach.rs` replay gate + exit code | `lib/crates/fabro-cli/src/commands/run/attach.rs:344-349, 450` | Terminal (replay, not live); `state_exit_code` already prefers the conclusion's `StageStatus`, so archived runs with a conclusion inherit the prior-status exit code naturally |
|
||||
| `run_lookup.rs` end_time | `lib/crates/fabro-workflow/src/run_lookup.rs:238` | Terminal (populate `end_time`) |
|
||||
| Supervisor / shutdown / worker-exit | `lib/crates/fabro-server/src/server.rs:2138, 3170, 3465` | Terminal (don't second-guess); the always-allow `* → Dead` escape hatch remains intact for anomalous cleanup |
|
||||
| `attach_event_is_terminal` | `lib/crates/fabro-server/src/server.rs:1651` | **Leave unchanged** — this matches on `EventBody` not `RunStatus`; archive doesn't end an attach stream |
|
||||
|
||||
No billing / usage / reporting site reads `is_terminal()` — those roll up from the `conclusion` record, not from status.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
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)
|
||||
- `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
|
||||
|
||||
None. All patterns are grounded in the repo.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|---|---|
|
||||
| **Add `archived` to both `InternalRunStatus` and public `RunStatus`** | Forced by the compile-time exhaustive match at `server.rs:3317-3327` (`workflow_status_to_public`) and at `server.rs:2573-2582` (`board_column`). Omitting from the public enum would either (a) break compilation or (b) require downgrading to non-exhaustive matching and losing the compile-time safety net. The public variant carries the same semantic as the internal one. Web UI code still in scope for a tiny follow-on (see Unit 7). |
|
||||
| **Carry `prior_status` on `RunProjection` and `restored_status` on `RunUnarchived` event payload** | Projection gains a single `prior_status: Option<RunStatus>` field. The `RunArchived` apply arm captures `self.status` into `prior_status` before setting status to `Archived`. The unarchive *operation* reads `prior_status` directly from the projection (no event-log scan), emits `RunUnarchived { actor, restored_status = projection.prior_status }`, and the unarchive apply arm reads its own event payload to set status and clear `prior_status`. Events stay self-describing; projection stays pure append-and-apply; no backward scan anywhere. |
|
||||
| **`RunArchived` event carries `actor: Option<ActorRef>`, mirroring `RunCancelRequested`** | Existing actor-carrying precedent. `ActorRef::user(subject.login)` is the same pattern control-requested events use today. |
|
||||
| **Split `is_terminal()` into two concepts: `is_terminal()` (reached terminal outcome) and `is_immutable()` (not transitionable)** | The guard at `status.rs:36` is the only caller that needs "immutable"; every other in-repo caller wants "reached terminal." Splitting gives each caller the semantic it actually wants with no special-casing at the call sites. `can_transition_to` then uses `is_immutable()`, and `Archived` participates in both. |
|
||||
| **Per-ID endpoints (`POST /runs/{id}/archive`, `POST /runs/{id}/unarchive`), CLI fan-out for bulk** | Matches existing `/cancel`, `/pause`, `/unpause` route family. CLI owns the per-id result aggregation (mirroring `rm.rs`). No new response shape in the API surface. |
|
||||
| **Extend `-a/--all` to include archived** (user decision) | Simplest flag story. `-a` becomes "show everything including archived"; default `ps` still shows only active runs; archived are hidden unless `-a`. |
|
||||
| **`listRuns` API gains an `include_archived` query param** | The API surface needs a way to opt in that mirrors the CLI extension. Default is `false` (hide). |
|
||||
| **No-op with success for repeat archive/unarchive in both directions** (user decision) | Archive on already-archived → success, no event. Unarchive on a non-archived terminal → success, no event. Both directions symmetric so bulk retries and mixed-id batches are safe. No event emitted on idempotent calls. |
|
||||
| **Archive allowed only from terminal** | Origin R2. CLI rejects cleanly; no `--force` flag. |
|
||||
| **Unarchive emits `RunUnarchived` with `restored_status`; projection sets status to that value and clears `prior_status`** | Event-sourcing clean: replay reconstructs the prior status from the event payload, projection stays a simple apply-in-order. |
|
||||
| **Inherit authorization from existing `/cancel`, `/pause`, `/unpause` handlers** | New `POST /runs/{id}/archive` and `POST /runs/{id}/unarchive` handlers use the `AuthenticatedService` extractor pattern the existing mutation handlers already use. Actor on the event comes from the request subject via `actor_from_subject` (server.rs:5865-5867). No new authz surface introduced. |
|
||||
| **Preserve the `* → Dead` escape hatch** | Origin R14 note. Supervisor/orphan handling may still mark an archived run `Dead`; that "effectively discards" the archive. |
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Event payload shape for `RunArchived`/`RunUnarchived`** → `RunArchived { actor }`, `RunUnarchived { actor, restored_status }` as new `EventBody` variants (not piggybacking on `RunStatusTransitionProps`, since `restored_status` is specific to unarchive).
|
||||
- **`StatusReason` for archive events** → use `reason: None`. No new `StatusReason::Archived` variant; archive is a user-initiated state change, not a status reason.
|
||||
- **`prior_status` ownership** → lives on `RunProjection` as a new `prior_status: Option<RunStatus>` field; populated by `RunArchived` apply, read by the unarchive *operation* at emit time, cleared by `RunUnarchived` apply.
|
||||
- **Unit 5 handler authz** → inherits the `AuthenticatedService` extractor pattern used by `/cancel`, `/pause`, `/unpause`. Tenant/ownership scope inherits the same boundary.
|
||||
- **`-a/--all` flag shape** → extend `-a` to include archived (user decision).
|
||||
- **API shape** → per-ID endpoints + CLI fan-out.
|
||||
- **Idempotency of repeat calls** → no-op with success.
|
||||
- **UI-centric `RunStatus` enum treatment** → not modified in v1.
|
||||
- **`can_transition_to` refactor direction** → split `is_terminal()` into `is_terminal()` + `is_immutable()`.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Whether `fork` from an archived run is allowed** — not explicitly named in origin R14; `fork` creates a new run, so the archived-source has no lifecycle collision. Default to allowing; Unit 4 should explicitly confirm `fork.rs` does not mutate the parent run (only reads it) before shipping.
|
||||
- **Whether `DELETE /runs/{id}` works on an archived run** — server-side has no status gate today; CLI-side only blocks `is_active()`. Archived runs are not active, so `fabro rm <archived_id>` succeeds naturally. Leave as-is unless a test flags it.
|
||||
- **Whether `POST /runs/{id}/blobs` should reject on archived** — low-risk (content-addressed, append-only). Leave unguarded unless the mutation audit finds a user-facing path through it.
|
||||
- **`StatusFilter` enum shape on the server side** — currently `RunningOnly | All`; whether to add a third variant or extend `All` is a small decision the implementer makes while touching `run_lookup.rs`.
|
||||
- **Color choice for archived in `status_cell()`** — gray (`Color::Ansi256(8)`, matching `Dead`) is the obvious pick; leave final call to the implementer.
|
||||
- **Unification of `InternalRunStatus` and the public `RunStatus` enums (explicitly deferred as a follow-up).** The repo carries two overlapping status enums: the event-sourced engine view (`InternalRunStatus` in OpenAPI / `RunStatus` in `fabro-types`) and the scheduler view (public OpenAPI `RunStatus` / a separate Rust `RunStatus` referenced around `lib/crates/fabro-server/src/server.rs:1233, 2813, 3322-3324, 3980, 4058, 4075, 4106, 4345-4387, 5912-5924`). They map via an explicit translation at `server.rs:3322-3324` (`Succeeded → Completed`, `Failed + reason=Cancelled → Cancelled`). The web UI at `apps/fabro-web/app/data/runs.ts:131-139` redefines the engine enum shape inline rather than consuming the public one — a strong signal the engine view is what actually matters to consumers. Unification would fold the pre-execution `Runnable` and `Cancelled` variants into the engine enum (via a new engine variant and/or a reason-driven display mapping), migrate every `managed_run.status` mutation in `server.rs` (~20 sites), and remove the public OpenAPI `RunStatus` in favor of the unified enum. This is a real, cross-cutting refactor — scoped separately. **Action:** once the archive feature ships, start a dedicated `/ce:brainstorm` for the unification design; do not bundle it into archive.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
Lifecycle transitions introduced by this feature:
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
S[Succeeded] -->|archive| A[Archived]
|
||||
F[Failed] -->|archive| A
|
||||
D[Dead] -->|archive| A
|
||||
A -->|unarchive<br/>restored_status = S| S
|
||||
A -->|unarchive<br/>restored_status = F| F
|
||||
A -->|unarchive<br/>restored_status = D| D
|
||||
A -.->|Dead escape hatch<br/>* → Dead always allowed| D
|
||||
```
|
||||
|
||||
Event flow for a single archive+unarchive cycle (per-run monotonic `event_seq`; projection state shown after each event):
|
||||
|
||||
```text
|
||||
seq=N RunCompleted { reason: ... } → status = Succeeded, prior_status = None
|
||||
seq=N+1 RunArchived { actor: user(login) } → status = Archived, prior_status = Some(Succeeded)
|
||||
seq=N+2 RunUnarchived { → status = Succeeded, prior_status = None
|
||||
actor: user(login),
|
||||
restored_status: Succeeded,
|
||||
}
|
||||
```
|
||||
|
||||
Status enum split:
|
||||
|
||||
```text
|
||||
is_terminal() → { Succeeded, Failed, Dead, Archived } // "reached terminal outcome"
|
||||
is_immutable() → { Succeeded, Failed, Dead } // "can_transition_to blocks outbound (except to Dead)"
|
||||
// Archived is deliberately NOT immutable — can transition to restored_status on unarchive
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
### Unit dependency graph
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U1[Unit 1<br/>Status enum + guard]
|
||||
U2[Unit 2<br/>Events + projection]
|
||||
U3[Unit 3<br/>Archive/unarchive operations]
|
||||
U4[Unit 4<br/>Mutation rejection audit]
|
||||
U5[Unit 5<br/>OpenAPI + server endpoints]
|
||||
U6[Unit 6<br/>CLI commands]
|
||||
U7[Unit 7<br/>Listing visibility]
|
||||
U1 --> U2
|
||||
U2 --> U3
|
||||
U3 --> U4
|
||||
U3 --> U5
|
||||
U4 --> U5
|
||||
U5 --> U6
|
||||
U1 --> U7
|
||||
U6 --> U7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 1: Status enum + transition guard split**
|
||||
|
||||
**Goal:** Add `Archived` to `RunStatus` and split the overloaded `is_terminal()` into `is_terminal()` (reached terminal outcome) + `is_immutable()` (not transitionable). Update `can_transition_to` to allow `Succeeded|Failed|Dead ↔ Archived` while preserving the `* → Dead` escape hatch.
|
||||
|
||||
**Requirements:** R1, R2, R5.
|
||||
|
||||
**Dependencies:** None — foundation.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-types/src/status.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/run_status.rs` (re-exports, verify they cover the new APIs)
|
||||
- Modify: each `is_terminal()` caller per the audit table above — `lib/crates/fabro-cli/src/commands/run/wait.rs`, `logs.rs`, `attach.rs`; `lib/crates/fabro-workflow/src/run_lookup.rs`; `lib/crates/fabro-server/src/server.rs`
|
||||
- Test: `lib/crates/fabro-types/src/status.rs` (unit tests inline or in a sibling test module)
|
||||
|
||||
**Approach:**
|
||||
- Add `RunStatus::Archived` after `Dead`, with snake_case serde and `Display`/`FromStr` arms. Follow the existing import-style convention (types by name).
|
||||
- `is_terminal()` = `matches!(self, Succeeded | Failed | Dead | Archived)`.
|
||||
- Introduce `is_immutable()` = `matches!(self, Succeeded | Failed | Dead)`.
|
||||
- `can_transition_to()`:
|
||||
- Keep the `to == Dead` short-circuit that returns `true` unconditionally.
|
||||
- Gate on `is_immutable()` (not `is_terminal()`) for the "already-terminal outbound block."
|
||||
- Add transitions: `(Succeeded | Failed | Dead) → Archived` and `Archived → (Succeeded | Failed | Dead)`.
|
||||
- Audit every `is_terminal()` caller: all of them want "reached terminal outcome," so they remain calling `is_terminal()` and get `Archived` for free. The only caller that needs to switch to `is_immutable()` is `can_transition_to` itself.
|
||||
- `wait.rs:125-131` has an exhaustive match with `unreachable!()` on non-terminal; add an `Archived` arm that prints an archived status line (or bails cleanly — archiving mid-wait is prevented upstream by R2).
|
||||
- `attach.rs:450` `state_exit_code` already reads from `conclusion` first; verify the archived-fallback path still returns a sensible code (expected: inherits the pre-archive terminal via the conclusion record).
|
||||
|
||||
**Patterns to follow:** Existing enum/trait shape in the same file.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `RunStatus::from_str("archived")` round-trips through `Display`.
|
||||
- Happy path: `Succeeded.can_transition_to(Archived)` is true; `Archived.can_transition_to(Succeeded)` is true; round-trip works for Failed and Dead too.
|
||||
- Happy path: `Running.can_transition_to(Archived)` is false (only terminal → archived).
|
||||
- Happy path: `Archived.can_transition_to(Dead)` is true (escape hatch preserved).
|
||||
- Edge case: `Archived.can_transition_to(Archived)` is false — the idempotent no-op is handled at the operation layer (Unit 3), not the guard.
|
||||
- Edge case: `is_terminal()` returns true for Archived; `is_immutable()` returns false for Archived.
|
||||
- Edge case: `InvalidTransition` error carries both `from` and `to` for a rejected archive transition.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-types` passes.
|
||||
- `cargo nextest run --workspace` still passes (all `is_terminal()` callers still compile and pass under the new semantics).
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` is clean.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 2: Event variants + projection apply arms**
|
||||
|
||||
**Goal:** Add `RunArchived` and `RunUnarchived` as event variants end-to-end — internal `Event`, wire `EventBody`, props, envelope wiring, projection arms — following the 7-step checklist in `docs-internal/events-strategy.md`.
|
||||
|
||||
**Requirements:** R3, R4, R9.
|
||||
|
||||
**Dependencies:** Unit 1.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/event.rs` (internal `Event` variant, `trace()`, `event_name()`, `event_body_from_event()`, `stored_event_fields()`)
|
||||
- Create / modify: `lib/crates/fabro-types/src/run_event/run.rs` — new `RunArchivedProps { actor }` and `RunUnarchivedProps { actor, restored_status }` structs
|
||||
- Modify: `lib/crates/fabro-types/src/run_event/mod.rs` — `EventBody::RunArchived`/`RunUnarchived` variants with `#[serde(rename = "run.archived" / "run.unarchived")]`, and `event_name()` arms
|
||||
- Modify: `lib/crates/fabro-store/src/run_state.rs` — add `prior_status: Option<RunStatus>` field to `RunProjection`; `RunArchived` apply captures `self.status.as_ref().map(|r| r.status)` into `prior_status` then sets `self.status = run_status_record(RunStatus::Archived, None, ts)`; `RunUnarchived` apply sets `self.status = run_status_record(props.restored_status, None, ts)` and clears `self.prior_status = None`
|
||||
- Test: `lib/crates/fabro-store/src/run_state.rs` inline test module (projection apply)
|
||||
- Test: `lib/crates/fabro-workflow/src/event.rs` inline test module (event name + body round-trip)
|
||||
|
||||
**Approach:**
|
||||
- Read `docs-internal/events-strategy.md` first; follow the 7 steps exactly.
|
||||
- `RunArchivedProps` carries `actor: Option<ActorRef>`. `RunUnarchivedProps` carries `actor: Option<ActorRef>` and `restored_status: RunStatus` (typed — do not follow the `RunRewound.previous_status: Option<String>` precedent; stringly-typed is a known anti-pattern here).
|
||||
- Wire event names `"run.archived"` and `"run.unarchived"` (lowercase dot notation per events-strategy.md).
|
||||
- Projection: on `RunArchived`, capture `self.status.as_ref().map(|r| r.status)` into the new `prior_status` field, then set `self.status` to `Archived` with `reason: None`. On `RunUnarchived`, set `self.status` to `props.restored_status` with `reason: None` and `updated_at: ts`, and clear `self.prior_status = None`.
|
||||
- `pending_control` is not modified by either arm — archive is reachable only from terminal, and terminal runs have no pending control by the existing `RunCompleted`/`RunFailed` apply semantics (see `run_state.rs:142-154`). No defensive clearing needed.
|
||||
- Do NOT add these to `attach_event_is_terminal()` at `server.rs:1651` — archive is never a fresh-attach stream endpoint.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `Event::RunCancelRequested` at `lib/crates/fabro-workflow/src/event.rs:93-96` for the actor-carrying event shape.
|
||||
- `Event::RunRemoving` at `lib/crates/fabro-workflow/src/event.rs:89-92` for the status-transition shape.
|
||||
- `EventBody::RunFailed` / `RunCompleted` for per-event typed props structs (not shared).
|
||||
- Projection apply arms at `lib/crates/fabro-store/src/run_state.rs:122-154`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: serializing `EventBody::RunArchived { actor: Some(user("alice")) }` produces JSON with `"event": "run.archived"` and `"properties": { "actor": ... }`.
|
||||
- Happy path: projection replayed over `[RunCreated, RunCompleted, RunArchived]` ends with `status = Archived`.
|
||||
- Happy path: projection replayed over `[RunCreated, RunCompleted, RunArchived, RunUnarchived { restored_status: Succeeded }]` ends with `status = Succeeded`.
|
||||
- Integration: projection replayed over `[... RunCompleted, RunArchived, RunUnarchived(Failed)]` (hypothetical: restored_status differs from the true prior) still applies `restored_status` — enforces that the event payload is authoritative.
|
||||
- Edge case: `event_name()` for both new variants returns the exact dotted strings.
|
||||
- Edge case: `Event::trace()` arms exist for both (required by events-strategy step 2).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-workflow -p fabro-store -p fabro-types` passes.
|
||||
- No existing snapshot test regressed; any that explicitly list event variants have the two new ones appended.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 3: Archive / unarchive workflow operations**
|
||||
|
||||
**Goal:** New workflow-layer functions that validate preconditions, capture prior status, and emit events for archive and unarchive. Centralize the "only-from-terminal" rule and the idempotency behavior (no-op with success) here so both the CLI and server handlers share the logic.
|
||||
|
||||
**Requirements:** R3, R4, R6 (server side of), R7 (server side of).
|
||||
|
||||
**Dependencies:** Units 1, 2.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-workflow/src/operations/archive.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/mod.rs` — re-export
|
||||
- Test: `lib/crates/fabro-workflow/src/operations/archive.rs` inline tests
|
||||
- Test: `lib/crates/fabro-workflow/tests/it/` — scenario coverage
|
||||
|
||||
**Approach:**
|
||||
- Two async functions: `archive(run_id, actor, ...)` and `unarchive(run_id, actor, ...)`.
|
||||
- Both load the current projection. Error handling:
|
||||
- `archive` on an active (non-terminal, non-archived) status → `Error::Precondition` with an actionable message ("must be terminal").
|
||||
- `archive` on already-archived → return `Ok(idempotent)` without emitting an event.
|
||||
- `unarchive` on a non-archived terminal status → return `Ok(idempotent)` without emitting an event (symmetric with archive idempotency).
|
||||
- `unarchive` on an active status → `Error::Precondition` ("run is not archived").
|
||||
- `unarchive` on archived → read `projection.prior_status` (populated by the `RunArchived` apply arm — no backward event scan), emit `RunUnarchived { actor, restored_status: prior_status }`. If `prior_status` is unexpectedly `None` (should not happen for an archived run), fail loudly with an invariant-violated error.
|
||||
- Emit events through `Emitter::emit()` (never direct-write). The emitter handles `RunEvent` construction exactly once per events-strategy.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `operations/resume.rs:17-22` for the shape of a status-checking operation that emits events.
|
||||
- `server.rs:5850-5867` for how control-requested events capture `actor` via `actor_from_subject`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `archive(succeeded_run)` emits `RunArchived` and projection shows `Archived`.
|
||||
- Happy path: `unarchive(archived_run)` emits `RunUnarchived { restored_status: Succeeded }` and projection shows `Succeeded`.
|
||||
- Happy path: `archive(failed_run)` then `unarchive` → projection returns to `Failed`.
|
||||
- Happy path: `archive(dead_run)` then `unarchive` → projection returns to `Dead`.
|
||||
- Edge case: `archive(already_archived_run)` returns Ok with no event emitted (idempotent); sequence count unchanged.
|
||||
- Edge case: `unarchive(already_succeeded_run)` (not archived, but terminal) returns Ok with no event emitted (idempotent).
|
||||
- Edge case: `unarchive(running_run)` (active) returns a precondition error ("run is not archived").
|
||||
- Error path: `archive(running_run)` returns a precondition error mentioning "must be terminal".
|
||||
- Integration: `archive` then `unarchive` then `archive` again → three events in the log (since the middle unarchive reopened the run), projection shows `Archived` at end.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-workflow` passes.
|
||||
- An integration test demonstrates the full archive/unarchive cycle through the event store, not just the logic layer.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 4: Mutation rejection for archived runs (R14 audit)**
|
||||
|
||||
**Goal:** Teach every run-mutation entry point to reject operations on archived runs with an actionable "unarchive first" error, preserving the `* → Dead` escape hatch.
|
||||
|
||||
**Requirements:** R12, R13, R14.
|
||||
|
||||
**Dependencies:** Units 1, 2, 3.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/resume.rs` — add `Archived` rejection
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/rewind.rs` — add status check that rejects archived (no status check today)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` — `start_run`, `cancel_run`, `pause_run`, `unpause_run` handlers (~lines 3963-6150) switch from generic 409 to archived-specific actionable message when the current status is `Archived`
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` — `append_run_event` handler (~line 4813) add an archived guard (currently ungated, bypasses `can_transition_to`)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` — `submit_answer` handler (~line 4769) defensively rejects archived
|
||||
- Test: `lib/crates/fabro-server/tests/it/` — conformance and negative-path tests
|
||||
- Test: `lib/crates/fabro-workflow/tests/it/` — resume/rewind rejection tests
|
||||
|
||||
**Approach:**
|
||||
- Define a single canonical error message string such as: ``run <id> is archived; run `fabro unarchive <id>` to restore it and try again``. Reuse across handlers.
|
||||
- In each handler, check `status == Archived` before the existing status-class check so the archived-specific message wins.
|
||||
- Do NOT reject in `attach_event_is_terminal()` (`server.rs:1651`) — that matches on `EventBody`, not status, and archive is never a fresh-attach endpoint.
|
||||
- Leave `DELETE /runs/{id}` unguarded — archived runs being delete-able preserves the orthogonality of archive-and-delete (origin Scope Boundaries).
|
||||
- Leave `POST /runs/{id}/blobs` unguarded for v1 — low-risk append-only path; revisit if the test suite surfaces a problem.
|
||||
- Do NOT add any status check to supervisor paths (`server.rs:2138, 3170, 3465`) — those already skip terminal runs and archived is terminal under the new `is_terminal()` semantics.
|
||||
- `append_run_event` (`server.rs:4813-4852`) gets an archived guard as listed in Files. In the same touch, confirm that the endpoint already rejects client-supplied lifecycle-transition `EventBody` variants (or add that rejection) — clients must not be able to inject `RunArchived`/`RunUnarchived`/`RunCompleted`/`RunFailed` directly and skip the operations-layer authorization + precondition checks. This is a pre-existing concern the plan inherits by touching this handler.
|
||||
- `fork` reads from the source run but must not mutate it; confirm by grepping `operations/fork.rs` for writes targeting the source `run_id` before Unit 4 closes. If fork mutates the source (e.g. to record a child link), add the archived guard.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `resume.rs:17-22` for the status-gate shape.
|
||||
- `server.rs` 409 response pattern in `cancel_run` et al. for the handler-level rejection.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: none — this unit is purely negative-path.
|
||||
- Error path: `resume(archived_run)` → precondition error with "unarchive first" phrasing.
|
||||
- Error path: `rewind(archived_run)` → precondition error.
|
||||
- Error path: `POST /runs/{id}/cancel` with archived status → 409 with archived-specific body.
|
||||
- Error path: `POST /runs/{id}/pause` with archived status → 409 with archived-specific body.
|
||||
- Error path: `POST /runs/{id}/unpause` with archived status → 409 with archived-specific body.
|
||||
- Error path: `POST /runs/{id}/start` with archived status (e.g. resume-via-start) → 409 with archived-specific body.
|
||||
- Error path: `POST /runs/{id}/events` (append_run_event) with archived status → 409 or 400 (pick consistent code with the rest of the archived-rejection family).
|
||||
- Integration: `POST /runs/{id}/unarchive` followed by a resume succeeds (rejection unblocks cleanly on unarchive).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server -p fabro-workflow` passes.
|
||||
- A scenario test demonstrates: archive → each mutation returns the actionable error → unarchive → same mutation now works.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 5: OpenAPI spec + server endpoints**
|
||||
|
||||
**Goal:** Add archive/unarchive endpoints and `include_archived` listing param to the OpenAPI spec, add `archived` to `InternalRunStatus`, then implement server handlers and verify progenitor/TS client regeneration.
|
||||
|
||||
**Requirements:** R8, R10, R11, R16 (partial — server side of visibility).
|
||||
|
||||
**Dependencies:** Units 3, 4.
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/api-reference/fabro-api.yaml` — add `archived` to `InternalRunStatus` enum (lines 2864-2875) **and** to public `RunStatus` enum (lines 2097-2108); add `POST /api/v1/runs/{id}/archive` and `POST /api/v1/runs/{id}/unarchive` operations; add `include_archived: boolean` query parameter to `listRuns` (lines 121-136).
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` — `build_router_with_options()` gets two new routes; new handler functions `archive_run`, `unarchive_run` that use the same `AuthenticatedService` extractor as `/cancel`/`/pause`/`/unpause` and call `operations::archive::archive` / `unarchive`; add `Archived` arms to the exhaustive matches in `workflow_status_to_public` (~line 3317) and `board_column` (~line 2573); extend `list_runs` handler (~line 2744) to accept `include_archived` and apply the filter at the handler layer (it queries `state.store.list_runs` directly — it does NOT go through `run_lookup::filter_runs`).
|
||||
- Test: `lib/crates/fabro-server/tests/` — conformance test automatically picks up the new routes; add handler-level happy-path + error-path tests including authz parity with `/cancel`.
|
||||
|
||||
**Approach:**
|
||||
- Edit the OpenAPI spec first; `cargo build -p fabro-api` regenerates the Rust types.
|
||||
- Response shape for archive/unarchive: reuse the existing `RunStatusResponse` shape (or whatever `/cancel` returns today) — archive/unarchive end in a clean status transition, so status-after-operation is the natural response.
|
||||
- Handler error mapping: `Error::Precondition` → 409 with JSON body carrying the message; idempotent success on already-archived/already-not-archived → 200 with current status.
|
||||
- `listRuns` default `include_archived = false`. The filter applies in the `list_runs` handler directly — this surface calls `state.store.list_runs(&ListRunsQuery::default())` and does not pass through `run_lookup::filter_runs` (which is only called from the prune path). Either filter the returned slice at the handler, or extend `ListRunsQuery` with an `include_archived: bool`, and push the predicate into `slate::catalog::list_run_ids`.
|
||||
- Add `Archived` arms to two exhaustive matches on engine `WorkflowRunStatus` in `server.rs`: (1) `workflow_status_to_public` at ~line 3317-3327 maps to the new public `RunStatus::Archived` variant; (2) `board_column` at ~line 2573-2582 maps to `None` (archived runs don't appear in a board column) or `Some("archived")` — picker's call.
|
||||
- Authz: `archive_run`/`unarchive_run` handlers use `AuthenticatedService` extractor and `actor_from_subject(subject)` to populate the event's `actor`, mirroring `cancel_run` (`server.rs:5883-6005`). No new scope/tenant logic.
|
||||
- `include_archived=true` is strictly additive within the already-authorized result set (does not alter tenant/ownership scope).
|
||||
- After the spec edit, run `cd lib/packages/fabro-api-client && bun run generate` to regenerate TS client. Commit generated files.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `POST /runs/{id}/cancel` route declaration and handler as the precedent for the archive/unarchive endpoints.
|
||||
- `prune_runs` request/response shape at `/system/prune/runs` as a precedent for a filtered listing response (though we don't copy the filter body shape — we just add a query param).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `POST /runs/{id}/archive` on a succeeded run returns 200 and subsequent `GET /runs/{id}` shows `status: archived`.
|
||||
- Happy path: `POST /runs/{id}/unarchive` on an archived run returns 200 and `GET /runs/{id}` shows the prior terminal status.
|
||||
- Happy path: `GET /runs` default hides archived; `GET /runs?include_archived=true` includes them.
|
||||
- Edge case: `POST /runs/{id}/archive` on already-archived run returns 200 (idempotent).
|
||||
- Edge case: `POST /runs/{id}/unarchive` on a non-archived terminal run returns 200 (idempotent — symmetric with archive).
|
||||
- Edge case: `POST /runs/{id}/unarchive` on an active run returns 409 with actionable "run is not archived" message.
|
||||
- Error path: `POST /runs/{id}/archive` on an active (running) run returns 409.
|
||||
- Error path: `POST /runs/{unknown_id}/archive` returns 404.
|
||||
- Conformance: the server's spec/router conformance test (`cargo nextest run -p fabro-server`) passes after the spec edit.
|
||||
- Integration: the full lifecycle `create → run → complete → archive → list (hidden) → list --include-archived (shown) → unarchive → resume (rejected? — no, resume only works on Succeeded; see Unit 4 test)`.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-api` regenerates without progenitor errors.
|
||||
- `cd lib/packages/fabro-api-client && bun run generate && bun run typecheck` passes.
|
||||
- `cargo nextest run -p fabro-server` (the conformance test is the authoritative spec/router consistency check).
|
||||
- `curl -X POST .../runs/{id}/archive` returns the expected shape against a running server.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 6: CLI commands — `fabro archive` and `fabro unarchive`**
|
||||
|
||||
**Goal:** Two new top-level CLI commands via `RunsCommands` with bulk-by-ID positional args and per-ID failure aggregation that mirrors `fabro rm`. Colors and status display learn `Archived`.
|
||||
|
||||
**Requirements:** R6, R7.
|
||||
|
||||
**Dependencies:** Unit 5.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs` — add `Archive(RunsArchiveArgs)` and `Unarchive(RunsUnarchiveArgs)` variants to `RunsCommands` (around line 937-945); add the corresponding arg structs mirroring `RunsRemoveArgs` (~line 281-293); add `.name()` arms (~line 947-955) returning `"archive"` and `"unarchive"`
|
||||
- Create: `lib/crates/fabro-cli/src/commands/runs/archive.rs`
|
||||
- Create: `lib/crates/fabro-cli/src/commands/runs/unarchive.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/mod.rs` — dispatch arms for the two new subcommands
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/archive.rs` (new)
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/unarchive.rs` (new)
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/archive.rs` (new) — full lifecycle scenario
|
||||
|
||||
**Approach:**
|
||||
- CLI layer has no server-side logic — just the progenitor-generated `server.api().archive_run(id).send().await` calls (method names depend on OpenAPI regen).
|
||||
- Copy `rm.rs:26-101` as the template: loop over `args.runs`, call the per-ID endpoint, collect `(run_id, Result)` pairs, print per-ID success/failure, emit structured JSON output when the CLI format is JSON, and `bail!("some runs could not be <archived|unarchived>")` at the end if any failed.
|
||||
- Help text: `"Mark a terminal run as archived (reviewed, no further action needed). Archived runs are hidden from default listings."`. For unarchive: `"Restore an archived run to its prior terminal status."`.
|
||||
- No `--force` flag. No `--confirm`. Bulk is safe because archive is reversible.
|
||||
- Telemetry names (`"archive"`, `"unarchive"`) added to `RunsCommands::name()`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/runs/rm.rs` for bulk-by-ID shape, per-ID output, JSON formatting, final-error semantics.
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/rm.rs` for test shape (help snapshot, success/fail cases).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `fabro archive <succeeded_id>` prints success line; follow-up `fabro ps` no longer shows the run; `fabro ps -a` shows it with status `archived` (gray).
|
||||
- Happy path: `fabro unarchive <archived_id>` prints success line; follow-up `fabro ps -a` shows it with the prior terminal status.
|
||||
- Happy path: `fabro archive <id_a> <id_b> <id_c>` archives all three; per-ID success lines.
|
||||
- Edge case: `fabro archive <terminal_id> <already_archived_id>` — both "succeed" (second is a no-op).
|
||||
- Edge case: `fabro unarchive <archived_id> <succeeded_id>` — first succeeds, second fails with "not archived"; final exit is non-zero; JSON mode has `errors: [{ identifier, error }]` populated.
|
||||
- Edge case: `fabro unarchive <already_succeeded_id>` — succeeds idempotently (no-op, no event).
|
||||
- Error path: `fabro archive <running_id>` — fails with "must be terminal"; exit non-zero.
|
||||
- Error path: `fabro unarchive <running_id>` — fails with "run is not archived" (active runs can't be unarchived since they aren't terminal); exit non-zero.
|
||||
- Error path: `fabro archive <unknown_id>` — 404 rendered as a clear error.
|
||||
- Error path: `fabro archive` with no IDs — clap rejects (required positional).
|
||||
- Help snapshot: `fabro archive --help` snapshot test.
|
||||
- Help snapshot: `fabro unarchive --help` snapshot test.
|
||||
- Integration (scenario): full lifecycle across multiple commands — see `tests/it/scenario/archive.rs`.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` passes (including new snapshots after `cargo insta accept --snapshot <new>`).
|
||||
- Manual smoke: `fabro archive <id>` / `fabro ps` / `fabro ps -a` / `fabro unarchive <id>` against a local server.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 7: Listing visibility — `-a` extension, display, server-side filter plumbing**
|
||||
|
||||
**Goal:** Extend `-a/--all` to include archived, teach `filter_server_runs` and the server-side `filter_runs` about archived, update the empty-list hint, and ensure the `listRuns` API opt-in works end-to-end.
|
||||
|
||||
**Requirements:** R10, R11, R16.
|
||||
|
||||
**Dependencies:** Units 1, 6.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/server_runs.rs:146-171` — `filter_server_runs` predicate drops archived unless `show_archived` is set; plumb the new flag through from `list_command`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/list.rs` — read `args.all` as the "show archived" signal (since `-a` is the chosen extension); update the empty-list hint at lines 68-78 to reflect the new meaning of `-a`; add an `Archived` arm to `status_cell()` at lines 146-159 (gray, `Color::Ansi256(8)`)
|
||||
- Modify: `apps/fabro-web/app/data/runs.ts:131-150` — add `"archived"` to the inline `RunStatus` string-literal union and add a `runStatusDisplay["archived"]` entry with an appropriate label/dot/text triple (gray family). The web UI type is hand-maintained and parallel to the generated TS client; without this update, archived runs render with no label
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/ps.rs` updates — existing tests verify new flag semantics
|
||||
- Test: `lib/crates/fabro-server/tests/it/` — listing tests cover both `include_archived` values on the API side (the actual API handler change lives in Unit 5)
|
||||
- Test: `apps/fabro-web/` — if there's a `runs.ts` test, ensure `isRunStatus("archived")` returns true
|
||||
|
||||
**Approach:**
|
||||
- Default `fabro ps` (no `-a`): only active runs (unchanged from today).
|
||||
- `fabro ps -a`: active + terminal + archived (the one visible behavior change for existing scripted users — document in the help text).
|
||||
- Empty-list hint rewording: today's text is `"No running processes found. Use -a to show all runs."` — no change needed if we keep `-a` as "show all including archived."
|
||||
- Server-side `filter_runs` is called from multiple surfaces (list, prune). Archive-exclusion rule only applies to `listRuns`; `prune` works on terminal runs and archived are terminal, so pruning an archived run is fine under existing semantics — but validate during implementation that prune doesn't surprise users.
|
||||
- The `include_archived` query param on `listRuns` is already added in Unit 5; this unit just wires it through the filter layer on both sides.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `RunFilterArgs.orphans` composition at `lib/crates/fabro-cli/src/args.rs:258-261` as a precedent for a list-time boolean filter (even though we're extending `-a` rather than adding a new flag).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `fabro ps` (default) hides a newly archived run.
|
||||
- Happy path: `fabro ps -a` shows active + terminal + archived runs.
|
||||
- Happy path: `GET /api/v1/runs` (default) hides archived.
|
||||
- Happy path: `GET /api/v1/runs?include_archived=true` shows archived.
|
||||
- Edge case: `fabro ps -a` on a server with only archived runs shows them (not the "No running processes found" hint).
|
||||
- Edge case: `fabro ps` on a server with only archived runs shows the empty-list hint pointing to `-a`.
|
||||
- Edge case: `status_cell()` renders `archived` in gray.
|
||||
- Integration: run the full lifecycle — create → run → complete → `ps` shows it → `archive` → `ps` hides it → `ps -a` shows it → `unarchive` → `ps` still hides it (now succeeded, still terminal, still hidden without `-a`).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli -p fabro-server -p fabro-workflow` passes.
|
||||
- Snapshot tests for `fabro ps` output under each mode accepted via `cargo insta accept --snapshot <...>`.
|
||||
- Manual smoke against a local server with a small run population covering all three status buckets (active, terminal-non-archived, archived).
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** adds two new server routes; extends one (`listRuns`). Six existing mutation handlers get an archived-specific 409 branch. Two operations (`resume`, `rewind`) get an archived precondition. One existing event family (status-transition) gains two variants; the projection gets two apply arms. CLI gets two new top-level commands; one list filter extends.
|
||||
- **Error propagation:** archived-rejection errors surface as `Error::Precondition` in the workflow layer, 409 in HTTP, and non-zero exit codes with actionable per-ID messages at the CLI. The canonical error text is shared across all surfaces.
|
||||
- **State lifecycle risks:** unarchive reads `projection.prior_status` (set by the `RunArchived` apply arm), so there is no event-log scan at unarchive time. Projection stays pure append-and-apply. The risk is reduced to a single invariant: `prior_status` must be `Some` whenever `status == Archived`. Enforced by the archive apply arm being the only code that sets status to Archived and the unarchive apply arm being the only code that clears `prior_status`.
|
||||
- **API surface parity:** both `InternalRunStatus` and public `RunStatus` gain `archived` (forced by exhaustive matches at `server.rs:2573-2582, 3317-3327`). `RunStatusResponse` callers get a new enum value. The hand-maintained web UI `RunStatus` type in `app/data/runs.ts` is updated in lockstep so archived runs render correctly.
|
||||
- **Integration coverage:** scenario test in `lib/crates/fabro-cli/tests/it/scenario/archive.rs` covers the full cross-command lifecycle. `cargo nextest run -p fabro-server` conformance test guards OpenAPI/router drift.
|
||||
- **Unchanged invariants:** the `* → Dead` transition escape hatch. The `attach_event_is_terminal()` semantics (matches on event body, not status). The supervisor/orphan-recovery paths (already skip terminal runs; archived now qualifies). The `DELETE /runs/{id}` behavior (archived runs remain deletable). The event-sourcing purity of the projection (archive/unarchive are both append-only events).
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| `projection.prior_status` gets out of sync with `status == Archived` due to a future apply arm or code path that sets status=Archived without also setting prior_status | Only the `RunArchived` apply arm sets status to Archived. Add a debug-assert in the unarchive operation: `debug_assert!(prior_status.is_some())` and return an invariant-violated error if somehow None. A property test on projection replay can catch drift. |
|
||||
| OpenAPI regen introduces breaking changes for existing in-repo TS client callers | Both enums gain `archived`. The generated TS client enums pick it up automatically; the hand-maintained `apps/fabro-web/app/data/runs.ts` union is updated in Unit 7. A grep for `switch`/`match` over `RunStatus` in `apps/fabro-web/` during Unit 7 confirms no other consumer regresses. |
|
||||
| A caller invokes `append_run_event` with a client-supplied `RunArchived`/`RunUnarchived`/`RunCompleted` body to bypass the operations-layer authz+precondition | Unit 4 adds an event-variant allowlist check to `append_run_event` so lifecycle-transition variants are rejected at the endpoint (see Unit 4 Approach). |
|
||||
| `is_terminal()` semantics change silently breaks a caller we missed in the audit | Every production caller was enumerated in the research section; the change treats archived as terminal, which is safer than the reverse. `cargo nextest run --workspace` is the gate — if a caller needed the old "immutable" meaning, it was already calling `can_transition_to`, which now uses `is_immutable()`. |
|
||||
| Scripted users of `-a` get archived runs in their output after the flag extension | Intentional per user decision; document in release notes and the `-a` help text. |
|
||||
| Concurrent archive + status transition race on the same run | Per-run `event_seq` is atomic; the event that wins (`Succeeded/Failed` vs `Archived`) is whichever commits first. The later one fails `can_transition_to` and returns a precondition error. Handled naturally by the existing guard. |
|
||||
| Label/tag/comment writes on archived runs in a future feature | No such endpoints exist today; the plan adds no specific rejection for them. The Deferred to Implementation item records that future annotation surfaces must include an archive check. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- Update `docs/core-concepts/runs.md` (if it exists) or the appropriate user-facing CLI docs to describe the archived lifecycle.
|
||||
- Add a changelog entry for the new commands and the `-a` extension (user-visible).
|
||||
- No migration is required — existing runs keep their prior statuses; the new status appears only on runs the user explicitly archives.
|
||||
- No monitoring changes — archive/unarchive events flow through the existing event pipeline and telemetry.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **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:** [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`)
|
||||
- **Status-transition event precedent:** `lib/crates/fabro-workflow/src/event.rs:89-92` (`RunRemoving`)
|
||||
- **Projection apply:** `lib/crates/fabro-store/src/run_state.rs:82-154`
|
||||
|
|
@ -1,991 +0,0 @@
|
|||
---
|
||||
title: "feat: Files Changed tab for workflow runs"
|
||||
type: feat
|
||||
status: completed
|
||||
date: 2026-04-19
|
||||
origin: docs/brainstorms/2026-04-19-run-files-changed-tab-requirements.md
|
||||
---
|
||||
|
||||
{/*
|
||||
Implementation status (2026-04-19): all 13 units shipped on main.
|
||||
|
||||
- [x] Unit 1: OpenAPI spec + schema extensions
|
||||
- [x] Unit 2: Lifecycle — capture final_patch on RunFailed
|
||||
- [x] Unit 3: Sandbox git machine-readable helpers
|
||||
- [x] Unit 4: Per-run request coalescing primitive
|
||||
- [x] Unit 5: Real list_run_files handler (sandbox path)
|
||||
- [x] Unit 6: Degraded fallback (final_patch) + empty envelope
|
||||
- [x] Unit 7: Demo handler parity
|
||||
- [x] Unit 8: Security & observability (logging-strategy.md update;
|
||||
denylist lives inline in run_files.rs — a globset-based module
|
||||
extraction is the one remaining follow-up from this plan)
|
||||
- [x] Unit 9: TS client regen + @pierre/diffs upgrade (1.0.11 → 1.1.15)
|
||||
- [x] Unit 10: Rendering paths (MultiFileDiff / PatchDiff / placeholders)
|
||||
- [x] Unit 11: Empty/error/loading/refresh states + SSE revalidation
|
||||
- [x] Unit 12: A11y + responsive + deep-link
|
||||
- [x] Unit 13: Surface tab + verification
|
||||
|
||||
Deferred follow-ups (not blocking ship):
|
||||
- Extract inline denylist from run_files.rs into a shared globset-based
|
||||
run_files_security module and add unit tests for non-UTF-8 path
|
||||
handling.
|
||||
- Wrap large diff lists in `<Virtualizer>` once a run with >50 files
|
||||
demonstrates a measurable rendering regression.
|
||||
*/}
|
||||
|
||||
|
||||
# feat: Files Changed tab for workflow runs
|
||||
|
||||
## Overview
|
||||
|
||||
Make the existing `apps/fabro-web/app/routes/run-files.tsx` skeleton real. Replace the hardcoded `fallbackFiles` fixture with a live diff sourced from the run's sandbox (while active) or from the stored `final_patch` string (once the sandbox is gone), rendered via `@pierre/diffs`. Surface the tab in the Run Detail UI, add security controls (auth, path denylist, request budget), and add a small lifecycle change so Failed runs also capture a `final_patch` for post-sandbox viewing.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The Files tab skeleton already imports `@pierre/diffs`' `MultiFileDiff` and calls `GET /runs/:id/files`, but that endpoint does not exist on the server — the route falls back to hardcoded fixture data. The tab is currently hidden from navigation via `broken: true` in `apps/fabro-web/app/routes/run-detail.tsx:14`. Users cannot see what a run actually changed without leaving Fabro.
|
||||
|
||||
This is also a **reintroduction** — the same endpoint *path* was defined-but-unimplemented and explicitly deleted in `docs/plans/2026-04-05-run-adjacent-server-only-cleanup-plan.md` §6; the `PaginatedRunFileList`/`FileDiff`/`DiffFile` schemas **survived** and remain in `docs/api-reference/fabro-api.yaml` today as orphans. Unit 1 re-wires the existing schemas (replacing the `PaginationMeta` reference on `PaginatedRunFileList` with the new `RunFilesMeta`) rather than reintroducing them from scratch.
|
||||
|
||||
That cleanup's stated rationale was that **the CLI** shouldn't reconnect to sandboxes for live diffs — the concerns were CLI UX (long sandbox spin-up, flaky reconnects destroying an interactive command) and avoiding a CLI-only sandbox dependency. Those concerns apply differently here: (1) the consumer is a web UI, not a CLI, where a "this didn't load" spinner is acceptable where a hanging `fabro diff` invocation wasn't; (2) the plan treats reconnect failure as a fall-through to a stored-patch fallback (Unit 6) rather than a hard error, so a failed reconnect degrades gracefully; (3) no new sandbox dependency is introduced in CLI code paths. The April 5 deletion is respected: no CLI code in this plan calls `reconnect_run_sandbox`.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
This plan satisfies the requirements in `docs/brainstorms/2026-04-19-run-files-changed-tab-requirements.md`:
|
||||
|
||||
**UI (R1–R8):**
|
||||
- R1 (render via @pierre/diffs) — Units 9, 10
|
||||
- R2 (toolbar toggles + persist split/unified) — Unit 10
|
||||
- R3 (remove Steer) — Unit 10
|
||||
- R4 (empty-state taxonomy) — Unit 11
|
||||
- R5 (error-state taxonomy) — Unit 11
|
||||
- R6 (loading + refresh + freshness) — Unit 11
|
||||
- R7 (deep link) — Unit 12
|
||||
- R8 (a11y + responsive) — Unit 12
|
||||
|
||||
**Diff semantics (R9–R13):**
|
||||
- R9 (committed-HEAD only) — Units 3, 5
|
||||
- R10 (live sandbox path) — Units 3, 5
|
||||
- R11 (post-sandbox = final_patch only) — Unit 6
|
||||
- R12 (degraded view via PatchDiff) — Units 6, 10
|
||||
- R13 (coverage by run state, use `git_commit_sha` on Failed) — Unit 13 verification
|
||||
|
||||
**API contract (R14–R18):**
|
||||
- R14 (endpoint + operationId) — Unit 1
|
||||
- R15 (optional `from_sha`/`to_sha`, reject non-default) — Units 1, 5
|
||||
- R16 (materialize-on-demand) — Unit 5
|
||||
- R17 (don't change `final_patch` consumers) — Unit 2 explicitly preserves
|
||||
- R18 (no lifecycle push) — Unit 2 (captures `final_patch` without pushing)
|
||||
|
||||
**Schema extensions (R19–R23):**
|
||||
- R19 (`change_kind` optional) — Unit 1
|
||||
- R20 (contents conventions for add/delete/rename) — Unit 1
|
||||
- R21 (`truncated` + `binary` independent) — Unit 1
|
||||
- R22 (`sensitive` flag) — Unit 1
|
||||
- R23 (additive back-compat) — Unit 1
|
||||
|
||||
**Caps (R24–R28):**
|
||||
- R24 (per-file 256 KB / 20k lines) — Units 3, 5
|
||||
- R25 (aggregate 5 MB) — Unit 5
|
||||
- R26 (skip binary) — Units 3, 5
|
||||
- R27 (200-file cap) — Unit 5
|
||||
- R28 (`--find-renames=50%`) — Unit 3
|
||||
|
||||
**Security & observability (R29–R35):**
|
||||
- R29 (authentication + IDOR-safe 404) — Unit 5
|
||||
- R30 (committed-only as primary control) — Units 3, 5
|
||||
- R31 (sensitive-path denylist) — Units 5, 6, 8
|
||||
- R32 (request budget + coalescing) — Units 4, 5
|
||||
- R33 (git hardening env) — Units 3, 8
|
||||
- R34 (demo isolation) — Unit 7
|
||||
- R35 (log redaction) — Unit 8
|
||||
|
||||
**Demo (R36):** moves `fallbackFiles` into demo handler — Unit 7
|
||||
|
||||
### Success Criteria (quantified)
|
||||
|
||||
Carried from origin + new measurable targets:
|
||||
|
||||
- **Coverage**: ≥ 85% of Files-tab opens on runs ≤ 7 days old return `meta.degraded: false` with `data.length > 0` or explicit R4(b) "no changes" state. Older runs or Failed-no-checkpoint runs are allowed to show R4(c).
|
||||
- **Latency**: **p95 < 3 s** for the endpoint on runs with ≤ 200 files and ≤ 5 MB aggregate content, measured from request accept to response complete. Live-Daytona runs may have a separate p95 ≤ 10 s budget until `git cat-file --batch` batching is in place.
|
||||
- **First contentful paint**: within 500 ms of the response's first byte on the client.
|
||||
- **Security**: zero occurrences of diff contents, full changed-file paths, or git stderr in production logs over a 7-day observation window (measurable via Sentry search on the tracing field set).
|
||||
- **Freshness**: `CheckpointCompleted` SSE event triggers a UI revalidation within 1 s of receipt (500 ms debounce + round-trip).
|
||||
- **Demo mode**: `X-Fabro-Demo: 1` returns the fixture response without touching `state.runs` or `state.store` (verified by a test spy).
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No uncommitted working-tree view (deferred to v2; see origin Key Decisions).
|
||||
- No lifecycle push-on-failure and no changes to `RunFailed` event shape beyond adding `final_patch` (no head SHA push, no ref pollution, no CI triggers).
|
||||
- No per-stage / per-checkpoint UI; `from_sha`/`to_sha` params exist as forward-compat slots only — v1 rejects non-default values with 400.
|
||||
- No origin-side read path. Post-sandbox runs without `final_patch` show an empty state.
|
||||
- No search/filter/grouping beyond what `@pierre/diffs` provides natively.
|
||||
- No content-based secret detection (denylist is path-only, defense-in-depth).
|
||||
- No SlateDB schema change; `final_patch` stays `Option<String>` on `RunProjection`.
|
||||
- No change to the `PaginatedRunFileList` schema name even though cursor pagination isn't used (additive meta change only).
|
||||
- No "Steer" inline commenting on diff lines (already out of scope; the skeleton's Steer UI is removed).
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- **Handler pair idiom (`demo::*_stub` + real)**: `lib/crates/fabro-server/src/demo/mod.rs:94-122` (`get_run_stages`, `list_run_artifacts_stub`) and `lib/crates/fabro-server/src/server.rs:2102-2204` (`list_run_stages`). Extractor order: `_auth: AuthenticatedService, State(state), Path(id), Query(params)`.
|
||||
- **Route registration**: `lib/crates/fabro-server/src/server.rs:1000-1076` (demo router) and `:1078-1149` (real router). The `/api/v1` prefix is applied at mount-time, not in `.route(...)` paths.
|
||||
- **`ListResponse<T>` wrapper**: `lib/crates/fabro-server/src/server.rs:211-225` — the in-repo baseline for "paginated" endpoints that actually return naturally-bounded lists (always sets `has_more: false`). `list_run_stages` uses this pattern today even though it accepts `PaginationParams`.
|
||||
- **Sandbox reconnect**: `lib/crates/fabro-sandbox/src/reconnect.rs:17-60` (dispatches on `provider` string; only Local and Daytona are compiled into the server — `fabro-server/Cargo.toml:25` enables only `features = ["daytona"]`, so Docker runs would 409 at reconnect). `reconnect_run_sandbox` in `lib/crates/fabro-server/src/server.rs:5797-5806` maps all reconnect errors to `StatusCode::CONFLICT`.
|
||||
- **Sandbox git helpers**: `lib/crates/fabro-workflow/src/sandbox_git.rs`. `GIT_REMOTE` (line 23), `shell_quote` (line 26), `git_diff` at line 185 is `pub(crate)` with a 30 s timeout and returns an unbounded string — not fit for the new endpoint. A sibling machine-readable helper is needed.
|
||||
- **`RunProjection.final_patch`**: `lib/crates/fabro-store/src/run_state.rs:35`, populated at `lib/crates/fabro-workflow/src/lifecycle/git.rs:303-332` via `on_run_end` when `outcome.status == Success || PartialSuccess`. Extending to Failed is the lifecycle change in Unit 2.
|
||||
- **Redaction**: `lib/crates/fabro-redact/src/` is gitleaks+entropy at the content level. No path-denylist exists anywhere — Unit 8 is greenfield for that.
|
||||
- **Frontend API helpers**: `apps/fabro-web/app/api.ts:41-47` (`apiJson`), `:115-130` (`apiJsonOrNull` — handles 404 and 501 gracefully — use this for the new route).
|
||||
- **Route conventions**: loaders use `({ request, params })`; `export const handle = { wide: true }` toggles wide layout; data flows through `withRouteModule` wrapper (`router.tsx:42-49`).
|
||||
- **Tab visibility**: `apps/fabro-web/app/routes/run-detail.tsx:14` has `{ name: "Files Changed", path: "/files", broken: true }`; `:68` filters with `!t.broken`. Removing the flag makes the tab visible.
|
||||
- **SSE revalidation pattern**: `apps/fabro-web/app/components/stage-sidebar.tsx:39-66` uses `useRevalidator` + debounced SSE subscription to `/api/v1/runs/${id}/attach`. Use this pattern to refresh the Files tab on `CheckpointCompleted` events for Running runs.
|
||||
- **OpenAPI conformance test**: `lib/crates/fabro-server/tests/it/openapi_conformance.rs` `all_spec_routes_are_routable` — fails immediately if a spec route lacks a router entry. Register a `not_implemented` placeholder if handlers are staged across multiple units.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
From `docs/plans/`:
|
||||
|
||||
- `docs/plans/2026-04-05-run-adjacent-server-only-cleanup-plan.md` **deleted** `/api/v1/runs/{id}/files` and the `PaginatedRunFileList`/`FileDiff` schemas earlier this month. Verify via `git log -- docs/api-reference/fabro-api.yaml` before editing that file. Reviewers will want prior-art context.
|
||||
- `docs/plans/2026-04-08-production-web-ui.md` established demo-vs-real parity: demo handlers must return the same wire shape as real handlers, distinguished only by `X-Fabro-Demo: 1`. Follow this for Unit 7.
|
||||
- `docs/plans/2026-04-09-settings-toml-redesign-handoff-3.md` documented the full OpenAPI → progenitor → openapi-generator regen workflow. Key points: add optional fields (not required) for back-compat; expect a large TS-client diff; conformance test catches spec/router drift; `keys_match_openapi_spec`-style tests were deleted, so there is no active frontend↔spec key-diff gate.
|
||||
- `docs/plans/2026-04-07-interview-control-channel-and-server-slack-plan.md` pattern: enqueue with short timeout; treat channel closure as abort. Apply to sandbox subprocess invocations (R32).
|
||||
|
||||
There is no `docs/solutions/` directory in this repo; `docs/plans/` and `docs/brainstorms/` are the institutional-knowledge corpus.
|
||||
|
||||
### External References
|
||||
|
||||
- `@pierre/diffs` research (Apache-2.0, https://github.com/pierrecomputer/pierre):
|
||||
- `MultiFileDiff` takes `{oldFile, newFile}` with full contents.
|
||||
- `PatchDiff` takes a unified patch string (`parsePatchFiles` is a sibling utility that returns `FileDiffMetadata[]`).
|
||||
- `FileDiff` takes precomputed hunks (`FileDiffMetadata`) — `type` field covers `"change" | "rename-pure" | "rename-changed" | "new" | "deleted"`.
|
||||
- `renderAnnotation` is line-only; per-file banners must be sibling DOM.
|
||||
- 1.0.11 (currently installed) has **no virtualization**; 1.1.0 introduced a `Virtualizer` component and `renderHeaderPrefix`/`renderCustomHeader`. Latest is 1.1.16 (2026-04-19).
|
||||
- 1.0 → 1.1 refactored managers (`MouseEventManager`/`LineSelectionManager` merged into `InteractionManager`). Public React components keep the same shape; internal APIs change.
|
||||
- No built-in keyboard nav, no responsive split/unified; both are consumer-built.
|
||||
- Git invocation for enumeration: `git diff --raw -z --find-renames=50% <base>..HEAD` + `git cat-file --batch` (for size gating) + `git show <sha>:<path>`. Rename detection is off by default; `--find-renames=50%` is the brainstorm's pinned threshold (R28).
|
||||
|
||||
### Sources & References
|
||||
|
||||
- **Origin document**: [docs/brainstorms/2026-04-19-run-files-changed-tab-requirements.md](../brainstorms/2026-04-19-run-files-changed-tab-requirements.md)
|
||||
- Related prior plans: `docs/plans/2026-04-05-run-adjacent-server-only-cleanup-plan.md`, `docs/plans/2026-04-08-production-web-ui.md`, `docs/plans/2026-04-09-settings-toml-redesign-handoff-3.md`, `docs/plans/2026-04-07-interview-control-channel-and-server-slack-plan.md`
|
||||
- External: https://diffs.com/ (@pierre/diffs docs), https://github.com/pierrecomputer/pierre
|
||||
- Logging strategy to extend: `docs-internal/logging-strategy.md`
|
||||
- AGENTS.md rules: shell quoting (`shell_quote`), import style, API workflow (spec → progenitor → handler → conformance test → TS regen)
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|---|---|
|
||||
| **Drop origin-read entirely; use `final_patch` + `PatchDiff` for post-sandbox runs.** | `@pierre/diffs` renders unified patches natively via `PatchDiff`. Origin-read would add the GitHub REST vs bare-clone decision, credential scoping, and a server-side patch parser for no added UX beyond what the stored patch string can deliver. Trade: patch-only view lacks surrounding file context, flagged in the UI with a banner. |
|
||||
| **Capture `final_patch` on `RunFailed` (no push, no refs).** | A 6-line change in `lifecycle/git.rs` closes the Failed-post-sandbox coverage gap with zero blast radius (no origin push, no CI triggers, no crash-time credentials). Hard-crash paths that don't reach the lifecycle hook still fall to R4(c) empty state. |
|
||||
| **Upgrade `@pierre/diffs` to 1.1.x.** | `Virtualizer` protects the tab against large runs; `renderHeaderPrefix` replaces sibling-div hacks for binary/truncated/sensitive banners. Breaking changes live in internal managers (`InteractionManager`) — public React components are stable. |
|
||||
| **Response shape**: reuse `PaginatedRunFileList` name; introduce `RunFilesMeta` replacing `PaginationMeta` on this endpoint. | Keeps the existing schema name (already in the spec and the TS client as a type alias). Adds `truncated`, `total_changed`, optional `degraded`, optional `patch` without touching shared `PaginationMeta`. Non-breaking for consumers of `PaginationMeta` on other endpoints. |
|
||||
| **No cursor pagination; single top-level `truncated` + `total_changed`.** | Natural-bound list with a hard 200-file cap. Follows `ListResponse<T>` precedent where "paginated" just means "bounded". Adding a cursor is deferred until a consumer needs it. |
|
||||
| **`change_kind` is optional.** | Resolves the R19/R23 back-compat tension: existing progenitor/openapi-generator clients can ignore it; v1 clients that know about it can skip hunk inspection. Kept as additive-only metadata. |
|
||||
| **Denylist in server code; content-based scanning out of scope.** | `fabro-redact` is content-level; the brainstorm explicitly confines R31 to path-based skipping. Matches the "authz gate + `git diff` parity" framing in R30. Config-driven denylist can come later. |
|
||||
| **Request coalescing, not queuing.** | Concurrent callers for the same run share one in-flight materialization via a singleflight map on `AppState`. Avoids redundant git work, prevents queue-exhaustion DoS, and is simpler than a 429-with-retry policy. |
|
||||
| **Use `apiJsonOrNull` on the web loader.** | Handles 404 and 501 gracefully, so dev environments without the new route (or demo without the new demo stub) render R4(c) empty state instead of hitting `RootErrorBoundary`. Mirrors the precedent in `run-stages.tsx:118` and `run-overview.tsx:16`. |
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Post-sandbox read mechanism** (origin doc, Resolve-Before-Planning): resolved by dropping origin-read; use `final_patch` + `PatchDiff`.
|
||||
- **Keep R12 degraded view or drop?**: keep R12. Implementation is near-trivial given `PatchDiff`; no full server-side patch parser (a regex-level header scan is sufficient for denylist enforcement).
|
||||
- **Sandbox provider coverage**: Local + Daytona in the deployed server (Docker feature is not compiled into `fabro-server` per `lib/crates/fabro-server/Cargo.toml:25`). For runs whose `SandboxRecord.provider` is `"docker"`, reconnect returns `Ok(None)` via the new `try_reconnect_run_sandbox` helper and we fall through to `final_patch` with `degraded_reason: "provider_unsupported"`.
|
||||
- **Lifecycle change for Failed runs**: approved — capture `final_patch` on `RunFailed` without any push or ref change, using a shorter 10 s timeout to bound terminal latency.
|
||||
- **Patch parser choice**: no full server-side parser. Degraded-view client uses `@pierre/diffs` `PatchDiff` / `parsePatchFiles`. Server does a one-regex header scan for denylist enforcement.
|
||||
- **Freshness timestamp source**: `to_sha_committed_at` for Running runs; HTTP response time for completed. Refresh disabled when `to_sha` is unchanged.
|
||||
- **`to_sha` on the wire**: added to `RunFilesMeta` in Unit 1 (optional). Unit 5 populates from `git rev-parse HEAD` on the sandbox; Unit 6 populates from `RunProjection.conclusion.git_commit_sha` for degraded responses.
|
||||
- **Coalescing shape**: inline concrete implementation on `AppState`, not a generic `CoalescingRegistry<K, V>` module. Drive via `tokio::spawn` + `broadcast::Receiver` (not `Shared<BoxFuture>` alone) to decouple materialization from caller liveness. `catch_unwind` around the materialization body.
|
||||
- **`total_changed` for degraded responses**: count `^diff --git ` headers in the filtered patch via a compiled regex — cheap and accurate.
|
||||
- **Placeholder priority**: `sensitive > binary > symlink/submodule > truncated` so security signals never get hidden.
|
||||
- **Denylist matching**: `globset` against separate basename and path-suffix globsets. Checked against both `old_path` and `new_path` for renames.
|
||||
- **Authorization**: v1 matches sibling `/runs/{id}/*` endpoints (authentication only via `AuthenticatedService`). Unauthorized returns **404** (not 403/401) to prevent run-ID enumeration. Per-run workspace membership is a cross-cutting follow-up tracked separately, not this plan's scope.
|
||||
- **Unit 1 back-compat grep**: the implementer runs `rg "PaginatedRunFileList\['meta'\]|PaginatedRunFileList\\.meta"` across the monorepo before editing the schema and records zero-or-N existing consumers in the PR description.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Exact method signatures** for the new machine-readable sandbox-git helpers — let implementation pick them when writing tests.
|
||||
- **Final TS-client regen diff size** — will be large by construction; reviewers should expect it. Regenerate last.
|
||||
- **SSE event wire name** — `CheckpointCompleted` is almost certainly the canonical name; confirm against `lib/crates/fabro-workflow/src/event.rs` during Unit 11.
|
||||
- **First-file-exceeds-5 MB behavior**: if the very first non-sensitive text file already exceeds the aggregate 5 MB budget, apply the per-file cap (R24: 256 KB / 20 k lines) first; the aggregate cap never kicks in for that file. Subsequent files hit the aggregate cap normally.
|
||||
- **Exact `ListRunFilesParams` field names** (`page[limit]` vs `pageLimit` etc.) — match the sibling `PaginationParams` serde renames exactly; implementation confirms at write-time.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
### Response envelope
|
||||
|
||||
```yaml
|
||||
# OpenAPI sketch — directional
|
||||
FileDiff:
|
||||
required: [old_file, new_file]
|
||||
old_file: DiffFile
|
||||
new_file: DiffFile
|
||||
change_kind?: "added" | "modified" | "deleted" | "renamed" | "symlink" | "submodule"
|
||||
truncation_reason?: enum # "file_too_large" | "budget_exhausted" (absent when not truncated)
|
||||
truncated?: boolean # convenience: truncation_reason.is_some()
|
||||
binary?: boolean # content is not textual (contents always "")
|
||||
sensitive?: boolean # path matched denylist (contents always "")
|
||||
|
||||
RunFilesMeta: # new — replaces PaginationMeta on this endpoint
|
||||
required: [truncated, total_changed]
|
||||
truncated: boolean # any truncation applied (file-count, per-file, or aggregate)
|
||||
files_omitted_by_budget?: int # count of files dropped because the 5 MB aggregate cap was exhausted
|
||||
total_changed: integer # total files actually changed in the run
|
||||
to_sha?: string # head SHA the diff/patch was resolved against
|
||||
to_sha_committed_at?: timestamp # commit time of to_sha (for "Checkpoint Xm ago" indicator)
|
||||
degraded?: boolean # true when response is patch-only (no file contents)
|
||||
degraded_reason?: enum # "sandbox_unreachable" | "sandbox_gone" | "provider_unsupported"
|
||||
patch?: string # unified patch text (capped at 5 MB), only present when degraded=true
|
||||
|
||||
PaginatedRunFileList: # name retained; meta type changed
|
||||
required: [data, meta]
|
||||
data: [FileDiff]
|
||||
meta: RunFilesMeta
|
||||
```
|
||||
|
||||
### Handler flow
|
||||
|
||||
```text
|
||||
GET /api/v1/runs/{id}/files
|
||||
|
||||
1. Parse & auth:
|
||||
_auth: AuthenticatedService
|
||||
parse_run_id_path(id) -> RunId (400 on malformed)
|
||||
load_run_record(id) (404 if not found)
|
||||
|
||||
2. Reject non-default from_sha/to_sha:
|
||||
if from_sha or to_sha provided and != default -> 400
|
||||
|
||||
3. Coalesce:
|
||||
key = RunId
|
||||
materialize via AppState.files_registry.run_coalesced(key, async { ... })
|
||||
|
||||
4. materialize():
|
||||
a. If run has an active sandbox (SandboxRecord present):
|
||||
try reconnect_run_sandbox -> Box<dyn Sandbox>
|
||||
if ok:
|
||||
files = run new machine-readable sandbox_git helper
|
||||
(git diff --raw -z --find-renames=50% <base>..HEAD,
|
||||
then per-file git cat-file -s + git show <sha>:<path>)
|
||||
files = apply_denylist(files) # R31
|
||||
files = apply_caps(files) # R24, R25, R27
|
||||
return { data: files,
|
||||
meta: { truncated, total_changed,
|
||||
degraded: false } }
|
||||
if reconnect fails -> fall through
|
||||
|
||||
b. If final_patch is Some:
|
||||
return { data: [],
|
||||
meta: { truncated: false, total_changed: 0,
|
||||
degraded: true, patch: final_patch } }
|
||||
|
||||
c. Else (no sandbox + no final_patch):
|
||||
return { data: [],
|
||||
meta: { truncated: false, total_changed: 0,
|
||||
degraded: false } }
|
||||
# Empty envelope — UI maps to R4(c).
|
||||
|
||||
5. Errors:
|
||||
Sandbox git subprocess timeout / non-zero exit → 503 transient.
|
||||
Coalescing future panic → 500 unknown, with request ID.
|
||||
|
||||
All logging emits only: run_id, file_count, bytes_total, duration_ms,
|
||||
truncated, binary_count, sensitive_count. No paths, no contents,
|
||||
no raw git stderr. (R35)
|
||||
```
|
||||
|
||||
### Client rendering
|
||||
|
||||
```text
|
||||
RunFiles component:
|
||||
|
||||
if meta.degraded && meta.patch:
|
||||
<PatchDiff patch={meta.patch} options={...}>
|
||||
<DegradedBanner reason="Contents unavailable; showing patch only" />
|
||||
|
||||
elif data.length > 0:
|
||||
<Virtualizer> # @pierre/diffs 1.1.x
|
||||
for file in data:
|
||||
if file.binary: <BinaryPlaceholder name={file.new_file.name} change={file.change_kind} />
|
||||
elif file.sensitive:<SensitivePlaceholder name={file.new_file.name} />
|
||||
elif file.truncated:<TruncatedPlaceholder name={file.new_file.name} />
|
||||
else: <MultiFileDiff oldFile={file.old_file} newFile={file.new_file} options={...} />
|
||||
|
||||
else:
|
||||
<EmptyState kind={deriveEmptyKind(runStatus, meta.degraded)} /> # R4 taxonomy
|
||||
```
|
||||
|
||||
### Data flow summary
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A[Web loader] -->|GET /runs/:id/files| B[fabro-server handler]
|
||||
B --> C{Run has active sandbox?}
|
||||
C -->|yes| D[reconnect_run_sandbox]
|
||||
D -->|ok| E[sandbox_git::list_changed_files_raw]
|
||||
E --> F[apply denylist + caps]
|
||||
F --> G[FileDiff[] response]
|
||||
C -->|no, or reconnect fails| H{final_patch present?}
|
||||
D -->|fails| H
|
||||
H -->|yes| I[Degraded response: patch string in meta]
|
||||
H -->|no| J[Empty envelope]
|
||||
G --> K[Client: MultiFileDiff per file]
|
||||
I --> L[Client: PatchDiff with meta.patch]
|
||||
J --> M[Client: R4 empty state]
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [ ] **Unit 1: OpenAPI spec — endpoint + schema extensions**
|
||||
|
||||
**Goal:** Add `GET /api/v1/runs/{id}/files` to the spec with `operationId: listRunFiles`, extend `FileDiff` with optional metadata fields, replace the endpoint's `meta` with a new `RunFilesMeta`, and regenerate Rust + TS clients.
|
||||
|
||||
**Requirements:** R14, R15, R19, R20, R21, R22, R23, R27
|
||||
|
||||
**Dependencies:** None (foundational; unblocks Units 5, 6, 7, 9)
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/api-reference/fabro-api.yaml` (add path, extend schemas, add `RunFilesMeta`)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (register route against `not_implemented` to satisfy conformance test; real handler lands in Unit 5)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs:25-41` (add `pub use fabro_api::types::{FileDiff, RunFilesMeta, PaginatedRunFileList, DiffFile}` re-exports if missing)
|
||||
- Test: `lib/crates/fabro-server/tests/it/openapi_conformance.rs` (already exists; validates routability)
|
||||
- Regenerated (do not hand-edit): `lib/packages/fabro-api-client/src/models/file-diff.ts`, `diff-file.ts`, `paginated-run-file-list.ts`, and a new `run-files-meta.ts`
|
||||
|
||||
**Approach:**
|
||||
- Add the path under `/api/v1/runs/{id}/files:` with the same `parameters` style as `listRunStages` (path `id`, plus `Query page[limit]`/`page[offset]` if we want to keep the param shape consistent, even though v1 ignores them). Also accept optional `from_sha`/`to_sha` query params for forward compat; v1 handler rejects non-default with 400 (R15).
|
||||
- Responses: 200 with `$ref: '#/components/schemas/PaginatedRunFileList'`; 400 for invalid `from_sha`/`to_sha`; 404 for missing run; 409 for reconnect failure with an unrecoverable `final_patch` absence.
|
||||
- Extend `FileDiff` additively — `change_kind`, `truncated`, `binary`, `sensitive` all optional. `old_file`/`new_file` stay required (empty-string contents for added/deleted sides).
|
||||
- Introduce `RunFilesMeta` as a new named schema (not a modification to `PaginationMeta`) to avoid affecting other endpoints' pagination.
|
||||
- Run the regen sequence per AGENTS.md: `cargo build -p fabro-api`, then `cd lib/packages/fabro-api-client && bun run generate`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `listRunStages` operation at `fabro-api.yaml:667-689` for operation shape.
|
||||
- `list_run_artifacts` operation at `:716-736` for non-cursor response style (but keep `PaginatedRunFileList` wrapper since the schema already exists).
|
||||
- `not_implemented` handler (imported in `server.rs`) for placeholder route registration.
|
||||
|
||||
**Test scenarios:**
|
||||
- Integration: `cargo nextest run -p fabro-server --test it openapi_conformance` passes — the new route path resolves against `build_router()` (Unit 1 registers a placeholder; Unit 5 swaps in the real handler).
|
||||
- Happy path: `cargo build -p fabro-api` succeeds — progenitor accepts the schema extensions; `cd lib/packages/fabro-api-client && bun run generate` succeeds and produces `run-files-meta.ts` + updated `file-diff.ts`.
|
||||
- Back-compat: existing consumers of `FileDiff` compile unchanged (no required fields added).
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run -p fabro-server` passes (conformance test specifically).
|
||||
- TS client has `RunFilesMeta` model and updated `FileDiff` with optional fields.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 2: Lifecycle — capture `final_patch` on `RunFailed`**
|
||||
|
||||
**Goal:** Extend the workflow lifecycle's `on_run_end` hook so Failed runs also run `git diff <base_sha> HEAD` and persist the resulting patch into `RunProjection.final_patch` via a new (or reused) event field. No origin push, no ref changes.
|
||||
|
||||
**Requirements:** R13 (coverage for Failed runs when the lifecycle hook is reached)
|
||||
|
||||
**Dependencies:** None (independent; unblocks Unit 6's fallback path for Failed runs)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/lifecycle/git.rs` (`on_run_end` — drop the `Success || PartialSuccess` guard; use a **10 s** timeout on the diff capture, not the default 30 s, so Failed-run terminal latency stays bounded)
|
||||
- Modify: `lib/crates/fabro-workflow/src/lifecycle/event.rs` (the emit site at `:482` for `Event::WorkflowRunFailed` — read `self.final_patch.lock().unwrap().clone()` and pass it through to the event, mirroring the `WorkflowRunCompleted` emit at `:464-476`)
|
||||
- Modify: `lib/crates/fabro-workflow/src/event.rs` (the `Event::WorkflowRunFailed` variant + the `to_run_event` mapping near `:1585`)
|
||||
- Modify: `lib/crates/fabro-types/src/run_event/run.rs` (`RunFailedProps` at `:110` — add `#[serde(default, skip_serializing_if = "Option::is_none")] pub final_patch: Option<String>`)
|
||||
- Modify: `lib/crates/fabro-store/src/run_state.rs` (`apply_event` for `RunFailed` — clone `final_patch` into the projection like `RunCompleted` does at `:146`)
|
||||
|
||||
**Approach:**
|
||||
- Copy the existing Success/PartialSuccess logic (`lib/crates/fabro-workflow/src/lifecycle/git.rs:303-331`) to also run for `Failed`. Keep the "best-effort, log warn on error" behavior; do not fail the run because diff capture failed.
|
||||
- Use a **10 s timeout** (not the existing 30 s) for the Failed-path `git diff` invocation — Failed runs are often in a pathological state (FS locks, OOM, corrupted index), and downstream consumers (Slack notifier, SSE `RunFailed`, CI hooks) are latency-sensitive to terminal emission. Emit a `RunNotice` warn when the timeout fires; projection `final_patch` stays `None`.
|
||||
- `RunFailed` event already exists (`lib/crates/fabro-workflow/src/lifecycle/event.rs:482`) but does **not** forward `final_patch` today — this unit wires the shared `Arc<Mutex<Option<String>>>` read (already at `:426` in the Completed branch) through to the Failed emit.
|
||||
- The projection already carries `final_patch` — just copy the field through in the `RunFailed` arm.
|
||||
- **No changes to `final_patch`'s wire consumers** (PR body generation, etc.). This is additive.
|
||||
- **Event replay**: serde's `#[serde(default)]` ensures pre-change RunFailed events in SlateDB deserialize with `final_patch: None` — no corruption, no backfill required. Old Failed runs continue to show R4(c) on the Files tab.
|
||||
|
||||
**Execution note:** Start with a failing test that asserts a Failed run's `RunProjection.final_patch` is `Some(...)` after the lifecycle hook fires. That test drives all three file changes.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-workflow/src/lifecycle/git.rs:303-331` — existing `on_run_end` structure to clone.
|
||||
- `lib/crates/fabro-store/src/run_state.rs:142-148` — existing `RunCompleted` → projection mapping to mirror.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: sandbox reachable at Failed — `final_patch` populated on the projection with the expected diff string.
|
||||
- Edge case: base_sha missing on the run — skip diff capture cleanly, projection `final_patch` stays `None` (no panic).
|
||||
- Error path: `git diff` subprocess fails inside sandbox — `RunNotice` warn emitted, projection `final_patch` stays `None`, failure does not affect the run's terminal status.
|
||||
- Integration: projection round-trip — `apply_events` on a recorded `RunFailed` event with `final_patch: Some(...)` produces a projection with that patch.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-workflow` passes with the new tests.
|
||||
- `cargo nextest run -p fabro-store` passes with the event-application test.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 3: Sandbox git — machine-readable diff + blob read helpers**
|
||||
|
||||
**Goal:** Add the sandbox-side helpers the server endpoint needs: enumerate changed files with raw + rename detection, size-gate via `cat-file`, read individual blobs. Existing `git_diff` helper stays for PR/checkpoint callers.
|
||||
|
||||
**Requirements:** R10, R24, R25, R26, R27, R28, R32 (10 s timeout), R33 (shell_quote)
|
||||
|
||||
**Dependencies:** None (independent; unblocks Unit 5)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/sandbox_git.rs` (add new `pub(crate)` helpers; leave existing `git_diff` unchanged)
|
||||
- Test: `lib/crates/fabro-workflow/src/sandbox_git.rs` (unit tests in the existing `#[cfg(test)]` module, following the in-file pattern at `:239-...` which constructs a real tempdir git repo)
|
||||
|
||||
**Approach:**
|
||||
- New helper `list_changed_files_raw(sandbox, base_sha, to_sha)` → `Result<Vec<RawDiffEntry>, DiffError>`. Runs `git diff --raw -z --find-renames=50% <base>..<to_sha>`. Parses the null-separated raw output into an `enum RawDiffEntry { Added{path, blob_sha, mode}, Modified{path, old_blob, new_blob, mode}, Deleted{path, blob_sha, mode}, Renamed{old_path, new_path, old_blob, new_blob, similarity, mode}, Symlink{path, change_kind, mode}, Submodule{path, change_kind} }`. Modes of `120000` → `Symlink`; `160000` → `Submodule`; these variants never invoke blob reads. `DiffError` distinguishes `Transient { message }` (timeout, process kill) from `Permanent { message }` (bad revision, unknown object) so the handler can route permanent errors to R4/R5 rather than a 503.
|
||||
- **Use `git cat-file --batch-check` and `--batch` instead of per-file invocations.** The naive design (per-file `git cat-file -s` + `git show`) produces 400–800 sandbox RPCs for a 200-file run; `--batch-check` streams all sizes in one invocation and `--batch` streams all blobs. This is load-bearing for the p95 < 3 s target. Helper `stream_blob_metadata(sandbox, shas) → Result<Vec<BlobMeta>, DiffError>` and `stream_blobs(sandbox, shas, size_cap) → Result<Vec<Option<String>>, DiffError>` (returns `None` for blobs that exceed the cap; caller flags `truncated`).
|
||||
- **Paths from git output are metadata only**; blob reads are always SHA-addressed (`git show <sha>` or `git cat-file --batch`), never `<sha>:<path>`. This eliminates the path-quoting concern entirely — user-controlled paths never enter a shell invocation for blob reads.
|
||||
- **Binary detection**: use the `--numstat` side-call (or the raw-format `-\t-\t<path>` marker) for text vs binary. Do not attempt to read binary bytes through `--batch`; skip to `binary: true, contents: ""`.
|
||||
- **Git hardening env on every sandbox-side invocation** (R33): `GIT_TERMINAL_PROMPT=0`, `-c core.hooksPath=/dev/null`, `-c core.fsmonitor=false`, `-c protocol.file.allow=never`, unset `GIT_EXTERNAL_DIFF`. The repo contents are attacker-controlled relative to Fabro; the sandbox isolation does not substitute for flag hardening on the invocation itself.
|
||||
- All helpers use `shell_quote` for interpolated SHAs (even though SHAs are hex) as a belt-and-suspenders defense per AGENTS.md. Timeout is **10 s** sandbox-side per R32.
|
||||
- Visibility: make the new helpers **`pub`** directly in `sandbox_git.rs` rather than creating a separate `diff_inspector` module — the existing `sandbox_git.rs` is the canonical home for sandbox-git code; a new module adds structure without function.
|
||||
|
||||
**Execution note:** Test-first against a tempdir git repo fixture. Reuse the in-file pattern at `sandbox_git.rs:239+`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `sandbox_git.rs:185-195` — existing `git_diff` for the subprocess-invocation pattern.
|
||||
- `sandbox_git.rs:55-67` — `git_checkpoint` for `shell_quote` + `GIT_REMOTE` + `exec_command` boilerplate.
|
||||
- `sandbox_git.rs:246-...` — existing tempdir-based fixture style (no loops in test setup per AGENTS.md rules).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: fixture with added file, modified file, deleted file → `list_changed_files_raw` returns 3 entries with correct `RawDiffEntry` variants and paths.
|
||||
- Happy path: fixture with a rename (same content, new path) → single `Renamed` entry with similarity ≥ 50%.
|
||||
- Edge case: rename below threshold (significant content change + rename) → emitted as `Deleted` + `Added` pair (no `Renamed` variant).
|
||||
- Edge case: binary file (PNG fixture) → entry flagged `binary: true`; `blob_size` + `show_blob` bypassed by caller.
|
||||
- Edge case: very large text file (>256 KB) → `blob_size` reports correctly; caller truncates without reading contents.
|
||||
- Error path: invalid base SHA → helper returns `Err(...)` without panicking.
|
||||
- Error path: sandbox `exec_command` returns non-zero → helper returns `Err(format!("exit ...: ..."))` matching existing pattern.
|
||||
- Integration: after `git_checkpoint`, `list_changed_files_raw(sandbox, base_sha)` returns the expected set (verifies the helper composes with existing lifecycle).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-workflow` passes with new tests.
|
||||
- `cargo +nightly-2026-04-14 clippy -p fabro-workflow --all-targets -- -D warnings` passes (no new `wildcard_imports` or unsafe code).
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 4: Server — per-run request-coalescing primitive**
|
||||
|
||||
**Goal:** Add a singleflight/coalescing registry to `AppState` so concurrent callers hitting `/runs/{id}/files` for the same run share one materialization. Different run IDs remain parallel.
|
||||
|
||||
**Requirements:** R32 (request coalescing per run)
|
||||
|
||||
**Dependencies:** None (unblocks Unit 5)
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (`AppState` struct at `:534-556` — add `files_in_flight: Arc<tokio::sync::Mutex<HashMap<RunId, Weak<Shared<BoxFuture<Arc<Result<ListRunFilesResponse, ApiError>>>>>>>>`) and a `coalesced_list_run_files` helper fn in the same file or in Unit 5's new `run_files.rs`
|
||||
- Modify: `lib/crates/fabro-server/src/error.rs` (derive `#[derive(Clone)]` on `ApiError`)
|
||||
- Test: tests are colocated with the helper (in `run_files.rs` or `server.rs`) — no standalone module/file
|
||||
|
||||
**Approach:**
|
||||
- **Inline the coalescer; do not build a generic `CoalescingRegistry<K, V>` module.** There is only one consumer. Use a concrete `Arc<tokio::sync::Mutex<HashMap<RunId, Weak<Shared<BoxFuture<Arc<Result<ListRunFilesResponse, ApiError>>>>>>>>` field on `AppState`, accessed by a single helper fn `coalesced_list_run_files(&state, run_id, materialize_fn) -> Arc<Result<...>>`. Promote to a shared primitive only when a second consumer appears.
|
||||
- **Drive materialization via `tokio::spawn`, not via `Shared` polling alone.** `Shared<BoxFuture>` only makes progress while at least one caller polls; if the first HTTP request is cancelled before the second starts polling, materialization stalls. `tokio::spawn` detaches execution from callers: the first caller inserts a `(spawn_handle, broadcast::Receiver)` into the map, subsequent callers get a new receiver, and everybody waits for the shared result regardless of who stays subscribed.
|
||||
- **Wrap the materialization body in `AssertUnwindSafe(...).catch_unwind()`** so a panic inside one materialization becomes an `ApiError::internal_server_error("materialization panicked", request_id)` for all coalesced callers — and a *new* caller on that run_id after the panic triggers a fresh materialization (no poisoning).
|
||||
- **Cancellation policy on abandoned materialization**: if all callers drop, the spawned task **continues to completion** (worst-case consumes one sandbox-exec budget) rather than cancelling mid-git-subprocess, which risks orphan processes in the sandbox. The cost of completed-but-discarded work is bounded by R32's 10 s git timeout; the cost of orphan sandbox processes is not.
|
||||
- **Error sharing**: the value type is `Arc<Result<T, ApiError>>` so errors are shared across concurrent callers, but the entry is evicted from the map as soon as the task completes — the next caller after completion triggers a fresh materialization (by design; we do not cache across requests).
|
||||
- **ApiError Clone**: derive `#[derive(Clone)]` on `ApiError` (fields are `StatusCode` + `String`; cheap) so the shared `Arc<Result<T, ApiError>>` can yield `ApiError` copies to each concurrent caller without move gymnastics. Include this one-line derive in Unit 4's Files list.
|
||||
- **Crate dependency**: use `futures_util::future::Shared` (already a `fabro-server` dep via `futures-util.workspace = true`) rather than adding `futures` as a new dep.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Axum state layout at `server.rs:534-556` — add the field next to existing `Arc`-wrapped state.
|
||||
- `tokio::sync::Mutex` for the registry lock (async-safe).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: two concurrent calls with the same run_id — materialization runs once; both callers receive the same value.
|
||||
- Edge case: different run_ids — materializations run in parallel (not serialized).
|
||||
- Error path: the materialization errors — both callers receive the same cloned error.
|
||||
- Edge case: first caller cancels (request dropped) while second is still polling — materialization continues via `tokio::spawn` and the second caller still receives the value.
|
||||
- Edge case: all callers drop before completion — materialization still completes (no orphan git processes in the sandbox).
|
||||
- Error path: materialization panics — both callers receive a 500 ApiError ("materialization panicked"), not a panic. A subsequent third caller on the same run_id after the panic triggers a fresh materialization (no poisoning).
|
||||
- Integration: after a completed materialization, a new caller triggers a fresh run (no stale cache).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes with the new tests.
|
||||
- No new clippy warnings.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 5: Server — `list_run_files` real handler (sandbox path)**
|
||||
|
||||
**Goal:** Replace the `not_implemented` placeholder from Unit 1 with a real handler that loads the run, reconnects to the sandbox, runs the new sandbox-git helpers, applies caps and the denylist, coalesces concurrent requests, and returns the populated `PaginatedRunFileList`. The fallback branch (degraded / empty) is separate Unit 6 work.
|
||||
|
||||
**Requirements:** R10, R14, R15, R16, R24, R25, R26, R27, R29, R30, R31, R32, R33, R35
|
||||
|
||||
**Dependencies:** Units 1, 3, 4
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/run_files.rs` (new module housing the handler + helpers; or add in `server.rs` if the existing file is the convention — prefer a new module to keep `server.rs` size manageable)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (swap `not_implemented` for `list_run_files` in the real router; add `mod run_files;`)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (re-export new types from `fabro_api::types` where needed)
|
||||
- Test: `lib/crates/fabro-server/tests/it/api/run_files.rs` (new integration test file under the existing `tests/it/api/` layout — follow `human-in-the-loop-api.rs` conventions if present, else mirror `run_stages.rs`)
|
||||
|
||||
**Approach:**
|
||||
- **Handler signature** uses a **single combined Query extractor** `Query(params): Query<ListRunFilesParams>` flattening `page[limit]`, `page[offset]`, `from_sha`, `to_sha` — matching the `ModelListParams` pattern at `server.rs:140-149` rather than stacking two `Query<>` extractors.
|
||||
- **Authorization (R29)**: after `load_run_record`, verify the authenticated principal is entitled to the run. Match whatever predicate sibling `/runs/{id}/*` endpoints use today; if the siblings enforce authentication-only, this endpoint does too (noted as a cross-cutting follow-up in the Risks table, not this plan's scope). **Return 404 for both "run not found" and "run exists but caller lacks access"** — prevents run-ID enumeration / IDOR.
|
||||
- **SHA validation**: accept `from_sha`/`to_sha` only when matching `^[0-9a-f]{7,40}$`; malformed values → 400 before any processing. Non-default values → 400 per R15 (v1).
|
||||
- **Reconnect helper**: replace the call to `reconnect_run_sandbox` with a new sibling `try_reconnect_run_sandbox(state, run_id) → Result<Option<Box<dyn Sandbox>>, Response>`. Semantics: `Ok(Some(sandbox))` — reconnected; `Ok(None)` — no active sandbox record OR reconnect failed (fall through to Unit 6); `Err(Response)` — store-read error (→ 500) or malformed run_id (→ 400). This lets Unit 6's fallback fire cleanly without Unit 5 ever emitting 409. Leave the existing `reconnect_run_sandbox` helper for `list_sandbox_files` callers that still want 409 semantics.
|
||||
- Steps after reconnect:
|
||||
1. `parse_run_id_path(&id)` → 400 on malformed.
|
||||
2. Validate `from_sha`/`to_sha` format; reject non-default values with 400.
|
||||
3. `load_run_record(...)` → 404 if not found OR authorization check fails.
|
||||
4. Extract `base_sha` from `RunRecord.start.base_sha` (confirm field name during Unit 1) — if `None` (run hasn't started), return empty envelope mapped to R4(a).
|
||||
5. `try_reconnect_run_sandbox(...)`. On `Ok(Some(sandbox))`: proceed to sandbox path. On `Ok(None)`: fall through to Unit 6.
|
||||
6. `to_sha` = `git rev-parse HEAD` on the sandbox (one call). Capture `to_sha_committed_at` via `git show -s --format=%cI <to_sha>`.
|
||||
7. `list_changed_files_raw(sandbox, base_sha, to_sha)` → `Vec<RawDiffEntry>`. Permanent errors (bad revision, unknown object — e.g., base_sha garbage-collected) fall through to Unit 6 rather than 503. Transient errors (timeout, process kill) → 503.
|
||||
8. Apply **denylist first** (R31) using the globset-based matcher from Unit 8 — entries with a matched path get `sensitive: true` and empty contents; do not read their blobs. Denylist matches on BOTH `old_path` and `new_path` for renames — if either matches, mark sensitive.
|
||||
9. **File-count cap** (R27): stop enumeration once 200 entries are collected. Sensitive entries **do** count against the cap (they still convey information); binary and symlink/submodule entries also count against the cap.
|
||||
10. For non-sensitive, non-binary, non-symlink, non-submodule entries: use batched `stream_blob_metadata` (one call) and `stream_blobs` (one call) against all collected blob SHAs. Per-file cap (R24: 256 KB or 20k lines) → `truncated: true, truncation_reason: "file_too_large", contents: ""`.
|
||||
11. **Aggregate cap** (R25): track running bytes; once > 5 MB, remaining entries get `truncated: true, truncation_reason: "budget_exhausted"`, name + change_kind only. Set `meta.files_omitted_by_budget` count accordingly.
|
||||
12. Return `PaginatedRunFileList { data, meta: { truncated, total_changed, to_sha, to_sha_committed_at, degraded: false } }`.
|
||||
- Gate the entire materialization through the coalescing helper from Unit 4.
|
||||
- **Git hardening env on sandbox-side git invocations** (R33) is applied inside Unit 3's helpers; Unit 5 just passes the sandbox handle in. Still `shell_quote` all interpolated inputs per AGENTS.md.
|
||||
- **Logging gate** (R35): emit a single `tracing::info!` span at request end with ONLY fields `run_id`, `file_count`, `bytes_total`, `duration_ms`, `truncated`, `binary_count`, `sensitive_count`, `symlink_count`, `submodule_count`. No paths, no contents, no raw git stderr. A unit test asserts the span's field set matches this allowlist exactly.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `list_run_stages` at `server.rs:2102-2204` for extractor order and 404 handling.
|
||||
- `list_sandbox_files` at `server.rs:5698-5726` for the reconnect-error-as-409 pattern — but note we override this to fall through to Unit 6 instead of surfacing 409 directly.
|
||||
- `paginate_items<T>` at `server.rs:2688-2695` is **not** used here (not real pagination).
|
||||
- `ApiError::bad_request` / `ApiError::not_found` / `ApiError::new(StatusCode::CONFLICT, ...)` for error shapes.
|
||||
- `docs-internal/logging-strategy.md` for the tracing conventions.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: Running run with active sandbox + a simple 3-file diff — handler returns `{ data: [...], meta: { truncated: false, total_changed: 3, degraded: false } }` with correct `change_kind` and contents.
|
||||
- Edge case: 200-file cap hit — response has exactly 200 entries, `meta.truncated: true`, `meta.total_changed` reflects the actual total (> 200).
|
||||
- Edge case: binary file — entry has `binary: true, contents: ""`; file is counted against the 200 cap; blob is not read.
|
||||
- Edge case: file > 256 KB — entry has `truncated: true, contents: ""`; `blob_size` was consulted but `show_blob` was not.
|
||||
- Edge case: aggregate 5 MB cap — first N files have full contents, remainder have `truncated: true` with no contents; `meta.truncated: true`.
|
||||
- Edge case: rename at 50% threshold — emitted as `change_kind: renamed` with distinct `old_file.name` / `new_file.name` and populated contents.
|
||||
- Edge case: denylisted file (`.env.production`) — entry has `sensitive: true`, empty contents, does **not** count against the 200 cap (R31 acts before R27 in order of operations).
|
||||
- Error path: invalid run ID — 400 bad request.
|
||||
- Error path: unknown run — 404 not found.
|
||||
- Error path: invalid `from_sha` query param — 400 bad request.
|
||||
- Error path: sandbox reconnect fails — handler yields to fallback (Unit 6) rather than 409.
|
||||
- Error path: `list_changed_files_raw` subprocess times out — 503 transient; log includes `duration_ms`, no paths.
|
||||
- Integration: two concurrent HTTP calls for the same run ID — sandbox git helpers execute once (verified via a counter on a mock sandbox); both callers receive identical responses.
|
||||
- Integration: tracing span for a successful request contains only the allowlisted fields (assert via `tracing-test` or equivalent); no path or content fragments leak.
|
||||
- Integration: `AuthenticatedService` rejection — unauthenticated call returns 401/403 per existing sibling behavior (not 404; that's origin-doc R29 for IDOR-prevention, but we match existing siblings which use 401 — reconcile in implementation).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes all new + existing tests.
|
||||
- Manual: `fabro server start` + create a real run → hit `GET /api/v1/runs/<id>/files` while Running → real diff returned.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 6: Server — degraded fallback (`final_patch`) + empty envelope**
|
||||
|
||||
**Goal:** When reconnect fails (or there is no active sandbox), return either a degraded response with `meta.patch` populated from `RunProjection.final_patch`, or an empty envelope indicating R4 empty state when no diff can be produced.
|
||||
|
||||
**Requirements:** R11 (now: final_patch fallback only, not origin read), R12, R13
|
||||
|
||||
**Dependencies:** Units 1, 2, 5
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/run_files.rs` (extend the handler from Unit 5 with the fallback branch)
|
||||
- Test: `lib/crates/fabro-server/tests/it/api/run_files.rs` (new scenarios)
|
||||
|
||||
**Approach:**
|
||||
- When Unit 5's primary path signals fallback (reconnect returned `Ok(None)` or the primary git path hit a permanent error like bad revision):
|
||||
1. Load `RunProjection.final_patch`, `conclusion.git_commit_sha` (for `to_sha`), and the run status from SlateDB via the run store.
|
||||
2. If `Some(patch)`: apply a **5 MB size cap** to the patch string (truncate + set `meta.truncated: true` if over). Apply a **lightweight path-denylist filter** on the patch — scan `diff --git a/<path> b/<path>` headers (one regex; no full parser) and strip entire file sections whose path matches the denylist, replacing them with a `# sensitive file omitted: <basename-or-pattern>` placeholder. This closes the Unit 5 ↔ Unit 6 denylist asymmetry without a full patch parser. Determine `degraded_reason`: if `RunRecord.sandbox_provider == "docker"` (a provider not supported by the deployed server's Daytona-only build) → `"provider_unsupported"`; else if the run is completed → `"sandbox_gone"`; else → `"sandbox_unreachable"`. Count `diff --git` headers in the filtered patch to populate `total_changed` accurately.
|
||||
3. Return `{ data: [], meta: { truncated, total_changed: <header-count>, to_sha: git_commit_sha, to_sha_committed_at, degraded: true, degraded_reason, patch: capped_and_filtered_patch } }`.
|
||||
4. If `final_patch` is `None` → return `{ data: [], meta: { truncated: false, total_changed: 0, degraded: false } }`. The UI derives R4(c) from `{ runStatus, data.length, meta.degraded }`.
|
||||
- **Do not** build a full patch parser server-side. The regex-level header filter is sufficient to strip denylisted entries; contents within non-denylisted sections are returned as-is for the client's `PatchDiff` to render.
|
||||
- **Logging gate**: emit the same tracing field set as Unit 5 (minus sandbox-specific fields); never log the patch content, the filtered-out paths, or the raw git stderr.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Unit 5 for tracing, error handling, and response shape.
|
||||
- `lib/crates/fabro-store/src/run_state.rs:35` for `final_patch` field access.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: Succeeded run, no active sandbox, `final_patch` populated — response has `meta.degraded: true`, `meta.patch: "..."`, `data: []`.
|
||||
- Happy path: Failed run after Unit 2's lifecycle change, sandbox gone, `final_patch` populated — same shape as above.
|
||||
- Edge case: Succeeded run, `final_patch` is `None` (projection write failure) — response has `meta.degraded: false`, empty `data`, `total_changed: 0`.
|
||||
- Edge case: Running run where reconnect transiently fails — response falls back to `final_patch` if present; no 503 surfaces to the client.
|
||||
- Error path: run store read fails — 500 with request ID.
|
||||
- Integration: full handler round-trip — Running + active sandbox prefers sandbox path; Succeeded + no sandbox uses `final_patch`; Failed + no sandbox + no `final_patch` returns empty envelope.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes new scenarios.
|
||||
- Manual: terminate a run, destroy the sandbox (or wait for teardown), hit the endpoint → degraded response with `meta.patch` set.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 7: Server — demo handler parity**
|
||||
|
||||
**Goal:** Move the frontend's `fallbackFiles` fixture into a `demo::list_run_files_stub` handler that returns the exact wire shape of the real handler. Remove the fixture from the frontend so demo mode flows through the same loader path.
|
||||
|
||||
**Requirements:** R34 (demo isolation), R36
|
||||
|
||||
**Dependencies:** Unit 1
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/demo/mod.rs` (add `pub(crate) async fn list_run_files_stub` returning a static `PaginatedRunFileList`)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs:1000-1076` (register `.route("/runs/{id}/files", get(demo::list_run_files_stub))` in the demo router)
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx` (remove the `fallbackFiles` constant and the `files.length > 0 ? ... : fallbackFiles` branch)
|
||||
- Test: `lib/crates/fabro-server/tests/it/api/run_files.rs` (add a demo-mode scenario using the `X-Fabro-Demo` header)
|
||||
|
||||
**Approach:**
|
||||
- Fixture content: same files the frontend currently uses (a small refactor diff). Populate `change_kind`/`truncated`/`binary` so the demo response exercises the new schema fields (at least one `added`, one `modified`, one `renamed`; no `sensitive` or `binary` in the basic fixture, but leave a comment for future additions).
|
||||
- Demo handler must ignore the path `id` entirely (it never touches the run store) — guarantees R34 "two modes cannot cross-contaminate."
|
||||
- Frontend: the `default export RunFiles` component consumes `loaderData` directly; there is no fallback branch.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `demo::list_run_artifacts_stub` at `demo/mod.rs:112-122` for handler shape.
|
||||
- `docs/plans/2026-04-08-production-web-ui.md` Decision 3: demo handlers return the same wire shape as real handlers.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: request with `X-Fabro-Demo: 1` header returns the fixture without touching `state.runs` or `state.store` (verify via a counter / spy).
|
||||
- Happy path: request without the header on the same router tree goes through the real handler (or returns 404 if the run doesn't exist).
|
||||
- Edge case: demo handler receives an invalid run ID path — still returns the fixture (does not touch `parse_run_id_path`).
|
||||
- Integration: the demo response validates against the OpenAPI schema (use the existing conformance helpers if available; else assert serde deserializes into the regenerated TS type in a quick frontend unit test).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes demo scenarios.
|
||||
- Manual: `fabro server start` + `curl -H 'X-Fabro-Demo: 1' http://localhost:.../api/v1/runs/any-id/files` → fixture response.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 8: Server — security & observability hardening**
|
||||
|
||||
**Goal:** Centralize the sensitive-path denylist, git-process hardening (for future host-side invocations; placeholder in v1), and logging gates used by Units 5 and 6.
|
||||
|
||||
**Requirements:** R29, R30, R31, R32 (timeouts), R33, R35
|
||||
|
||||
**Dependencies:** Units 5, 6 (consume the utilities)
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/run_files_security.rs` (or add to `run_files.rs` — a separate file is cleaner since this module is reused by Units 5 and 6)
|
||||
- Modify: `lib/crates/fabro-server/src/run_files.rs` (import denylist / logging helpers)
|
||||
- Modify: `docs-internal/logging-strategy.md` (extend the prohibited-fields list to include `diff_contents`, `file_path` (for changed files specifically), `git_stderr`)
|
||||
- Test: `lib/crates/fabro-server/src/run_files_security.rs` (unit tests in-file)
|
||||
|
||||
**Approach:**
|
||||
- **Denylist uses `globset::GlobSet`** built from two explicit lists:
|
||||
- **Basename globs** (applied to the file's basename only): `.env`, `.env.*`, `*.pem`, `id_rsa*`, `*.p12`, `*.keystore`, `*.key`
|
||||
- **Path-suffix globs** (applied to the full repo-relative path): `.aws/credentials`, `.git/config`, `.ssh/**`
|
||||
- `fn is_sensitive(path: &str) -> bool` normalizes the path (reject non-UTF-8 → returns `true` as a safe default; normalize `./`/`../`), then matches against both globsets. For renames, the handler checks both `old_path` and `new_path`; either match → `sensitive: true`.
|
||||
- **Git hardening env** for sandbox-side git (R33): a helper `fn sandbox_git_env() -> Vec<(String, String)>` returning the env pairs from Unit 3 (`GIT_TERMINAL_PROMPT=0`, `GIT_EXTERNAL_DIFF=""`, etc.) used by every sandbox-side git invocation. **No `host_git_hardening_env()` stub** — origin-read is out of scope for v1 and that placeholder was removed. If origin-read lands later, the hardening is added then against the concrete host-side code path.
|
||||
- **Logging helper** `struct RunFilesMetrics { file_count, bytes_total, duration_ms, truncated, binary_count, sensitive_count, symlink_count, submodule_count }` with an `.emit(run_id: &RunId)` method that writes a single `tracing::info!` span. Tests assert no `%s` / string-interpolation leaks paths or contents.
|
||||
- **Extend `docs-internal/logging-strategy.md`** with the new prohibited-field entries (`diff_contents`, `file_path` for changed-file paths specifically, `git_stderr`) so future endpoints inherit the rule.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-redact/src/jsonl.rs:21` — the existing redaction field skiplist, as the conceptual ancestor (but content-level, not path-level).
|
||||
- `AGENTS.md` shell-quoting rule for any shell-adjacent code.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `is_sensitive(".env.production")` → true; `is_sensitive("src/models/user.rs")` → false.
|
||||
- Edge case: path with `../` or non-UTF-8 bytes — `is_sensitive` rejects/ignores safely (does not panic; returns `false`).
|
||||
- Edge case: denylist pattern matches ancestor directory (e.g., `/workspace/.ssh/id_rsa_backup`) — matched true on `id_rsa_backup`? pin the behavior explicitly: match on exact basename globs, not ancestor segments, to keep the rule predictable; document in the helper's doc comment.
|
||||
- Integration: `RunFilesMetrics::emit` writes a tracing event with exactly the allowlisted fields; a negative assertion verifies no changed-file paths appear.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes.
|
||||
- `cargo +nightly-2026-04-14 clippy -p fabro-server --all-targets -- -D warnings` passes.
|
||||
- `docs-internal/logging-strategy.md` contains the new prohibited fields.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 9: Web — regenerate TS client + upgrade @pierre/diffs**
|
||||
|
||||
**Goal:** Regenerate the TypeScript client after the OpenAPI change and upgrade `@pierre/diffs` from 1.0.11 to 1.1.x.
|
||||
|
||||
**Requirements:** Enabling R1, R9; external dependency update.
|
||||
|
||||
**Dependencies:** Unit 1
|
||||
|
||||
**Files:**
|
||||
- Regenerated (do not hand-edit, run `cd lib/packages/fabro-api-client && bun run generate`): `lib/packages/fabro-api-client/src/models/*.ts`, `lib/packages/fabro-api-client/src/api/*.ts`, `lib/packages/fabro-api-client/src/models/index.ts`
|
||||
- Modify: `apps/fabro-web/package.json` (bump `@pierre/diffs` to `^1.1.15` — the most recent release published > 24 h before implementation time per the user-global CLAUDE.md policy against fresh packages; verify the age gate at install time and step back further if 1.1.15 is too new)
|
||||
- Modify: `apps/fabro-web/bun.lock` (run `bun install` to regenerate)
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx` (adapt to 1.1.x if there are import or manager-class renames surfaced by `tsc`)
|
||||
|
||||
**Approach:**
|
||||
- Regenerate the TS client first; fix any TypeScript errors surfaced by the regen before touching `@pierre/diffs`.
|
||||
- Install 1.1.16 per the brainstorm's Key Decision (pass 1.1.x). Reading the 1.1.0 release notes, public React components (`MultiFileDiff`, `FileDiff`, `PatchDiff`, `File`) keep the same shape; internal `MouseEventManager`/`LineSelectionManager` are merged into `InteractionManager`. We only use public React components, so breakage should be limited.
|
||||
- Do **not** touch the tab's UX yet — Units 10–12 own that. This unit is strictly: regen + library upgrade + compile clean.
|
||||
- User-level CLAUDE.md forbids installing packages under 24 hours old. 1.1.16 was published 2026-04-19 (today); check the release date at implementation time and pin to the most recent version published > 24h ago (likely 1.1.15 or earlier).
|
||||
|
||||
**Patterns to follow:**
|
||||
- AGENTS.md "API workflow" (lines 41–49).
|
||||
- `apps/fabro-web/package.json` existing version constraints for style (`^` ranges).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: run the existing `bun test` suite and `bun run typecheck` — all passes.
|
||||
- Happy path: add a minimal `@pierre/diffs` rendering smoke test (vitest + jsdom) that mounts a `MultiFileDiff` with a known 2-file fixture and a `PatchDiff` with a known patch string, asserts the components render without throwing. This gives automated regression coverage for the 1.0→1.1 migration that the original draft had as "manual QA only".
|
||||
- Integration: `bun run build` succeeds with the new library version.
|
||||
|
||||
**Verification:**
|
||||
- `cd apps/fabro-web && bun run typecheck` passes.
|
||||
- `cd apps/fabro-web && bun test` passes (existing tests).
|
||||
- `cd apps/fabro-web && bun run build` succeeds.
|
||||
- `cd lib/packages/fabro-api-client && bun run typecheck` passes.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 10: Web — rendering paths for normal + degraded + placeholder entries**
|
||||
|
||||
**Goal:** Wire the `run-files.tsx` route to consume the new response shape, branch between `MultiFileDiff` / `PatchDiff` / per-entry placeholders, and wrap in `Virtualizer` for lazy mounting.
|
||||
|
||||
**Requirements:** R1, R2, R9, R10, R11, R12, R21 (consume independent flags)
|
||||
|
||||
**Dependencies:** Unit 9
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx` (replace the current body with the new rendering tree; `fallbackFiles` already removed in Unit 7)
|
||||
- Create: `apps/fabro-web/app/routes/run-files/placeholders.tsx` (or co-located components: `BinaryPlaceholder`, `SensitivePlaceholder`, `TruncatedPlaceholder`, `DegradedBanner`)
|
||||
- Create: `apps/fabro-web/app/routes/run-files/placeholders.test.tsx` (unit tests; bun test + react testing library)
|
||||
|
||||
**Approach:**
|
||||
- Loader switches from `apiJson` to `apiJsonOrNull` — a 501 response (e.g., demo mode missing the route in a misconfigured env) resolves to `null` and flows into R4(c) empty state.
|
||||
- Component branches:
|
||||
- `data?.meta.degraded && data.meta.patch` → render `<PatchDiff patch={data.meta.patch} options={...} />` with a top-level `<DegradedBanner reason={data.meta.degraded_reason} />` above it. **Banner copy per reason:**
|
||||
- `"sandbox_gone"` → "Showing final patch only. This run's sandbox has been cleaned up; full file contents aren't available."
|
||||
- `"sandbox_unreachable"` → "Couldn't reach this run's sandbox. Showing the patch captured at the last checkpoint. Try Refresh." (Retry affordance on this banner.)
|
||||
- `"provider_unsupported"` → "Live diff isn't supported for this sandbox provider. Showing the patch captured at the last checkpoint."
|
||||
- `data?.data?.length > 0` → wrap in `<Virtualizer>` and map each entry:
|
||||
- **Placeholder priority** (highest first — a file matching multiple flags uses only the highest-priority placeholder): `sensitive > binary > symlink/submodule > truncated`. Security signals must never be hidden by a lesser flag.
|
||||
- `sensitive: true` → `<SensitivePlaceholder name={file.new_file.name} pattern={file.matched_pattern ?? "sensitive file"} />`.
|
||||
- `binary: true` → `<BinaryPlaceholder name={file.new_file.name} change={file.change_kind} />`.
|
||||
- `change_kind: "symlink"` or `"submodule"` → `<SymlinkPlaceholder>` / `<SubmodulePlaceholder>` showing the path and mode; never dereference the target.
|
||||
- `truncated: true` → `<TruncatedPlaceholder name={file.new_file.name} reason={file.truncation_reason} />`. Reason `"file_too_large"` → "File too large to render inline". Reason `"budget_exhausted"` → "Too many files changed — this file's contents were omitted (meta.files_omitted_by_budget above shows the count)."
|
||||
- Otherwise → `<MultiFileDiff oldFile={file.old_file} newFile={file.new_file} options={...} />`.
|
||||
- Otherwise → empty state (Unit 11 specifies exact messaging).
|
||||
- Persist split/unified in localStorage (R2). Respect md-breakpoint auto-collapse (override rendered style without overwriting storage per origin doc).
|
||||
- Remove the Steer-comment affordance entirely (brainstorm R3; don't ship dead UI).
|
||||
- Theme: keep `pierre-dark`/`pierre-light` per current `useTheme()` hook.
|
||||
- **Deep-link + PatchDiff**: when `meta.degraded && meta.patch`, deep-link fragments (`#file=<path>`) cannot target a file because `PatchDiff` renders one unified view. In this mode, the hash is preserved in the URL (so refresh can still resolve it once origin is reachable again) but no scroll/expand is attempted; a transient inline toast reads "File-level navigation isn't available in the patch-only view" on first load when a hash is present.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `apps/fabro-web/app/routes/run-stages.tsx` for loader + component structure.
|
||||
- `apps/fabro-web/app/api.ts:115-130` (`apiJsonOrNull`) for the 404/501-graceful loader pattern.
|
||||
- `apps/fabro-web/app/lib/theme.ts` for `useTheme`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: response with 3 normal entries → 3 `MultiFileDiff` instances rendered (mock or snapshot).
|
||||
- Happy path: response with `meta.degraded=true, meta.patch="..."` → one `PatchDiff` rendered; no `MultiFileDiff`; degraded banner visible.
|
||||
- Edge case: entry with `binary: true` → `BinaryPlaceholder` rendered; no `MultiFileDiff` for that entry.
|
||||
- Edge case: entry with `sensitive: true` → `SensitivePlaceholder` rendered; name surfaces but no hunks.
|
||||
- Edge case: entry with `truncated: true` → `TruncatedPlaceholder` rendered with file name and reason.
|
||||
- Edge case: entry with multiple flags (truncated + binary) → single placeholder renders with the higher-priority label (binary takes priority; document the ordering).
|
||||
- Integration: split/unified toggle persists across navigation (localStorage round-trip).
|
||||
- Integration: md-breakpoint collapse overrides rendered style without updating localStorage (resize event + subsequent resize back → persisted preference still honored).
|
||||
|
||||
**Verification:**
|
||||
- `cd apps/fabro-web && bun test` passes.
|
||||
- `cd apps/fabro-web && bun run typecheck` passes.
|
||||
- Manual in dev server: hit Files tab against a run with a real diff → renders via `MultiFileDiff`. Disconnect sandbox / test fixture → degraded view renders via `PatchDiff`.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 11: Web — empty-state + error-state + loading + refresh**
|
||||
|
||||
**Goal:** Implement the R4 empty-state taxonomy, R5 error-state taxonomy, initial loading skeleton, and refresh control with `to_sha`-based freshness indicator.
|
||||
|
||||
**Requirements:** R4, R5, R6
|
||||
|
||||
**Dependencies:** Unit 10
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx` (add empty/error/loading/refresh rendering)
|
||||
- Create: `apps/fabro-web/app/routes/run-files/states.tsx` (co-located `EmptyState`, `ErrorState`, `LoadingSkeleton`, `RefreshButton`, `FreshnessIndicator` components)
|
||||
- Create: `apps/fabro-web/app/routes/run-files/states.test.tsx` (unit tests)
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx` — add a route-level `ErrorBoundary` export (no nested error boundaries exist today; this is the first)
|
||||
|
||||
**Approach:**
|
||||
- **Loading**: initial fetch uses React Router's `useNavigation().state === "loading"` to show `<LoadingSkeleton>` (toolbar visible, diff area shimmer). During revalidation (`useRevalidator`), keep prior content visible.
|
||||
- **Empty states (R4)**:
|
||||
- (a) run has no `base_sha` yet (Submitted/Starting) → "Run is still starting. Files will appear once it begins."
|
||||
- (b) run produced `base_sha` but touched no files → "This run didn't change any files."
|
||||
- (c1) **Failed run without a checkpoint** → "This run failed before capturing any changes."
|
||||
- (c2) **Succeeded run with no recoverable diff** (projection write failure or `final_patch` lost) → "The diff for this run is no longer available. If you expect files here, please report it."
|
||||
- Derive the variant from `{ runStatus, data.data.length, data.meta.degraded, data.meta.patch }`. The `runStatus` comes from the parent `run-detail.tsx` loader data or a shared context. **Decision table**: `runStatus == Submitted|Starting` → R4(a). `runStatus in {Succeeded, PartialSuccess, Running} && data.length == 0 && !meta.degraded && meta.total_changed == 0` → R4(b). `runStatus == Failed && !meta.degraded` → R4(c1). `runStatus in {Succeeded, PartialSuccess} && !meta.degraded && data.length == 0` → R4(c2).
|
||||
- **Error states (R5)** — route-level `ErrorBoundary` matches on `Response.status`:
|
||||
- 4xx transient (429, 503) → retry affordance
|
||||
- 404 → treat as empty (R4(c)) — should not reach here in practice since 404 returns `null` via `apiJsonOrNull`
|
||||
- 401/403 → "You don't have access to this run's files."
|
||||
- 500 with request ID → `"Something went wrong. Request ID: <id>. Contact support."`
|
||||
- **Refresh (R6)**:
|
||||
- Toolbar Refresh button triggers `useRevalidator().revalidate()`.
|
||||
- Disabled when `lastResponse.meta.to_sha === currentlyDisplayed.to_sha` (both non-null). When `meta.to_sha === null` (rare — degraded response with no `git_commit_sha`), the button stays enabled; refresh attempts to re-query, which is the reasonable default.
|
||||
- **Freshness label source is resolved** (no longer deferred to implementation):
|
||||
- Running runs → "Checkpoint Xm ago" sourced from `meta.to_sha_committed_at` (commit time, not HTTP response time). This is the signal that matters: "nothing has changed on the agent side" vs "we just re-fetched".
|
||||
- Completed runs → "Fetched Xs ago" sourced from the HTTP response time (client-side; `Date.now()` at loader completion).
|
||||
- Degraded responses show both: "Captured Xm ago · Fetched Ys ago" so users understand the patch is old even when the refresh was recent.
|
||||
- **State transitions** (explicit):
|
||||
- Revalidation in flight: prior content stays mounted; Refresh button shows a spinner overlay; toolbar stays interactive.
|
||||
- Revalidation completes with new `to_sha`: content swaps; the "Fetched Xs ago" label resets.
|
||||
- Revalidation completes but response is now empty (file reverted): brief non-blocking toast "No changes in this run" and transition to R4(b) empty state.
|
||||
- Revalidation fails (503 transient, network, etc.): prior content stays visible; inline error banner with Retry; do **not** unmount to the route `ErrorBoundary` — that's only for initial loader failures.
|
||||
- SSE fires `CheckpointCompleted` on a Running run → after 500 ms debounce, `revalidator.revalidate()` runs. Duplicate/re-emitted events in the debounce window coalesce to one revalidation.
|
||||
- For Running runs, subscribe via SSE to `/api/v1/runs/${id}/attach?since_seq=1`, filter for the checkpoint-completed event (wire name **likely `CheckpointCompleted`**; confirm against `lib/crates/fabro-workflow/src/event.rs` during implementation and update this reference). Debounce 500 ms. Unsubscribe on unmount.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `apps/fabro-web/app/components/stage-sidebar.tsx:39-66` for SSE + `useRevalidator` debounced revalidation.
|
||||
- `apps/fabro-web/app/root.tsx:21-96` for `RootErrorBoundary` shape.
|
||||
- `apps/fabro-web/app/routes/run-stages.tsx:290` for empty-state prose style.
|
||||
- **Back-port**: add `to_sha: Option<String>` to `RunFilesMeta` in Unit 1 if not already present. Revisit Unit 1 before starting this one.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `data.data.length > 0` → `RunFiles` body renders; no empty/error state visible.
|
||||
- Edge case: `data === null` (loader returned null from 404/501) → empty state R4(c).
|
||||
- Edge case: empty `data.data` + `meta.total_changed === 0` + run status is `Running` → empty state R4(b) "run didn't change any files".
|
||||
- Edge case: empty `data.data` + run status is `Submitted` → empty state R4(a) "run starting".
|
||||
- Error path: loader throws `Response(status: 503)` → error state R5(a) with Retry button; clicking Retry re-runs the loader.
|
||||
- Error path: loader throws `Response(status: 401)` → error state R5(c).
|
||||
- Error path: loader throws `Response(status: 500)` → error state R5(d) with request ID (from response body).
|
||||
- Integration: Running run, SSE emits `CheckpointCompleted` → after 500 ms debounce, `useRevalidator().revalidate()` is called once (not twice for duplicate events).
|
||||
- Integration: Refresh button disabled state correctly tracks `meta.to_sha` unchanged.
|
||||
|
||||
**Verification:**
|
||||
- `cd apps/fabro-web && bun test` passes.
|
||||
- `cd apps/fabro-web && bun run typecheck` passes.
|
||||
- Manual: visit Files tab on Running / Succeeded / Failed runs and confirm each empty/error/loading state matches the taxonomy.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 12: Web — accessibility, responsive, deep-link**
|
||||
|
||||
**Goal:** Implement R7 (deep link) and R8 (a11y + responsive). Add j/k keyboard nav across files, md-breakpoint auto-collapse, `#file=<path>` URL fragment scroll/expand, focus management.
|
||||
|
||||
**Requirements:** R7, R8
|
||||
|
||||
**Dependencies:** Units 10, 11
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx`
|
||||
- Create: `apps/fabro-web/app/routes/run-files/keyboard.ts` (small hook encapsulating j/k + tab-order wiring)
|
||||
- Create: `apps/fabro-web/app/routes/run-files/keyboard.test.ts`
|
||||
|
||||
**Approach:**
|
||||
- **Deep link** (R7): on mount, read `window.location.hash` → if it matches `#file=<encoded-path>`, scroll the matching file into view and expand it (via `@pierre/diffs` `expandUnchanged` option or an internal "focus on this file" mechanism). If the file is truncated/binary/sensitive, scroll to the placeholder and highlight. If the file is absent, show a transient inline toast `"File <path> not in this run"` that dismisses after 5 s; preserve the hash so refresh can resolve it.
|
||||
- **Keyboard nav** (R8): `j`/`k` move focus to next/prev file row in the tab. Focus outline visible; `Enter` or `Space` expands/collapses. Do not hijack default browser scroll behavior; the hook listens on document and checks `document.activeElement` to avoid intercepting text inputs.
|
||||
- **Responsive** (R8): a `useEffect` with `window.matchMedia('(max-width: 768px)')` flips the rendered `diffStyle` to `"unified"` below the breakpoint without writing localStorage. Above the breakpoint, honor the persisted preference. Below `md`, toolbar controls (Refresh, split/unified toggle, disable-background toggle) have a minimum **44×44 px** touch-target (WCAG 2.5.5 AAA), implemented via Tailwind `min-h-[44px] min-w-[44px]`. Long diff lines scroll horizontally within the file panel, not the viewport. `prefers-reduced-motion` disables the loading skeleton's shimmer animation in favor of a static placeholder.
|
||||
- **Focus management**: after `useRevalidator` completes a refresh, focus returns to the Refresh button (or the previously-focused file if the user was mid-navigation).
|
||||
- **Tab order**: toolbar controls first, then file list, then hunks within the focused file.
|
||||
- **ARIA**: `role="region"` on each file row with `aria-label="<change_kind>: <path>"`. `@pierre/diffs` 1.1.x may render its own ARIA; audit visually and augment only where needed.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `apps/fabro-web/app/` for any existing keyboard-nav prior art. If none, this hook is the first; keep it small and testable.
|
||||
- Tailwind v4 `md:` breakpoint (`apps/fabro-web/app/app.css` or component-level classes) — document the chosen breakpoint (`768px` default) in a comment.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: URL has `#file=src%2Fmodels%2Fuser.rs` → on load, file is scrolled into view and expanded.
|
||||
- Happy path: `j`/`k` keys move focus between file rows; focus outline is visible; Enter expands/collapses.
|
||||
- Edge case: deep link target is `truncated` — scroll to the placeholder, not a diff view.
|
||||
- Edge case: deep link target is not in `data` — transient toast visible, URL hash preserved.
|
||||
- Edge case: `j` pressed while a textarea is focused — key is ignored.
|
||||
- Edge case: viewport resizes below md — `diffStyle` flips to `"unified"`; resize back → persisted preference restored.
|
||||
- Integration: after refresh via Refresh button, focus returns to Refresh button (accessible via `document.activeElement`).
|
||||
|
||||
**Verification:**
|
||||
- `cd apps/fabro-web && bun test` passes.
|
||||
- `cd apps/fabro-web && bun run typecheck` passes.
|
||||
- Manual: keyboard-only navigation through the tab works; screen-reader announcement is sane (test in VoiceOver or similar); responsive works at 320 / 768 / 1280 viewport widths.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 13: Surface tab + final verification**
|
||||
|
||||
**Goal:** Unhide the Files tab in navigation and run end-to-end verification across all run lifecycle states.
|
||||
|
||||
**Requirements:** All R# (final integration check)
|
||||
|
||||
**Dependencies:** Units 1–12
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.tsx` (remove `broken: true` from the Files Changed tab entry at line 14)
|
||||
|
||||
**Approach:**
|
||||
- Single-line flag flip. The route has been registered all along; this just makes it visible.
|
||||
- Verification script: create a real run locally, monitor Files tab across states (Submitted → Starting → Running → Succeeded/Failed), and also Failed post-sandbox (wait for teardown or manually destroy sandbox).
|
||||
|
||||
**Patterns to follow:**
|
||||
- Nothing new; the deletion is surgical.
|
||||
|
||||
**Test scenarios:**
|
||||
- Test expectation: none — this unit is a one-line enable + manual E2E verification; behavior coverage lives in Units 10–12 and the server integration tests.
|
||||
|
||||
**Verification:**
|
||||
- Manual E2E:
|
||||
- Submitted run → R4(a) empty state.
|
||||
- Running run → real diff via `MultiFileDiff`; Refresh updates after a checkpoint.
|
||||
- Succeeded run whose sandbox is still alive → real diff.
|
||||
- Succeeded run whose sandbox is gone → degraded view via `PatchDiff`.
|
||||
- Failed run with active sandbox → real diff.
|
||||
- Failed run whose sandbox is gone, lifecycle hook ran → degraded view (tests Unit 2 in the real world).
|
||||
- Failed run whose sandbox is gone, lifecycle hook didn't run (simulate crash) → R4(c) empty state.
|
||||
- Demo mode (`X-Fabro-Demo: 1` via cookie) → fixture response.
|
||||
- `cd apps/fabro-web && bun run build && cd ../.. && cargo build --workspace` both green.
|
||||
- `cargo nextest run --workspace` green.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** The new handler calls into `state.store` (SlateDB), `reconnect_run_sandbox`, the new `sandbox_git::diff_inspector` helpers, and the new `CoalescingRegistry`. It does **not** touch `state.runs`, `artifact_store`, or any lifecycle machinery — strictly additive on the server side.
|
||||
- **Error propagation:** 400/404 from `parse_run_id_path` and `load_run_record`. 503 from sandbox subprocess timeouts. 500 with request ID from anything else. Reconnect failure → internal fallback (not 409) because we have `final_patch` as a second path.
|
||||
- **State lifecycle risks:** None for the endpoint itself — it's read-only. Unit 2 adds one new lifecycle write (capture `final_patch` on Failed) which is idempotent (set-only, `Option<String>`).
|
||||
- **API surface parity:** TS client is regenerated; downstream consumers of the generated types get the new fields for free. `PaginationMeta` (shared) is untouched; `PaginatedRunFileList.meta` now uses the new `RunFilesMeta` type — this is a name change at the spec level that could surface as a TS type alias update in any place that imports `PaginatedRunFileList['meta']`. Grep for such usages during Unit 1.
|
||||
- **Integration coverage:** Concurrent viewers on the same run, lifecycle hook firing mid-HTTP-request, SSE revalidation triggering mid-render, and md-breakpoint resize during active keyboard nav — all exercised in the tests above.
|
||||
- **Unchanged invariants:**
|
||||
- `RunProjection.final_patch`'s semantics for Success/PartialSuccess are preserved; Failed adds a new population path without changing existing consumers (PR body generation).
|
||||
- `sandbox_git::git_diff` keeps its current 30 s timeout and `pub(crate)` visibility — PR and checkpoint callers are unaffected.
|
||||
- `PaginationMeta` stays as-is; no other endpoint changes.
|
||||
- `Dockerfile` / deployment topology unchanged.
|
||||
- `RunFailed` event keeps its existing fields and gains `final_patch: Option<String>` additively; existing event consumers compile unchanged because the field is optional.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Progenitor/openapi-generator regen produces a large diff that reviewers can't audit | Call out in the PR description; reviewers inspect hand-edited spec + handler; regenerated client is verified by `bun run typecheck` + `cargo build` |
|
||||
| 1.0 → 1.1 `@pierre/diffs` upgrade breaks internal manager usage | Public React components are stable per release notes; we only use public components. Manual visual QA in Unit 13 catches regressions. If blocked, pin to 1.0.11 and accept the no-virtualization limit |
|
||||
| Docker runs 409 on reconnect (Docker feature isn't compiled into fabro-server) | Acceptable per origin doc: Docker runs' Files tab falls through to `final_patch` path. Document in user-facing error: "Live diff unavailable for this sandbox provider." |
|
||||
| The coalescing registry leaks memory on panic (future dropped without removal) | Use `Weak` references in the map so orphaned entries clear on next lookup; tests verify |
|
||||
| `--find-renames=50%` threshold misses renames users expect | Documented in the origin doc as the pinned threshold. Future tuning via config is straightforward |
|
||||
| `final_patch` capture on Failed increases run-end latency | The hook already runs for Success/PartialSuccess; Failed is symmetric. Timeout is already bounded at 30 s and failure is logged as warn, not fatal |
|
||||
| `RunFilesMeta` replacing `PaginationMeta` on this endpoint confuses TS consumers | TS client is regenerated; typechecker catches usages. Grep during Unit 1 surfaces any explicit uses of `PaginatedRunFileList['meta']` |
|
||||
| Denylist misses a sensitive filename convention (e.g., `kubeconfig`, `terraform.tfvars`) | Accepted residual risk per brainstorm R31 reframe. Follow-up: config-driven denylist |
|
||||
| The brief disabled Refresh window after `to_sha` unchanged confuses users on long stages | UX decision in origin R6; disabled button conveys "no new checkpoint yet". Revisit if support reports surface |
|
||||
| Reintroducing the endpoint confuses reviewers who remember it being deleted | Prior-art note in PR description + "Prior art" reference in this plan |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- **API docs**: `docs/api-reference/fabro-api.yaml` is edited in Unit 1; documentation changes flow through automatically via Mintlify docs.
|
||||
- **Logging policy**: `docs-internal/logging-strategy.md` gains `diff_contents`, `file_path` (for this endpoint's changed-file paths), `git_stderr` to the prohibited-fields list (Unit 8).
|
||||
- **Changelog**: add an entry under `docs/changelog/` after merge describing the Files tab ship.
|
||||
- **Rollout**:
|
||||
- Unit 2 (lifecycle `final_patch` on Failed) is backward-compatible with in-flight runs; new Failed runs will start populating the field, old Failed runs stay at `None` (empty state on Files tab for them).
|
||||
- The endpoint is new and unauthenticated calls are rejected. No feature flag needed for gradual rollout; the tab was never visible before.
|
||||
- **Monitoring**: tracing spans from Unit 8 produce stable field names (`run_id`, `file_count`, `bytes_total`, `duration_ms`, `truncated`, `binary_count`, `sensitive_count`) that can be indexed by Sentry/Datadog.
|
||||
|
||||
## Phased Delivery
|
||||
|
||||
The units are dependency-ordered and can land as one bundle or a 3-phase sequence:
|
||||
|
||||
- **Phase 1 — Spec + lifecycle + sandbox helpers** (Units 1, 2, 3, 4): foundation; no user-visible change yet.
|
||||
- **Phase 2 — Real + fallback + demo handler** (Units 5, 6, 7, 8): endpoint works via `curl`; tab is still hidden.
|
||||
- **Phase 3 — Web UX + tab surfacing** (Units 9, 10, 11, 12, 13): feature becomes visible.
|
||||
|
||||
Single-PR is fine given the unit count and scope; phased PRs make sense if CI cycles are long or the team wants staged review.
|
||||
|
||||
## Dependencies Graph
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U1[Unit 1: OpenAPI spec] --> U5[Unit 5: real handler]
|
||||
U1 --> U6[Unit 6: fallback branch]
|
||||
U1 --> U7[Unit 7: demo handler]
|
||||
U1 --> U9[Unit 9: TS regen + pierre upgrade]
|
||||
U2[Unit 2: Failed run lifecycle] --> U6
|
||||
U3[Unit 3: sandbox git helpers] --> U5
|
||||
U4[Unit 4: coalescing registry] --> U5
|
||||
U5 --> U6
|
||||
U5 --> U8[Unit 8: security & observability]
|
||||
U6 --> U8
|
||||
U9 --> U10[Unit 10: rendering paths]
|
||||
U10 --> U11[Unit 11: states + refresh]
|
||||
U10 --> U12[Unit 12: a11y + deep link]
|
||||
U11 --> U13[Unit 13: surface tab + E2E]
|
||||
U12 --> U13
|
||||
U8 --> U13
|
||||
U7 --> U13
|
||||
```
|
||||
|
|
@ -1,548 +0,0 @@
|
|||
---
|
||||
title: "feat: Expose CLI lifecycle actions (cancel, archive, unarchive) in the web UI"
|
||||
type: feat
|
||||
status: completed
|
||||
date: 2026-04-19
|
||||
updated: 2026-04-20
|
||||
origin: docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md
|
||||
---
|
||||
|
||||
# feat: Expose CLI lifecycle actions (cancel, archive, unarchive) in the web UI
|
||||
|
||||
## Overview
|
||||
|
||||
Today the Fabro web UI at `apps/fabro-web` is essentially read-only for run management: only Preview mutates state. This plan adds three lifecycle actions to the run detail page (`/runs/{id}`): **cancel**, **archive**, and **unarchive**.
|
||||
|
||||
The plan also closes three supporting gaps the requirements and review surfaced:
|
||||
|
||||
- a shared action-capable toast system
|
||||
- a run-detail SSE subscription so action visibility updates live
|
||||
- two missing event strings in the board revalidation allowlist
|
||||
|
||||
As of **April 20, 2026**, product explicitly chose to remove the deferred cancel timer and undo window from the earlier requirements doc. In this plan, cancel fires immediately.
|
||||
|
||||
Pause/unpause and delete remain out of scope (see origin: `docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md`).
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Two user pains from the origin document drive this work:
|
||||
|
||||
1. **Daily friction for CLI users** who live in the web UI but must context-switch to a terminal to cancel, archive, or unarchive runs.
|
||||
2. **Exclusion of non-CLI teammates** (PMs, reviewers, stakeholders) who can observe runs but cannot participate in managing them.
|
||||
|
||||
The server endpoints already exist. The remaining work is UI surface, route wiring, SSE reconciliation, and user-facing error handling.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
All IDs reference the origin document, but this plan is the source of truth for implementation. The origin document's deferred-cancel requirements were superseded on **April 20, 2026** when product chose immediate cancel with no undo window.
|
||||
|
||||
- **R1** Expose cancel, archive, and unarchive on the run detail page.
|
||||
- **R2** Do not expose pause, unpause, or delete in this pass.
|
||||
- **R3** Do not expose checkpoint operations (resume, rewind, fork) or HITL question answering in this pass.
|
||||
- **R4** Do not expose these actions on board kanban cards or as bulk selection in this pass.
|
||||
- **R5** State-aware visibility:
|
||||
cancel visible for `submitted|runnable|starting|running|paused` as the primary affordance; archive for terminal non-archived runs; unarchive for archived runs.
|
||||
- **R6** Blocked runs hide the primary cancel button and instead show an inline notice with question text plus CLI guidance. Cancel remains reachable through a de-emphasized secondary affordance inside that notice.
|
||||
- **R7** The detail page subscribes to the run's SSE stream so affordances update live without a manual refresh.
|
||||
- **R8** Cancel fires immediately. There is no client-side pending timer, no undo window, and no pre-fire `GET /runs/{id}` recheck in this plan.
|
||||
- **R9** Archive and unarchive fire immediately and surface an inverse-action toast ("Run archived. Unarchive").
|
||||
- **R10** While a lifecycle action request is in flight, only the submitting control disables/spins. There is no cross-action disable window because there is no pending cancel timer.
|
||||
- **R11** There is no optimistic local archived/unarchived flip. All three actions reconcile through the action response, normal route revalidation, and SSE for later lifecycle transitions.
|
||||
- **R12** On 404/409/network failures, show a user-facing mapped error toast and revalidate so the page reconciles to actual server state. Because there is no optimistic local state, there is no rollback layer.
|
||||
- **R13** Multi-tab behavior has no per-client timers. SSE still reconciles non-terminal state transitions across tabs. **Known limitation:** if tab A is showing an already-terminal run and tab B archives/unarchives it, tab A may stay stale because the per-run `/attach` stream has already closed on `RunCompleted`/`RunFailed`. Users recover on navigation/refresh or on a failed action attempt surfaced through the 409/error toast path.
|
||||
- **R14** Accessibility:
|
||||
toasts use `role="status"` and `aria-live="polite"`, do not steal focus, action buttons are keyboard-operable and touch-friendly, and the blocked-run secondary cancel affordance expands to a 48x48 CSS px touch target on coarse pointers. Countdown-specific pause/resume behavior is no longer part of scope.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Actions exposed: cancel, archive, unarchive. Nothing else.
|
||||
- Surface: run detail page (`/runs/{id}`) only. Not the board, not bulk.
|
||||
- Not exposed: pause, unpause, delete, force-delete, resume/rewind/fork, HITL answering.
|
||||
- No OpenAPI changes.
|
||||
- No new server event types.
|
||||
- No changes to authorization (single-tenant trusted deployment assumption).
|
||||
- No phone-size responsive layout work; tablet and up only.
|
||||
- No keyboard shortcuts for individual actions.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- **Board SSE + revalidation allowlist:** `apps/fabro-web/app/routes/runs.tsx` (`BOARD_STATUS_EVENTS` at lines 63-79). `run.archived` and `run.unarchived` are missing. Test pattern in `apps/fabro-web/app/routes/runs.test.tsx`.
|
||||
- **Existing per-run SSE subscriptions:** `apps/fabro-web/app/routes/run-files.tsx` and `apps/fabro-web/app/components/stage-sidebar.tsx`. Both parse `msg.data` JSON and gate on `payload.event`; they do **not** use `EventSource` message type names.
|
||||
- **Run detail page header and Preview button:** `apps/fabro-web/app/routes/run-detail.tsx`. The route already uses React Router `useFetcher` plus a route `action` for Preview, so lifecycle actions can follow the same pattern instead of introducing a second mutation model.
|
||||
- **Run detail loader shape:** the loader receives raw API `summary.status` and maps it onto `run.lifecycleStatus` in loader data. UI visibility logic in this plan keys off `run.lifecycleStatus`; loader-only branching is described explicitly as checking `summary.status` before mapping.
|
||||
- **Existing toast primitive:** `apps/fabro-web/app/routes/run-files/states.tsx` has a simple read-only live-region toast. It is a useful visual/a11y baseline but is not reusable for stacked toasts with action buttons.
|
||||
- **UI primitives:** `apps/fabro-web/app/components/ui.tsx` exports `PRIMARY_BUTTON_CLASS` and `SECONDARY_BUTTON_CLASS`. No generic `<Button>` or app-level toast system exists today.
|
||||
- **API helpers:** `apps/fabro-web/app/api.ts` exports both `apiJson` and `apiFetch`. `apiJson` discards the response body on non-2xx. That is incompatible with lifecycle actions because these flows need the server error envelope for 404/409 handling. Lifecycle mutation helpers in this plan therefore use `apiFetch` and parse the body manually.
|
||||
- **Status taxonomy:** `apps/fabro-web/app/data/runs.ts` exports `RunStatus`, `runStatusDisplay`, and `mapRunSummaryToRunItem`. Use those status strings rather than open-coding new ones.
|
||||
- **Blocked question data:** `GET /api/v1/runs/{id}/questions` returns a `PaginatedApiQuestionList` in `docs/api-reference/fabro-api.yaml`. This plan intentionally shows the **first** pending question's `text` when the run is blocked; the blocked notice is informational only and does not attempt multi-question navigation or answering.
|
||||
- **Server cancel semantics:** for `submitted`/`runnable`, cancel may synchronously return a terminal failed/cancelled state; for `starting`/`running`/`blocked`/`paused`, the response may keep the same lifecycle status and the eventual transition lands later via SSE.
|
||||
- **Per-run `/attach` stream limitations:** the stream closes on terminal run events and has a few other silent-termination paths. This plan accepts the existing already-terminal stale-tab limitation for archive/unarchive instead of changing the server subscription contract.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
None. `docs/solutions/` is not seeded in this repo. Capture learnings from this work with `/ce:compound` after implementation.
|
||||
|
||||
### External References
|
||||
|
||||
Not needed. Local patterns cover React Router actions, SSE subscriptions, and route-level data loading.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Immediate cancel, no undo.** Product explicitly removed the deferred timer on April 20, 2026. Cancel now behaves like a normal immediate mutation with passive feedback.
|
||||
- **One mutation pattern for all three lifecycle actions.** Cancel, archive, and unarchive all use React Router `useFetcher` plus the `run-detail.tsx` route `action`, extending the existing Preview route-action pattern with an `intent` dispatch instead of mixing `fetcher` and direct click-handler fetches.
|
||||
- **Lifecycle mutation helpers use `apiFetch`, not `apiJson`.** These flows need access to the error response body for 404/409 mapping. `run-actions.ts` owns that parsing and returns or throws typed shapes the route action can consume.
|
||||
- **Archive/unarchive are not optimistic.** The UI shows normal in-flight disabled state during submission, then relies on action completion + route revalidation to reflect the archived state. This is simpler and matches current app patterns.
|
||||
- **Shared app-shell toast provider is still the right shape.** With the cancel undo window removed, the earlier focus-order and route-lifetime problems disappear. The provider only needs to support passive toasts and inverse-action toasts.
|
||||
- **The new shared SSE hook is for code reuse, not socket deduplication.** `useRunEventSource` standardizes payload parsing, allowlist gating, debounce behavior, and cleanup across call sites. It still opens one `EventSource` per caller; the plan no longer claims otherwise.
|
||||
- **Blocked-run question text is loaded by the run-detail route, not by a component-local fetch.** When the loader sees raw API `summary.status === "blocked"` before mapping that value to `run.lifecycleStatus`, it fetches the first pending question and returns `blockedQuestionText` alongside the run summary. `blocked-run-notice.tsx` stays presentational.
|
||||
- **Blocked-run secondary cancel is an inline text affordance, not an overflow menu.** This satisfies the product intent of a de-emphasized escape hatch while avoiding unnecessary menu infrastructure.
|
||||
- **Post-terminal archive/unarchive reconciliation stays response-driven.** The plan does not reconnect `/attach` after terminal closure. Success responses and normal route revalidation handle the local tab; the known already-terminal stale-tab limitation is explicitly accepted.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Cancel interaction model:** immediate-fire, no undo, per April 20, 2026 product decision.
|
||||
- **Mutation transport:** all lifecycle actions use `useFetcher` plus route `action` dispatch in `run-detail.tsx`.
|
||||
- **Error-body parsing:** use `apiFetch` inside `run-actions.ts`; do not use `apiJson` for lifecycle mutations.
|
||||
- **Blocked question source:** fetch the first pending question in the run-detail loader when raw API `summary.status` is `blocked` before it is mapped to `run.lifecycleStatus`.
|
||||
- **Blocked cancel affordance shape:** inline muted text link inside the blocked notice rather than a menu.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- Exact toast z-index and portal strategy if stacking interacts with the legacy toast in `run-files/states.tsx`.
|
||||
- Exact user-facing copy for each mapped 4xx/409 condition. Minimum set:
|
||||
cancel-409, archive-409, unarchive-409, 404, and generic network failure.
|
||||
- Exact visual treatment of the archive/unarchive inverse-action toast when the user clicks the toast action immediately after the first mutation settles.
|
||||
- Whether unarchive success uses a symmetric inverse-action toast (`Archive`) or a short passive "Run restored." toast.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> This section is directional guidance for implementation and review, not code to copy verbatim.
|
||||
|
||||
### Module layout (new + modified, repo-relative)
|
||||
|
||||
```text
|
||||
apps/fabro-web/app/
|
||||
├── components/
|
||||
│ ├── toast.tsx NEW Toast, ToastProvider, useToast, ToastRoot
|
||||
│ └── blocked-run-notice.tsx NEW Presentational blocked notice
|
||||
├── lib/
|
||||
│ ├── sse.ts NEW useRunEventSource(runId, { allowlist, debounceMs, onEvent? })
|
||||
│ └── run-actions.ts NEW cancel/archive/unarchive request helpers, status predicates, error mapping
|
||||
├── layouts/
|
||||
│ └── app-shell.tsx MOD Mount ToastProvider once
|
||||
└── routes/
|
||||
├── run-detail.tsx MOD Loader adds blockedQuestionText; action dispatches lifecycle intents; UI renders actions and toast integration
|
||||
├── run-detail.test.tsx NEW or extend if created during implementation
|
||||
├── runs.tsx MOD Extend BOARD_STATUS_EVENTS
|
||||
└── runs.test.tsx MOD Add allowlist cases
|
||||
```
|
||||
|
||||
### Immediate cancel flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant UI as Cancel Button
|
||||
participant Action as Route action
|
||||
participant API as POST /cancel
|
||||
participant Toast
|
||||
participant SSE as useRunEventSource
|
||||
|
||||
User->>UI: click Cancel
|
||||
UI->>Action: submit intent=cancel
|
||||
Action->>API: POST /runs/{id}/cancel
|
||||
alt 200 with terminal failed/cancelled state
|
||||
API-->>Action: RunStatusResponse
|
||||
Action-->>UI: { ok: true, run }
|
||||
UI->>Toast: "Run cancelled."
|
||||
else 200 with unchanged in-progress state
|
||||
API-->>Action: RunStatusResponse
|
||||
Action-->>UI: { ok: true, run }
|
||||
UI->>Toast: "Cancellation requested."
|
||||
SSE-->>UI: later run.failed / equivalent transition
|
||||
else 404 / 409 / network failure
|
||||
API-->>Action: ErrorResponse
|
||||
Action-->>UI: { ok: false, error }
|
||||
UI->>Toast: mapped error copy
|
||||
end
|
||||
```
|
||||
|
||||
### Archive / unarchive inverse-action flow
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant User
|
||||
participant UI as Archive Button
|
||||
participant Action as Route action
|
||||
participant API as POST /archive
|
||||
participant Toast
|
||||
|
||||
User->>UI: click Archive
|
||||
UI->>Action: submit intent=archive
|
||||
Action->>API: POST /runs/{id}/archive
|
||||
alt 200
|
||||
API-->>Action: RunStatusResponse
|
||||
Action-->>UI: { ok: true, run }
|
||||
UI->>Toast: "Run archived." + Unarchive action
|
||||
opt user clicks Unarchive in toast
|
||||
User->>UI: click Unarchive toast action
|
||||
UI->>Action: submit intent=unarchive
|
||||
end
|
||||
else 404 / 409 / network failure
|
||||
API-->>Action: ErrorResponse
|
||||
Action-->>UI: { ok: false, error }
|
||||
UI->>Toast: mapped error copy
|
||||
end
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
U1[Unit 1: Board allowlist additions]
|
||||
U2[Unit 2: Shared toast infrastructure]
|
||||
U3[Unit 3: Shared SSE hook and migration]
|
||||
U4[Unit 4: Lifecycle action helpers and route action dispatch]
|
||||
U5[Unit 5: Immediate cancel UI]
|
||||
U6[Unit 6: Archive/unarchive UI]
|
||||
U7[Unit 7: Blocked-run notice]
|
||||
|
||||
U2 --> U5
|
||||
U2 --> U6
|
||||
U3 --> U5
|
||||
U3 --> U6
|
||||
U3 --> U7
|
||||
U4 --> U5
|
||||
U4 --> U6
|
||||
U4 --> U7
|
||||
U5 --> U7
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 1: Extend `BOARD_STATUS_EVENTS` with `run.archived` and `run.unarchived`**
|
||||
|
||||
**Goal:** Ensure the board revalidates when a run is archived or unarchived from any source.
|
||||
|
||||
**Requirements:** R7, R13.
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/runs.tsx`
|
||||
- Modify: `apps/fabro-web/app/routes/runs.test.tsx`
|
||||
|
||||
**Approach:**
|
||||
- Add `run.archived` and `run.unarchived` to `BOARD_STATUS_EVENTS`.
|
||||
- Leave debounce/revalidator wiring unchanged.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing allowlist structure in `apps/fabro-web/app/routes/runs.tsx`
|
||||
- Existing allowlist tests in `apps/fabro-web/app/routes/runs.test.tsx`
|
||||
|
||||
**Test scenarios:**
|
||||
- `shouldRefreshBoardForEvent("run.archived")` returns `true`.
|
||||
- `shouldRefreshBoardForEvent("run.unarchived")` returns `true`.
|
||||
- `shouldRefreshBoardForEvent("run.created")` remains `false`.
|
||||
|
||||
**Verification:**
|
||||
- `runs.test.tsx` passes.
|
||||
- Manual: archive a terminal run from outside the board and confirm `/runs` updates without a manual refresh.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2: Shared toast infrastructure (`ToastProvider`, `useToast`)**
|
||||
|
||||
**Goal:** Introduce a stackable app-level toast system for passive toasts, error toasts, and inverse-action toasts.
|
||||
|
||||
**Requirements:** R9, R12, R14.
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/fabro-web/app/components/toast.tsx`
|
||||
- Create: `apps/fabro-web/app/components/toast.test.tsx`
|
||||
- Modify: `apps/fabro-web/app/layouts/app-shell.tsx`
|
||||
|
||||
**Approach:**
|
||||
- Export `ToastProvider`, `useToast()`, and a provider-owned root container.
|
||||
- `useToast()` exposes `push`, `dismiss`, and `clear`.
|
||||
- Supported toast shapes:
|
||||
passive info toast, error toast, and action toast with a single button.
|
||||
- Root renders a stacked bottom-right container with `role="status"` and `aria-live="polite"`.
|
||||
- Do not steal focus on mount.
|
||||
- Error toasts are sticky until dismissed.
|
||||
- Non-error toasts may auto-dismiss with a short TTL.
|
||||
- Action buttons meet the minimum touch target via padding or explicit size classes.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing `Toast` live-region semantics in `apps/fabro-web/app/routes/run-files/states.tsx`
|
||||
|
||||
**Test scenarios:**
|
||||
- `push({ message })` renders a toast with the message.
|
||||
- `push({ action: { label, onClick } })` renders an actionable button and fires `onClick`.
|
||||
- Error toasts do not auto-dismiss.
|
||||
- Multiple toasts stack in insertion order.
|
||||
- `dismiss()` removes a toast and leaves the rest reflowed.
|
||||
- The provider mounted in `app-shell.tsx` is accessible from descendant route components.
|
||||
|
||||
**Verification:**
|
||||
- `toast.test.tsx` passes.
|
||||
- `bun run typecheck` passes.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 3: Shared SSE hook (`useRunEventSource`) and migration of existing call sites**
|
||||
|
||||
**Goal:** Standardize run-scoped SSE parsing and revalidation behavior across the app.
|
||||
|
||||
**Requirements:** R7, R13.
|
||||
|
||||
**Dependencies:** None runtime; Units 5 and 6 consume this.
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/fabro-web/app/lib/sse.ts`
|
||||
- Create: `apps/fabro-web/app/lib/sse.test.ts`
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.tsx`
|
||||
- Modify: `apps/fabro-web/app/routes/run-files.tsx`
|
||||
- Modify: `apps/fabro-web/app/components/stage-sidebar.tsx`
|
||||
|
||||
**Approach:**
|
||||
- Export `useRunEventSource(runId, { allowlist, debounceMs = 300, onEvent? })`.
|
||||
- Internally:
|
||||
open `/api/v1/runs/${runId}/attach?since_seq=1`, parse `msg.data`, read `payload.event`, and gate both `revalidator.revalidate()` and `onEvent(payload)` on the allowlist.
|
||||
- Cleanup closes the `EventSource` and pending debounce timer.
|
||||
- The plan intentionally describes this as code reuse and behavior standardization, not socket deduplication.
|
||||
- `run-detail.tsx` should subscribe to the lifecycle events that can change button visibility for the current run.
|
||||
- `run-files.tsx` and `stage-sidebar.tsx` keep their current event sets and debounce timing.
|
||||
- `run-detail.tsx` is the subscriber that makes the blocked notice in Unit 7 disappear when the run leaves `blocked`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing SSE shapes in `apps/fabro-web/app/routes/run-files.tsx`
|
||||
- Existing SSE shapes in `apps/fabro-web/app/components/stage-sidebar.tsx`
|
||||
|
||||
**Test scenarios:**
|
||||
- Allowlisted `payload.event` triggers debounced revalidation.
|
||||
- Non-allowlisted events are ignored.
|
||||
- `onEvent` receives the parsed payload for allowlisted events.
|
||||
- Unmount closes the source and clears any timer.
|
||||
- The migrated `run-files.tsx` still refreshes for `checkpoint.completed`.
|
||||
- The migrated `stage-sidebar.tsx` still refreshes for stage events.
|
||||
|
||||
**Verification:**
|
||||
- `sse.test.ts` passes.
|
||||
- Existing `run-files` and `stage-sidebar` tests continue to pass.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 4: Lifecycle action helpers and route action dispatch**
|
||||
|
||||
**Goal:** Centralize request handling, error parsing, and status predicates for cancel/archive/unarchive.
|
||||
|
||||
**Requirements:** R5, R8, R9, R11, R12.
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/fabro-web/app/lib/run-actions.ts`
|
||||
- Create: `apps/fabro-web/app/lib/run-actions.test.ts`
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.tsx`
|
||||
|
||||
**Approach:**
|
||||
- `run-actions.ts` owns:
|
||||
`cancelRun(id, request)`, `archiveRun(id, request)`, `unarchiveRun(id, request)`,
|
||||
`mapError(error, action)`,
|
||||
and `canCancel`, `canArchive`, `canUnarchive`.
|
||||
- These helpers use `apiFetch`, not `apiJson`, so the error body is still available on 404/409.
|
||||
- Introduce a small typed error shape such as:
|
||||
`{ status: number; errors: ErrorResponseEntry[] }`.
|
||||
- If the error body is absent or non-JSON (for example, a proxy HTML error page), parse fallback should return `{ status, errors: [] }` so `mapError` can fall back to generic copy instead of throwing.
|
||||
- Extend the route `action` in `run-detail.tsx` to dispatch on `intent=preview|cancel|archive|unarchive`.
|
||||
- Because Preview is no longer the implicit default path, add a hidden `intent=preview` input to the existing Preview form so the dispatch routes it explicitly.
|
||||
- Return a typed action result payload for lifecycle submissions so the component can toast on settle.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing `useFetcher` + route `action` pattern already used for Preview in `run-detail.tsx`
|
||||
|
||||
**Test scenarios:**
|
||||
- `cancelRun`, `archiveRun`, and `unarchiveRun` parse 200 responses correctly.
|
||||
- 404 and 409 responses preserve the parsed error envelope.
|
||||
- Non-JSON error bodies fall back to `{ status, errors: [] }` rather than throwing during parsing.
|
||||
- `mapError` returns user-facing copy for cancel/archive/unarchive conflict states.
|
||||
- Status predicates use lifecycle status strings from `data/runs.ts`, not a new local taxonomy.
|
||||
- The route `action` dispatches correctly for each lifecycle `intent`.
|
||||
- Preview still submits through the same route action via `intent=preview`; cover that regression in `run-detail.test.tsx`.
|
||||
|
||||
**Verification:**
|
||||
- `run-actions.test.ts` passes.
|
||||
- `bun run typecheck` passes.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 5: Immediate cancel UI**
|
||||
|
||||
**Goal:** Add the cancel button to the run detail header using the same route-action/fetcher pattern as the other lifecycle actions.
|
||||
|
||||
**Requirements:** R5, R8, R10, R11, R12.
|
||||
|
||||
**Dependencies:** Units 2, 3, and 4.
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.tsx`
|
||||
- Modify/Create: `apps/fabro-web/app/routes/run-detail.test.tsx`
|
||||
|
||||
**Approach:**
|
||||
- Render cancel when `canCancel(run.lifecycleStatus)` is true and the run is not blocked.
|
||||
- Use `cancelFetcher.Form` with `intent=cancel`.
|
||||
- Disable only the cancel control while its submission is in flight.
|
||||
- On successful settle:
|
||||
if the returned run is already terminal failed/cancelled, show a passive "Run cancelled." toast;
|
||||
otherwise show "Cancellation requested." and rely on SSE + normal revalidation for the final flip.
|
||||
- On 404/409/network failure, show `mapError(error, "cancel")` in an error toast.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Preview button layout and fetcher pattern in `apps/fabro-web/app/routes/run-detail.tsx`
|
||||
- `SECONDARY_BUTTON_CLASS` from `apps/fabro-web/app/components/ui.tsx`
|
||||
|
||||
**Test scenarios:**
|
||||
- Cancel renders for `submitted`, `runnable`, `starting`, `running`, and `paused`.
|
||||
- Cancel is hidden for `blocked`, `succeeded`, `failed`, `dead`, and `archived`.
|
||||
- Submitting cancel sends `intent=cancel` through the route action.
|
||||
- While the cancel submission is pending, only that button disables.
|
||||
- A terminal success response shows "Run cancelled."
|
||||
- An async success response shows "Cancellation requested."
|
||||
- 404/409 responses show the mapped error toast.
|
||||
|
||||
**Verification:**
|
||||
- `run-detail.test.tsx` passes with cancel cases.
|
||||
- Manual: cancel a long-running run from `/runs/{id}` and confirm the toast and later lifecycle update behavior.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 6: Archive / unarchive UI**
|
||||
|
||||
**Goal:** Add archive and unarchive controls plus the inverse-action toast flow.
|
||||
|
||||
**Requirements:** R5, R9, R10, R11, R12.
|
||||
|
||||
**Dependencies:** Units 2, 3, and 4.
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.tsx`
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.test.tsx`
|
||||
|
||||
**Approach:**
|
||||
- Render archive when `canArchive(run.lifecycleStatus)` is true.
|
||||
- Render unarchive when `canUnarchive(run.lifecycleStatus)` is true.
|
||||
- Use dedicated fetchers or one intent-aware fetcher for both actions.
|
||||
- No optimistic local state; rely on standard submission state and route revalidation.
|
||||
- On archive success, push an action toast with `Unarchive`.
|
||||
- The toast action should capture the route-scoped fetcher submission at push time, e.g. `onClick: () => unarchiveFetcher.submit(...)`, rather than trying to host a route `<Form>` inside the app-shell toast tree.
|
||||
- On unarchive success, show the success-toast variant chosen in Deferred to Implementation below.
|
||||
- On 404/409/network failure, show the mapped error toast.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Same route-action/fetcher pattern as Unit 5
|
||||
|
||||
**Test scenarios:**
|
||||
- Archive renders only for terminal non-archived runs.
|
||||
- Unarchive renders only for archived runs.
|
||||
- Submitting archive/unarchive dispatches the correct `intent`.
|
||||
- Buttons disable while their own submission is pending.
|
||||
- Archive success shows "Run archived." with an Unarchive action.
|
||||
- Clicking the toast's Unarchive action submits the unarchive flow.
|
||||
- 404/409 failures show mapped error toasts.
|
||||
|
||||
**Verification:**
|
||||
- `run-detail.test.tsx` passes with archive/unarchive cases.
|
||||
- Manual: archive a terminal run from the detail page, then restore it from the toast action.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 7: Blocked-run notice + secondary cancel affordance**
|
||||
|
||||
**Goal:** Show non-CLI users why the run is blocked without presenting cancel as the main action.
|
||||
|
||||
**Requirements:** R6, R14.
|
||||
|
||||
**Dependencies:** Units 3, 4, and 5.
|
||||
|
||||
**Files:**
|
||||
- Create: `apps/fabro-web/app/components/blocked-run-notice.tsx`
|
||||
- Create: `apps/fabro-web/app/components/blocked-run-notice.test.tsx`
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.tsx`
|
||||
- Modify: `apps/fabro-web/app/routes/run-detail.test.tsx`
|
||||
|
||||
**Approach:**
|
||||
- In the run-detail loader:
|
||||
when raw API `summary.status === "blocked"` before it is mapped to `run.lifecycleStatus`, fetch the first pending question from `/api/v1/runs/{id}/questions?page[limit]=1&page[offset]=0` and return `blockedQuestionText`.
|
||||
- `blocked-run-notice.tsx` is presentational: it renders the question text when available, otherwise fallback copy, plus the muted "Cancel run anyway." secondary control.
|
||||
- The secondary control reuses the same cancel submission path as Unit 5.
|
||||
- The control uses the coarse-pointer hit-area expansion pattern from R14.
|
||||
- Loader-branch tests for `blockedQuestionText` live in `run-detail.test.tsx`; `blocked-run-notice.test.tsx` stays focused on presentational behavior.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Visual banner treatment inspired by `InlineErrorBanner` in `apps/fabro-web/app/routes/run-files/states.tsx`
|
||||
|
||||
**Test scenarios:**
|
||||
- Blocked runs render the question text when the loader returns it.
|
||||
- Blocked runs render fallback copy when no question is available.
|
||||
- Blocked runs do not show the primary cancel button.
|
||||
- Clicking "Cancel run anyway." submits the same cancel path as Unit 5.
|
||||
- The notice disappears when the lifecycle status is no longer blocked after revalidation/SSE.
|
||||
|
||||
**Verification:**
|
||||
- `blocked-run-notice.test.tsx` passes.
|
||||
- Manual: open a blocked run, verify the question text and secondary cancel affordance.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction model:** lifecycle actions now share one route-action/fetcher model instead of mixing fetcher submissions and direct handler fetches.
|
||||
- **Error propagation:** lifecycle mutation helpers preserve and parse server error bodies via `apiFetch`.
|
||||
- **State reconciliation:** immediate action responses, normal route revalidation, and live SSE updates remain the only state sources. There is no local optimistic layer and no client-side pending cancel timer.
|
||||
- **Known limitation retained:** archive/unarchive on already-terminal runs can leave another open tab stale until refresh because `/attach` has already closed. This plan documents the limitation rather than changing the server contract.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Toast provider overlaps the legacy fixed-position toast in `run-files/states.tsx`. | Start with simple stacking and adjust z-index or migrate the older toast later if visual overlap proves real. |
|
||||
| The shared SSE refactor is over-read as socket deduplication work. | The plan states explicitly that Unit 3 is code reuse and behavior standardization only. |
|
||||
| Error mapping drifts from server copy. | Keep the mapped strings in one place in `run-actions.ts`; only use server detail text as a fallback for unexpected cases. |
|
||||
| Blocked runs may have multiple pending questions. | The plan intentionally shows only the first question because this surface is informational, not an answering workflow. |
|
||||
| `scripts/refresh-fabro-spa.sh` is forgotten before commit. | Call it out in implementation and PR notes whenever `apps/fabro-web` changes ship. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- **PR description** should call out:
|
||||
scope = cancel/archive/unarchive only;
|
||||
immediate cancel with no undo;
|
||||
new `ToastProvider`;
|
||||
new run-detail SSE subscription;
|
||||
`scripts/refresh-fabro-spa.sh` was run.
|
||||
- **Accessibility audit before merge:**
|
||||
1. Tab through the detail-page action row and confirm cancel/archive/unarchive are keyboard-operable.
|
||||
2. Trigger cancel and confirm the passive toast appears without stealing focus.
|
||||
3. Trigger archive and confirm the inverse-action toast button is reachable by keyboard and touch-friendly.
|
||||
4. Open a blocked run and confirm the secondary "Cancel run anyway." affordance meets the coarse-pointer hit-area requirement.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin document:** [docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md](docs/brainstorms/2026-04-19-web-ui-lifecycle-actions-requirements.md)
|
||||
- Key repo files:
|
||||
`apps/fabro-web/app/routes/run-detail.tsx`,
|
||||
`apps/fabro-web/app/routes/runs.tsx`,
|
||||
`apps/fabro-web/app/routes/run-files.tsx`,
|
||||
`apps/fabro-web/app/components/stage-sidebar.tsx`,
|
||||
`apps/fabro-web/app/routes/run-files/states.tsx`,
|
||||
`apps/fabro-web/app/api.ts`,
|
||||
`apps/fabro-web/app/components/ui.tsx`,
|
||||
`apps/fabro-web/app/layouts/app-shell.tsx`
|
||||
- API spec:
|
||||
`docs/api-reference/fabro-api.yaml`
|
||||
- Related plan:
|
||||
`docs/plans/2026-04-19-001-feat-archived-run-status-plan.md`
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,123 +0,0 @@
|
|||
---
|
||||
title: "refactor: Clean up Home vs Storage path ownership"
|
||||
type: refactor
|
||||
status: active
|
||||
date: 2026-04-19
|
||||
---
|
||||
|
||||
# refactor: Clean up Home vs Storage path ownership
|
||||
|
||||
## Overview
|
||||
|
||||
Today the server lifecycle code records the server log as `<storage>/logs/server.log`, but tracing for serving processes still writes under `Home::logs_dir()`. Operators tailing the recorded server log miss server traces, and deployments that rely on durable `Storage` do not actually keep the server's tracing output there. This plan fixes that ownership bug, keeps CLI logs in `Home`, deletes dead legacy config/env compatibility code, and removes `Home::storage_dir()` so storage-placement policy lives in config/user resolution instead of the `Home` abstraction.
|
||||
|
||||
This is an aggressive greenfield cleanup. No compatibility shims, deprecation window, migration warnings, or release-note work are included for old config files, old `~/.fabro/.env`, or old `~/.fabro/server.json`.
|
||||
|
||||
## Key Changes
|
||||
|
||||
### Logging ownership
|
||||
|
||||
- Keep the existing server-state accessor and make its exact path the canonical server log destination:
|
||||
- `Storage::server_state().log_path()` already exists and resolves to `<storage>/logs/server.log`
|
||||
- Replace the current logging setup with an explicit internal sink type:
|
||||
- CLI sink: daily rolling logs under `Home::logs_dir()`
|
||||
- Server sink: fixed file at `<storage>/logs/server.log`
|
||||
- Drive sink selection from parsed command variants, not `command_name` string matching
|
||||
- Resolve the sink before tracing init:
|
||||
- `server __serve`, `server start --foreground`, and `server restart --foreground` use the server sink
|
||||
- `server start` / `server restart` daemon wrappers, `server stop`, `server status`, and all other commands use the CLI sink
|
||||
- Extend the pre-tracing bootstrap path in `main.rs` so server-specific config/log resolution covers `ServerCommand::Restart` when `foreground` is set, not just `Start` and `Serve`
|
||||
- Move enough settings/storage resolution ahead of `logging::init_tracing()` to choose the sink for serving processes; if that early resolution fails, return the error from `main_inner()` and let the existing fatal stderr formatter in `main()` render it without initializing tracing
|
||||
- The pre-tracing bootstrap for serve/foreground paths must call `user_config::load_settings_with_config_and_storage_dir(config, storage_dir)` and then `user_config::storage_dir(&settings)` so the `--storage-dir` CLI override is honored when picking the server sink
|
||||
- If storage resolution fails before tracing init, keep that failure on the same `main_inner() -> main()` stderr-only fatal path; do not attempt a fallback server sink without a resolved storage root
|
||||
- Keep the server log policy unchanged aside from ownership:
|
||||
- single file at `<storage>/logs/server.log`
|
||||
- truncated once on each server start/restart
|
||||
- no append+rotation/retention work in this pass
|
||||
- Make the file-open semantics explicit with one truncation owner per mode:
|
||||
- foreground-serving modes own their in-process bootstrap: after acquiring `<storage>/server.lock` and confirming no active server, the foreground process ensures the parent directory exists, creates/truncates `<storage>/logs/server.log` once, and then attaches the append-mode server sink
|
||||
- daemonized start/restart keeps bootstrap ownership in the daemon parent: after acquiring `<storage>/server.lock` and confirming no active server, the parent ensures the parent directory exists, creates/truncates `<storage>/logs/server.log` once, opens the redirected stdout/stderr handles against that file before spawn, and then launches `server __serve`
|
||||
- the `server __serve` child never truncates `<storage>/logs/server.log`; it only appends once tracing initializes
|
||||
- serving-process tracing always appends to `<storage>/logs/server.log` and never performs a second truncate
|
||||
- Boundary of the durable server log:
|
||||
- `<storage>/logs/server.log` becomes authoritative only after storage root resolution succeeds and the relevant serving bootstrap has created/opened the file
|
||||
- failures earlier in bootstrap, including config/settings resolution failures and lock-acquire/lock-timeout failures, remain stderr-only in this pass
|
||||
- Clap parse errors, `--help`, `--version`, and other failures that happen before command classification remain stderr/bootstrap-owned and are out of scope for the server-log ownership fix
|
||||
- Pre-existing `Home/logs/server*.log` files are accepted historical orphans; this pass does not add a one-time sweep
|
||||
- Keep `ServerRecord.log_path` pointed at `<storage>/logs/server.log`
|
||||
|
||||
### Remove dead Home and legacy path APIs
|
||||
|
||||
- Delete `Home::server_config()`, `Home::certs_dir()`, and `Home::storage_dir()`
|
||||
- Remove `fabro_config::legacy_env` entirely
|
||||
- Remove legacy config filename support entirely from `fabro_config::user`:
|
||||
- delete the old filename constants and path helpers
|
||||
- delete legacy warning state and warning logic
|
||||
- make `load_settings_config()` load only the explicit path, `FABRO_CONFIG`, or the default `settings.toml`
|
||||
- Remove CLI warning/reporting code for legacy `~/.fabro/.env` and old config filenames from `install`, `provider login`, and `doctor`
|
||||
- Remove the legacy server record fallback to `~/.fabro/server.json`; only `<storage>/server.json` remains valid
|
||||
- Make the aggressive compatibility cut explicit:
|
||||
- `server status` / `server stop` only inspect `<storage>/server.json`
|
||||
- no compatibility fallback or migration shim is added for daemons that wrote only `~/.fabro/server.json`
|
||||
- add a narrow fail-fast detector in every server lifecycle site that previously consulted `active_server_record_details` — not only `server status` and `server stop`, but also `server start`, `server restart`, `ensure_server_running_with_bind`, and the daemon/foreground execute paths — so that if `<storage>/server.json` is absent but the legacy `~/.fabro/server.json` path exists for a process that satisfies the existing `server_record_is_running()` liveness predicate (`fabro_proc::process_alive(pid)` plus `server_process_matches(record)`), the command aborts with an explicit manual-cleanup error instead of silently treating the server as stopped or spawning a duplicate
|
||||
- if the legacy record path exists but does not satisfy that existing liveness predicate, treat it as stale legacy state and continue cleanup/removal rather than aborting
|
||||
- the fail-fast error should name the legacy record path and current storage record path and tell the operator to stop the old daemon with a legacy CLI or manually clear the stale daemon before retrying
|
||||
- upgrading over a still-running legacy daemon remains unsupported; the detector is only there to fail loudly
|
||||
- Do not add new `Home` accessors for one-off singleton files like `.id` or `last_upgrade_check.json`; keep those joins local to their owning modules instead of replacing one dead abstraction with new speculative ones
|
||||
- Delete the `check_legacy_env` helper in `doctor.rs` and its two unit tests, and drop the `use fabro_config::legacy_env;` imports in `doctor.rs`, `install.rs`, and `provider/login.rs` so the crate removal leaves no orphaned references
|
||||
|
||||
### Move default storage policy out of Home
|
||||
|
||||
- Add a canonical `fabro_config::user::default_storage_dir()` helper that returns the preserved external default `~/.fabro/storage`
|
||||
- Remove `legacy_default_storage_root()` instead of renaming it in place
|
||||
- Use `default_storage_dir()` anywhere code currently assumes storage lives under `Home`, including:
|
||||
- server settings default storage root
|
||||
- workflow/run scratch fallback helpers
|
||||
- doctor/install/default-record lookup code
|
||||
- uninstall fallback when settings load fails
|
||||
- After this change, the `Home` struct no longer owns or exposes storage placement; the default storage policy remains home-derived, but it lives in config/user resolution instead of the `Home` API
|
||||
- Keep `Home` as user-scoped local state keyed by `FABRO_HOME`; telemetry identity and upgrade-check state remain home-scoped and intentionally vary when `FABRO_HOME` varies
|
||||
- Callers that currently do `legacy_default_storage_root().join("storage")` (e.g. `install.rs`, `server/record.rs`) must drop the trailing `.join("storage")` when switching to `default_storage_dir()`, since the new helper already resolves to `~/.fabro/storage`
|
||||
|
||||
### Clean up Storage/Home registry drift
|
||||
|
||||
- Add and use a distinct `Storage::slatedb_cache_dir()` accessor for `<storage>/cache/slatedb`
|
||||
- Keep the existing `Storage::slatedb_dir()` meaning unchanged as `<storage>/objects/slatedb`
|
||||
- Update the SlateDB cache wiring to use `Storage::slatedb_cache_dir()` instead of joining `cache/slatedb` inline
|
||||
- Keep dead paths dead: do not add new accessors for removed legacy env/config files
|
||||
|
||||
## Test Plan
|
||||
|
||||
- Update `Home` tests to reflect the trimmed API
|
||||
- Add unit coverage for log-sink resolution so these cases are explicit:
|
||||
- normal CLI command -> home rolling log
|
||||
- `server start --foreground` -> storage server log
|
||||
- `server restart --foreground` -> storage server log
|
||||
- `server __serve` -> storage server log
|
||||
- daemon wrapper commands -> CLI/home log
|
||||
- Add unit coverage for the pre-tracing bootstrap classification so a restart with `foreground == true` (`ServerCommand::Restart(ServerRestartArgs { foreground: true, .. })`) is handled like the corresponding start-foreground and `Serve` variants
|
||||
- Add or adjust server-start integration tests to verify:
|
||||
- the actual server log file is `<storage>/logs/server.log`
|
||||
- server tracing output lands there
|
||||
- no server rolling log is created under `Home/logs`
|
||||
- Update daemon/foreground server-start tests to verify the truncate-on-start + append-during-runtime semantics for `<storage>/logs/server.log`
|
||||
- Add a concurrency test for serving startup so a second concurrent foreground/serve start fails before any second truncate of `<storage>/logs/server.log`
|
||||
- Update config/user tests so old `cli.toml`, `user.toml`, and `server.toml` are neither loaded nor warned about
|
||||
- Update doctor/install/provider-login tests to remove legacy env/config warning expectations
|
||||
- Update server-record tests and `server_start` fixtures so only `<storage>/server.json` is canonical, and add coverage for the new fail-fast legacy-daemon detector
|
||||
- Update any workflow/run fallback tests that currently rely on `Home::storage_dir()`
|
||||
- Update docs/help/fixture expectations that still mention legacy filenames, legacy `.env`, or home-root server record paths
|
||||
|
||||
## Assumptions
|
||||
|
||||
- Greenfield cleanup: no compatibility fallback, migration shim, warning path, changelog work, or announcement work is retained for old config files, old `~/.fabro/.env`, or old `~/.fabro/server.json`
|
||||
- The external default storage location remains `~/.fabro/storage`; only the abstraction boundary changes
|
||||
- Unix socket location remains under `Home`
|
||||
- Dev token remains the intentional shared-machine exception: the home-level token remains the shared local-machine source, and `<storage>/server.dev-token` remains only the storage-owned mirror of that same token
|
||||
- Home remains user-scoped local CLI state keyed by `FABRO_HOME`
|
||||
- Temporary or test-only `FABRO_HOME` values continue to produce throwaway home-scoped telemetry ID / upgrade-check state; this pass does not special-case test homes
|
||||
- Storage-root server state files remain exactly:
|
||||
- `<storage>/server.json`
|
||||
- `<storage>/server.lock`
|
||||
- `<storage>/server.env`
|
||||
- `<storage>/server.dev-token` as the mirrored copy described above, not a second canonical source
|
||||
|
|
@ -1,53 +0,0 @@
|
|||
# Remove Inbound TLS Termination From `fabro-server`
|
||||
|
||||
## Summary
|
||||
|
||||
- Remove all server-side TLS termination from `fabro-server` so Fabro only listens on plain TCP or Unix sockets.
|
||||
- Make reverse proxy / load balancer TLS termination the only supported deployment model for HTTPS.
|
||||
- Treat this as a deliberate breaking config change: `[server.listen.tls]` is removed, not retained behind a compatibility layer.
|
||||
|
||||
## Public Interface Changes
|
||||
|
||||
- Simplify server listen settings to `Tcp { address }` or `Unix { path }`; remove the `tls` field from both sparse and resolved server settings.
|
||||
- Delete the inbound-listener TLS types from `fabro-types` and stop re-exporting them.
|
||||
- Remove `server.listen.tls` resolution from `fabro-config`.
|
||||
- Existing configs that still set `[server.listen.tls]` should fail during settings parsing via the current unknown-field behavior; do not add a migration shim.
|
||||
- Update published docs/examples so HTTPS is described as proxy-terminated, with public HTTPS URLs still expressed through `[server.api].url` and `[server.web].url`.
|
||||
|
||||
## Implementation Changes
|
||||
|
||||
- Server runtime:
|
||||
- Delete the Rustls listener module and remove the TLS branch from startup.
|
||||
- Keep the plain TCP and Unix socket serve paths intact.
|
||||
- Preserve `ConnectInfo` and IP allowlist behavior for non-TLS TCP serving.
|
||||
- Remove inbound-TLS-only dependencies from `fabro-server`.
|
||||
- Diagnostics and settings views:
|
||||
- Delete server listener cert/key diagnostics.
|
||||
- Keep redacting `server.listen` from settings APIs, since bind addresses are still treated as host topology.
|
||||
- Update the redaction comments/tests so they no longer reference TLS cert/key paths.
|
||||
- Tests and fixtures:
|
||||
- Delete the Linux-only inbound TLS integration module and its fixture directory.
|
||||
- Replace config-resolution tests that currently validate `server.listen.tls.cert/key` with tests asserting the removed `tls` field is rejected.
|
||||
- Update settings/runs API tests to remove TLS fixture blocks while keeping the `server.listen` redaction assertions.
|
||||
- Docs:
|
||||
- Update active docs that currently advertise `[server.listen.tls]`.
|
||||
- Leave archival brainstorm/plan docs unchanged.
|
||||
|
||||
## Test Plan
|
||||
|
||||
- `cargo build --workspace`
|
||||
- `cargo nextest run -p fabro-config`
|
||||
- `cargo nextest run -p fabro-server`
|
||||
- `cargo +nightly-2026-04-14 fmt --check --all`
|
||||
- `cargo +nightly-2026-04-14 clippy -p fabro-config -p fabro-server --all-targets -- -D warnings`
|
||||
- Cover these scenarios in tests:
|
||||
- TCP and Unix listener configs still parse, resolve, and serve correctly.
|
||||
- Configs containing `[server.listen.tls]` now fail with an unknown-field style parse error.
|
||||
- Settings API responses still redact `server.listen`.
|
||||
|
||||
## Assumptions
|
||||
|
||||
- Outbound/client TLS in `fabro-cli` remains unchanged.
|
||||
- Hook/integration TLS settings remain unchanged.
|
||||
- Proxy-aware behavior such as `X-Forwarded-Proto` handling remains in place.
|
||||
- No automatic migration or deprecation layer will be added for old listener TLS configs.
|
||||
|
|
@ -1,389 +0,0 @@
|
|||
---
|
||||
title: "fix: Remove lingering CLI/server same-host assumptions"
|
||||
type: fix
|
||||
status: completed
|
||||
date: 2026-04-20
|
||||
---
|
||||
|
||||
# fix: Remove lingering CLI/server same-host assumptions
|
||||
|
||||
## Overview
|
||||
|
||||
Tighten the CLI/server contract so an explicit `http(s)://...` target is always treated as a remote server, never as a disguised local daemon. This removes the remaining places where the CLI still derives remote behavior from local storage, local dev-token files, or colocated-network assumptions left over from the earlier same-host architecture.
|
||||
|
||||
Historical note (2026-04-21): the auth flow now also assumes a single origin. `fabro auth login` opens the browser flow on the resolved HTTP(S) target directly; the old `/api/v1/auth/cli/config` preflight no longer exists.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The codebase already moved most commands to a server-target model, but a few central helpers still collapse explicit remote targets back into local-machine state:
|
||||
|
||||
- explicit HTTP targets can inherit local dev-token files or active local server records
|
||||
- OAuth refresh failure can downgrade a remote session into local dev-token auth
|
||||
- remote auth flows still force direct-network behavior in production instead of respecting normal HTTP proxy policy
|
||||
- `fabro exec --server ...` bypasses the authenticated client stack entirely
|
||||
- explicit remote commands still eagerly resolve local server storage settings before they connect
|
||||
|
||||
Those behaviors were survivable when the CLI and server were assumed to live on the same machine. They become contract violations now that users can run the CLI on one host and talk to a server deployed elsewhere behind a TLS-terminating proxy.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Explicit `http(s)://...` targets never inherit authentication from local storage, local server records, or `~/.fabro/dev-token`.
|
||||
- R2. Local implicit dev-token conveniences remain available only on genuinely local transports and storage-owning flows.
|
||||
- R3. Remote OAuth refresh failure never downgrades a session into local dev-token auth; the CLI either refreshes successfully or returns a session-expired outcome.
|
||||
- R4. Production browser auth, refresh, and logout flows for remote HTTP targets respect normal HTTP transport policy instead of forcing direct no-proxy behavior.
|
||||
- R5. `fabro exec --server ...` uses the same authenticated remote-server contract as other explicit server-targeted commands.
|
||||
- R6. Explicit remote server commands do not require unrelated local server storage settings to resolve successfully.
|
||||
- R7. Tests and docs stop asserting the old colocated behavior and instead lock down the explicit target contract.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- In scope:
|
||||
- shared CLI connection/auth plumbing in `fabro-cli`
|
||||
- remote auth login/logout/refresh transport behavior
|
||||
- remote `exec` auth behavior
|
||||
- command, scenario, and crate-level regression coverage
|
||||
- user-facing contract notes where current docs or help still imply colocated behavior
|
||||
- Out of scope:
|
||||
- reintroducing mTLS
|
||||
- moving TLS termination back into `fabro server`
|
||||
- redesigning server auth methods
|
||||
- changing local server lifecycle commands (`fabro server start|stop|status`) away from storage ownership
|
||||
- making `fabro exec` server-owned
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-cli/src/command_context.rs` already distinguishes `ServerTargetArgs` (`for_target`) from `ServerConnectionArgs` (`for_connection`), which is the right contract boundary to preserve.
|
||||
- `lib/crates/fabro-cli/src/server_client.rs` is the central seam for target resolution, bearer selection, auto-start, refresh, and raw HTTP access. Most user-visible contract fixes can land here once.
|
||||
- `lib/crates/fabro-cli/src/commands/exec.rs` is a separate path that currently constructs a raw `FabroServerAdapter` directly instead of reusing the authenticated client stack.
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/ps.rs` currently encodes the old colocated assumption with `ps_accepts_local_tcp_server_target`.
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/exec.rs` already proves routing precedence for `exec`, but does not prove remote auth behavior.
|
||||
- `lib/crates/fabro-cli/tests/it/scenario/auth.rs` and `tests/it/support/auth_harness.rs` provide the existing black-box auth harness for real login/refresh/logout flows.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
- No `docs/solutions/` directory exists in this repository, so there are no institutional learnings to carry forward from that source.
|
||||
- `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`
|
||||
|
||||
### External References
|
||||
|
||||
- None. The repo already has enough local context and prior planning history to ground this cleanup.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- Explicit `http(s)://...` targets are always treated as remote by contract.
|
||||
- Rationale: once the user names a network URL, the CLI should stop inferring local identity from the machine it is running on.
|
||||
- Explicit loopback HTTP does not get a special local-auth exception.
|
||||
- Rationale: that convenience adds edge cases around port-forwards, tunnels, and local proxies without improving the core remote/local contract.
|
||||
- Implicit dev-token lookup stays only on local transports and storage-owned flows.
|
||||
- Rationale: Unix sockets and daemon auto-start are machine-local by design; explicit HTTP targets are not.
|
||||
- Remote OAuth refresh failure should degrade to “session expired,” not to local dev-token auth.
|
||||
- Rationale: remote identity should remain bound to the explicit target and the auth store entry for that target.
|
||||
- `fabro exec` stays CLI-owned, but its server-routed `/completions` transport must become auth-aware.
|
||||
- Rationale: this preserves the design established in [2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md](./2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md) while removing the last unauthenticated remote path.
|
||||
- Remote HTTP auth helpers should respect normal HTTP proxy policy.
|
||||
- Rationale: users now deploy Fabro behind TLS-terminating proxies; forcing `.no_proxy()` for every production HTTP auth call is another leftover same-host assumption.
|
||||
- Test-only HTTP helpers should continue forcing `no_proxy` or equivalent disabled-proxy policy.
|
||||
- Rationale: macOS proxy detection adds measurable overhead in the test suite, and the repo already treats test-only no-proxy clients as an intentional performance and determinism pattern.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- Should explicit loopback HTTP retain special local dev-token auto-auth?
|
||||
- No. Explicit URL means remote-by-contract, even if the host text looks local.
|
||||
- Should this plan revisit mTLS or in-process TLS termination?
|
||||
- No. Those are intentionally out of contract now.
|
||||
- Should `fabro exec` become server-owned as part of this cleanup?
|
||||
- No. Keep the agent session local and only fix the remote completions transport.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- Whether the smallest `exec` fix is:
|
||||
- a CLI-local authenticated completions adapter backed by `ServerStoreClient`, or
|
||||
- a small extension to the existing Fabro server provider surface.
|
||||
- The implementation should choose the smaller option that preserves bearer refresh semantics without pushing CLI auth concerns into unrelated layers.
|
||||
- Whether any doc changes beyond CLI help/reference pages are necessary.
|
||||
- Decide after diffing current user-facing docs for explicit `--server` and CLI auth guidance.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
### Target Contract Matrix
|
||||
|
||||
| Invocation shape | May consult local storage or active server record? | Allowed implicit credentials | Auto-start? | Proxy handling |
|
||||
|---|---|---|---|---|
|
||||
| Storage-owning local flow (`for_connection`, `connect_api_client_bundle`) | Yes | local dev token from env/storage/home | Yes, for local daemon flows | local transport may use `no_proxy` |
|
||||
| Explicit Unix socket target | No storage lookup for target resolution | env dev token, auth-store OAuth entry, local Unix-socket dev-token convenience | No new storage-driven target fallback | `no_proxy` |
|
||||
| Explicit HTTP(S) target | No | env dev token and auth-store OAuth entry for that exact target only | Never | production respects normal HTTP proxy policy; tests may force `no_proxy` |
|
||||
|
||||
### Unit Dependency Graph
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U1["Unit 1<br/>Separate target-only and local-runtime-backed connection paths"]
|
||||
U2["Unit 2<br/>Narrow implicit credential sources and refresh fallback"]
|
||||
U3["Unit 3<br/>Make browser auth and refresh remote-safe"]
|
||||
U4["Unit 4<br/>Bring exec onto the authenticated remote contract"]
|
||||
U5["Unit 5<br/>Realign tests and docs around the new contract"]
|
||||
|
||||
U1 --> U2
|
||||
U2 --> U3
|
||||
U2 --> U4
|
||||
U3 --> U5
|
||||
U4 --> U5
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Separate target-only and local-runtime-backed connection paths**
|
||||
|
||||
**Goal:** Preserve the architectural distinction between “I have a server target” and “I have a local storage-backed runtime context” all the way down into shared connection setup.
|
||||
|
||||
**Requirements:** R1, R2, R6
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/command_context.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/user_config.rs`
|
||||
- Test: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/ps.rs`
|
||||
|
||||
**Approach:**
|
||||
- Stop `connect_server_with_settings(...)` from always resolving `user_config::storage_dir(settings)` up front.
|
||||
- Keep local storage resolution only on the `ServerConnectionArgs` / storage-owning path.
|
||||
- Make the `ServerTargetArgs` path target-only:
|
||||
- resolve the `ServerTarget`
|
||||
- connect to it
|
||||
- avoid deriving remote behavior from local server runtime settings
|
||||
- Preserve the existing local daemon auto-start and local TCP helper behavior only on the storage-owned local path.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `CommandContext::for_target(...)` vs `CommandContext::for_connection(...)` in `lib/crates/fabro-cli/src/command_context.rs`
|
||||
- prior separation direction in [2026-04-06-cli-config-socket-storage-separation-plan.md](./2026-04-06-cli-config-socket-storage-separation-plan.md)
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path — an explicit remote `--server https://...` command succeeds or reaches the remote server even when local server storage settings are invalid or unresolved.
|
||||
- Edge case — an explicit Unix socket target still resolves and connects without requiring a storage-dir override.
|
||||
- Error path — an unreachable explicit HTTP target fails with a reachability/auth error, not a local settings or storage-resolution error.
|
||||
- Integration — `fabro ps --server http://...` no longer succeeds solely because the CLI also knows about a local storage dir.
|
||||
|
||||
**Verification:**
|
||||
- Explicit target-only commands can connect or fail based on the target alone; they no longer fail because unrelated local server storage settings are broken.
|
||||
|
||||
- [x] **Unit 2: Narrow implicit credential sources and refresh fallback**
|
||||
|
||||
**Goal:** Make bearer selection and refresh behavior respect the explicit remote/local target contract.
|
||||
|
||||
**Requirements:** R1, R2, R3
|
||||
|
||||
**Dependencies:** Unit 1
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Test: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/ps.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
|
||||
**Approach:**
|
||||
- Split bearer resolution by target class instead of one shared fallback chain:
|
||||
- explicit HTTP(S): only explicit env `FABRO_DEV_TOKEN` and stored OAuth entry for that exact target
|
||||
- local Unix socket / storage-owned local flow: keep local dev-token conveniences
|
||||
- Remove local dev-token fallback from the refresh rebuild path for explicit HTTP targets.
|
||||
- Remove the “remote target can fall back to `~/.fabro/dev-token`” behavior from `connect_server_target_direct(...)`.
|
||||
- Replace the current `ps_accepts_local_tcp_server_target` expectation with a deliberate contract:
|
||||
- explicit HTTP target requires explicit credentials, or
|
||||
- the test should use the normal local command path instead of `--server http://...`.
|
||||
|
||||
**Execution note:** Start with failing crate-level tests for explicit HTTP bearer selection and a failing regression around the current `ps_accepts_local_tcp_server_target` assumption before changing the shared fallback chain.
|
||||
|
||||
**Patterns to follow:**
|
||||
- existing `ResolvedBearer` / `RefreshableOAuth` structure in `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- black-box auth flow style in `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path — an explicit HTTP target with a stored OAuth session still attaches the correct bearer token and succeeds.
|
||||
- Edge case — an explicit HTTP target with only local dev-token files present sends no implicit bearer token and receives an auth-required failure.
|
||||
- Error path — when a remote refresh token is expired or revoked, the CLI clears the auth-store entry and reports session expiry without downgrading to local dev-token auth.
|
||||
- Integration — the normal local server flow still works through the local-storage/Unix-socket path after the shared fallback chain is narrowed.
|
||||
|
||||
**Verification:**
|
||||
- An explicit HTTP target can no longer authenticate solely because the same machine has a local dev-token file or active local server record.
|
||||
|
||||
- [x] **Unit 3: Make browser auth and refresh remote-safe**
|
||||
|
||||
**Goal:** Remove lingering direct-network assumptions from production CLI auth transport while preserving the existing token-safety guardrails and keeping test-only no-proxy behavior.
|
||||
|
||||
**Requirements:** R3, R4
|
||||
|
||||
**Dependencies:** Unit 2
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/login.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/logout.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Test: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
|
||||
**Approach:**
|
||||
- Remove unconditional `.no_proxy()` from HTTP auth helpers used by:
|
||||
- `GET /api/v1/auth/cli/config`
|
||||
- `POST /auth/cli/token`
|
||||
- `POST /auth/cli/refresh`
|
||||
- `POST /auth/cli/logout`
|
||||
- Keep Unix-socket auth helpers as explicitly local and `no_proxy`.
|
||||
- Keep test-only builders, harnesses, and fixtures on explicit `no_proxy` or disabled-proxy policy so the test suite does not pay macOS proxy-discovery overhead.
|
||||
- Preserve the existing sensitive-credential transport guard:
|
||||
- token and refresh submission still require HTTPS, loopback HTTP, or Unix socket transport
|
||||
- plaintext non-loopback HTTP remains rejected
|
||||
- Keep target normalization and browser URL generation unchanged except where needed to stop treating generic HTTP as colocated/local.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `is_loopback_or_unix_socket(...)` in `lib/crates/fabro-cli/src/loopback_target.rs`
|
||||
- existing auth scenario harness in `lib/crates/fabro-cli/tests/it/support/auth_harness.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path — HTTPS remote login, refresh, and logout continue to work end-to-end.
|
||||
- Edge case — loopback HTTP auth still succeeds for local CLI OAuth flows.
|
||||
- Error path — non-loopback plaintext HTTP refresh or token exchange is rejected before credentials are sent.
|
||||
- Integration — with normal production proxy policy enabled for a remote HTTP(S) auth target, the CLI auth flow uses the proxy-aware HTTP builder rather than forcing direct `no_proxy` behavior.
|
||||
|
||||
**Verification:**
|
||||
- Remote HTTP auth behavior is shaped only by target safety rules and normal HTTP client policy, not by same-host shortcuts.
|
||||
|
||||
- [x] **Unit 4: Bring `fabro exec --server` onto the authenticated remote contract**
|
||||
|
||||
**Goal:** Make server-routed `exec` completions use the same auth and refresh semantics as the rest of the explicit remote CLI surface.
|
||||
|
||||
**Requirements:** R3, R5
|
||||
|
||||
**Dependencies:** Unit 2
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/exec.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
|
||||
**Approach:**
|
||||
- Keep `fabro exec` local and CLI-owned.
|
||||
- Stop constructing a bare remote `FabroServerAdapter` from `user_config::build_server_client(...)`.
|
||||
- Reuse the authenticated CLI server client contract for `/api/v1/completions`:
|
||||
- either by adding a small CLI-local authenticated completions adapter backed by `ServerStoreClient`
|
||||
- or by extending the existing completions transport in the smallest way that preserves bearer refresh semantics
|
||||
- Preserve the existing command precedence contract:
|
||||
- explicit `--server` reroutes `exec`
|
||||
- configured server target alone still does not reroute `exec`
|
||||
|
||||
**Execution note:** Start with a failing remote-auth `exec` contract test so the auth integration shape is locked down before refactoring the provider transport.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `ServerStoreClient::send_http(...)` and refresh flow in `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- server `/completions` auth requirement in `lib/crates/fabro-server/src/server.rs`
|
||||
- existing routing-precedence tests in `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path — `fabro exec --server https://...` with valid stored CLI auth reaches `/api/v1/completions` without requiring a local provider API key.
|
||||
- Edge case — configured server target alone still does not reroute `exec`.
|
||||
- Error path — expired access token during remote exec completion refreshes once and retries, or surfaces the same session-expired outcome used by other remote commands when refresh is no longer possible.
|
||||
- Integration — login to a real authenticated server, then run `fabro exec --server ...` successfully against `/api/v1/completions`.
|
||||
|
||||
**Verification:**
|
||||
- The `exec` remote path no longer bypasses CLI auth state or raw bearer selection logic.
|
||||
|
||||
- [x] **Unit 5: Realign tests and docs around the new contract**
|
||||
|
||||
**Goal:** Remove stale colocated assumptions from black-box coverage and user-facing contract text.
|
||||
|
||||
**Requirements:** R7
|
||||
|
||||
**Dependencies:** Units 1-4
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/cmd/ps.rs`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/support/auth_harness.rs`
|
||||
- Modify: `docs/reference/cli.mdx`
|
||||
- Modify: `docs/reference/user-configuration.mdx`
|
||||
|
||||
**Approach:**
|
||||
- Update black-box tests so explicit HTTP targets are treated as remote-by-contract.
|
||||
- Keep low-level credential selection checks close to `server_client.rs`; do not simulate internal runtime files in CLI integration tests.
|
||||
- Add one regression proving an explicit remote command still works when local storage config is broken.
|
||||
- Add one remote-auth `exec` regression so the new authenticated completions path stays covered.
|
||||
- Update docs/help copy anywhere it still implies that explicit `--server` may inherit local daemon identity or local dev-token convenience.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `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:**
|
||||
- Happy path — documented explicit remote auth flow matches the CLI’s actual behavior after login.
|
||||
- Edge case — explicit HTTP target with a local daemon running on the same machine is still treated as remote unless the user provides explicit credentials.
|
||||
- Error path — a broken or missing local storage config no longer breaks explicit remote commands.
|
||||
- Integration — the end-to-end auth harness covers login -> remote command -> refresh -> logout with the tightened explicit-target contract, and `exec --server` has equivalent authenticated coverage.
|
||||
|
||||
**Verification:**
|
||||
- No command test, scenario test, or reference doc still depends on “explicit HTTP target inherits local server identity.”
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** `CommandContext` -> `ServerStoreClient` -> `AuthStore` / local dev-token lookup -> generated API client and raw `/completions` transport. Fixing this seam affects every command using `for_target(...)`, plus the separate `exec` transport path.
|
||||
- **Error propagation:** explicit remote commands should fail as remote commands:
|
||||
- reachability errors stay reachability errors
|
||||
- auth failures stay auth failures
|
||||
- expired sessions stay session-expired failures
|
||||
- they should not turn into local settings-resolution failures or hidden local-auth success
|
||||
- **State lifecycle risks:** auth-store removal on refresh failure must remain targeted to the remote session for that server key; local dev-token files should remain untouched.
|
||||
- **API surface parity:** every command using `CommandContext::for_target(...)` should inherit the same explicit-target behavior once the shared client plumbing is fixed. `exec` needs the parity fix separately because it bypasses that stack today.
|
||||
- **Integration coverage:** `ps`, auth scenario coverage, and `exec` all need regression protection because they represent three different surfaces exercising the same contract:
|
||||
- generated API client
|
||||
- browser auth endpoints
|
||||
- raw `/completions` transport
|
||||
- **Unchanged invariants:** local server lifecycle commands, local daemon auto-start, Unix-socket targeting, and plaintext non-loopback refresh rejection remain unchanged in principle.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Narrowing implicit dev-token fallback breaks existing local-HTTP tests or undocumented workflows | Update tests to use the deliberate local path or explicit credentials; document the new contract explicitly |
|
||||
| `exec` auth integration grows into a broad provider-layer refactor | Keep the fix CLI-local if possible and reuse `ServerStoreClient` rather than pushing CLI auth concerns into generic shared layers |
|
||||
| Production proxy handling changes accidentally slow or destabilize tests | Keep test-only builders and harnesses on explicit `no_proxy` or disabled-proxy policy; reserve proxy-aware assertions for a small number of targeted production-path regressions |
|
||||
| Shared client changes accidentally affect storage-owning local flows | Keep the `for_connection(...)` / local auto-start path explicit and preserve existing local-only regression coverage |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- The user-facing message should become simpler, not more nuanced:
|
||||
- explicit URL target = remote server
|
||||
- Unix socket and storage-owned local flow = local server conveniences
|
||||
- No deployment rollout or server config migration is required.
|
||||
- Do not add new deployment guidance around mTLS or built-in TLS termination; those are no longer part of the supported deployment story.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- Related plans:
|
||||
- [2026-04-06-cli-config-socket-storage-separation-plan.md](./2026-04-06-cli-config-socket-storage-separation-plan.md)
|
||||
- [2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md](./2026-04-05-cli-exec-explicit-local-and-mode-removal-plan.md)
|
||||
- [2026-04-19-003-feat-cli-auth-login-plan.md](./2026-04-19-003-feat-cli-auth-login-plan.md)
|
||||
- Related code:
|
||||
- `lib/crates/fabro-cli/src/command_context.rs`
|
||||
- `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/auth/login.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/auth/logout.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/exec.rs`
|
||||
- `lib/crates/fabro-server/src/server.rs`
|
||||
- Related tests:
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/ps.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/exec.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/scenario/auth.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/support/auth_harness.rs`
|
||||
- Repo guidance:
|
||||
- `docs-internal/testing-strategy.md`
|
||||
|
|
@ -1,856 +0,0 @@
|
|||
---
|
||||
title: "refactor: Extract fabro-client crate and lift domain DTOs to fabro-types"
|
||||
type: refactor
|
||||
status: active
|
||||
date: 2026-04-20
|
||||
---
|
||||
|
||||
Historical note (2026-04-21): the follow-up auth-surface tightening removed `LoopbackClassification`, `target.loopback_classification()`, `ensure_refresh_target_transport`, and the plain-HTTP refresh rejection. References to those APIs below describe the planned state at the time, not the current implementation.
|
||||
|
||||
# refactor: Extract fabro-client crate and lift domain DTOs to fabro-types
|
||||
|
||||
## Overview
|
||||
|
||||
Extract the typed Fabro-API client currently embedded in `fabro-cli` into a new reusable crate, `fabro-client`. Lift the domain data types the client uses (`RunSummary`, `EventEnvelope`, `RunProjection`, and an artifact-upload DTO) from `fabro-store` and `fabro-workflow` down to `fabro-types`, so `fabro-client` stays light on dependencies. Apply a short list of in-flight naming cleanups while we touch this code.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
`lib/crates/fabro-cli/src/server_client.rs` is a 1941-line file that implements a fully-featured HTTP client for the Fabro API (40+ typed method wrappers, OAuth refresh, SSE streaming, error classification, Unix-socket transport, artifact multipart uploads). The logic is reusable in spirit, but today it:
|
||||
|
||||
- lives inside the CLI binary crate, so nothing else in the workspace can reuse it
|
||||
- imports `fabro-store` DTOs (`RunSummary`, `EventEnvelope`, `RunProjection`) — entangling every consumer of the client with the storage layer
|
||||
- imports `fabro-workflow::artifact_snapshot::CapturedArtifactInfo` — pulling the workflow engine in for four artifact fields
|
||||
- mixes CLI concerns (subprocess autostart, dev-token-from-disk lookup, TOML-driven target resolution) with SDK concerns (make-a-request, parse-a-response) in the same file
|
||||
- carries several awkward names (`ClientBundle`, `RefreshableOAuth`, `ResolvedBearer`, `HttpResponseFailure`, `RunAttachEventStream`, `CapturedArtifactInfo`) that fight domain-driven naming
|
||||
|
||||
These were all reasonable while the client had exactly one caller. They prevent a second caller (an SDK, an IDE extension, future automation tooling) from emerging cleanly, and they block the layering story "`fabro-client` is to the API server what a typed SDK is to any HTTP service."
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. A new `fabro-client` crate exists at `lib/crates/fabro-client/`, declared in the workspace, publishing a typed `Client` and its connection machinery.
|
||||
- R2. `fabro-client` does **not** depend on `fabro-cli`, `fabro-store`, `fabro-workflow`, `fabro-server`, `fabro-config`, or any other CLI-bound or server-bound crate.
|
||||
- R3. `fabro-client` returns rich domain types from `fabro-types` (`RunSummary`, `EventEnvelope`, `RunProjection`, `StageId`, `RunId`, `RunBlobId`, `RunEvent`, `ArtifactUpload`) and wire-shape types re-exported from `fabro-api::types` (e.g. `SystemInfoResponse`, `PreviewUrlResponse`, `SecretMetadata`, `PruneRunsRequest`, `ModelTestResult`).
|
||||
- R4. `fabro-store` no longer owns `RunSummary`, `EventEnvelope`, or `RunProjection` (at the struct level). `fabro-workflow` no longer owns `CapturedArtifactInfo`.
|
||||
- R5. Type renames applied:
|
||||
- `ClientBundle` → inlined into `Client` (no separate type).
|
||||
- `RefreshableOAuth` → `OAuthSession`.
|
||||
- `ResolvedBearer` → `Credential`.
|
||||
- `HttpResponseFailure` → `ApiError`.
|
||||
- `RunAttachEventStream` → `RunEventStream`.
|
||||
- `CapturedArtifactInfo` → `ArtifactUpload`.
|
||||
- R6. `ServerTarget` is canonical-by-construction using lexical-only canonicalization (no `fs::canonicalize`, no existence checks). `ServerTargetKey` is deleted; `ServerTarget` serves as its own map key.
|
||||
- R7. `AuthStore` lives in `fabro-client`, defaults to `~/.fabro/auth.json`, and keys OAuth entries by `ServerTarget` directly.
|
||||
- R8. `fabro-cli` keeps CLI-owned orchestration: subprocess autostart, server-record lookup, dev-token-from-disk loading, `[cli.target]` TOML resolution, and the wrapper that stitches these together into a ready-to-use `fabro_client::Client`.
|
||||
- R9. The full workspace build passes (`cargo build --workspace`), clippy is clean (`cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings`), rustfmt check passes, and all workspace tests continue to pass (`cargo nextest run --workspace`).
|
||||
|
||||
## Review Adjustments
|
||||
|
||||
- Remaining gaps against this plan in the current landed code:
|
||||
- `HttpResponseFailure` → `ApiError` rename is still open.
|
||||
- `ServerTarget` canonical-by-construction / lexical-only Unix-path canonicalization is still open; canonicalization still partly lives in `AuthStore`.
|
||||
- `RunAttachEventStream` → `RunEventStream` rename is still open at the CLI boundary.
|
||||
- Because the two rename cleanups above are still open, Unit 11's "no leaked old names" grep is currently expected to fail until that follow-up cleanup lands.
|
||||
- Clarifications after implementation review:
|
||||
- `RunProjection` ownership moved to `fabro-types`; external callers may continue to import it through `fabro_store`'s re-export. Verification should check type ownership and dependency boundaries, not the literal import spelling.
|
||||
- `Client::from_http_client(...)` is the required public constructor. `Client::new_no_proxy(...)` may remain as a convenience wrapper, primarily for tests.
|
||||
- `TransportConnector` is an acceptable internal helper inside `fabro-client` when needed to preserve caller-specific transport configuration across refresh/rebuild flows.
|
||||
- `fabro-cli` may retain multiple thin `connect_*` convenience wrappers so long as they preserve CLI-only orchestration and funnel into `Client::builder()` under the hood.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
**In scope:**
|
||||
- Creating the `fabro-client` crate.
|
||||
- Lifting the four DTOs to `fabro-types` (`RunSummary`, `EventEnvelope`, `RunProjection`, `ArtifactUpload`).
|
||||
- The six type renames above.
|
||||
- `ServerTarget` canonical-by-construction + `ServerTargetKey` deletion.
|
||||
- Updating import sites across `fabro-cli`, `fabro-server`, `fabro-store`, `fabro-workflow`, `fabro-retro` (compiler-driven).
|
||||
- Keeping the existing behavior of every CLI command intact.
|
||||
|
||||
**Out of scope:**
|
||||
- Renaming `RunSummary`, `EventEnvelope`, `RunProjection`, `AuthEntry`, `StoredSubject` (structure moves, names stay; deferred per user direction).
|
||||
- Publishing `fabro-client` to crates.io or adding external-consumer documentation.
|
||||
- Writing a second consumer of `fabro-client` (SDK example, IDE integration, etc.) — the crate exists to enable that, not to deliver it.
|
||||
- Changing wire semantics (OpenAPI contract stays identical).
|
||||
- Migrating existing `~/.fabro/auth.json` entries. The canonical key format for HTTP targets remains identical (same `normalized_http_base_url` logic); Unix-socket canonicalization changes from `fs::canonicalize` (symlink-resolving) to lexical-only (`.`/`..` cleanup, no symlink chasing). Existing sessions against socket paths written as absolute non-symlinked paths continue to match. Users with symlinked socket paths may need to re-login — acceptable per `CLAUDE.md` ("We don't care about migration").
|
||||
- `RunEvent` unknown-variant handling. Already present today via `EventBody::Unknown` at `lib/crates/fabro-types/src/run_event/mod.rs:695` (covered by `:974`). Unit 2 verifies the `EventEnvelope` restructure preserves this existing behavior — no new variant, no new code.
|
||||
- Splitting the ~40 client methods into separate `client/runs.rs`, `client/secrets.rs`, etc. modules. A single `client.rs` is acceptable at ~900 lines; cosmetic domain splitting can happen later if the file grows.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-cli/src/server_client.rs:1-1941` — the entire current client implementation, including `Client`, `ClientBundle`, connection builders, error classification, `send_api`/`send_http`, `RunAttachEventStream`, and 40 typed wrapper methods.
|
||||
- `lib/crates/fabro-cli/src/auth_store.rs` — file-locked `~/.fabro/auth.json` persistence. Its `ServerTargetKey` is the canonical-key type that's about to go away.
|
||||
- `lib/crates/fabro-cli/src/loopback_target.rs` — pure URL classification, no dependencies outside `fabro-http` and `thiserror`. Moves cleanly.
|
||||
- `lib/crates/fabro-cli/src/sse.rs` — pure SSE line-buffer parser. Moves cleanly.
|
||||
- `lib/crates/fabro-cli/src/user_config.rs` — today owns `ServerTarget`, `normalized_http_base_url`, `cli_http_client_builder`, and TOML target resolution. `ServerTarget` and `normalized_http_base_url` move to `fabro-client`; the rest stays.
|
||||
- `lib/crates/fabro-cli/src/commands/server/{start,record}.rs` — CLI-owned autostart + pidfile. Stays.
|
||||
- `lib/crates/fabro-store/src/types.rs` — home of `RunSummary`, `EventEnvelope`, and `EventPayload`. `RunSummary` moves cleanly. `EventEnvelope` restructures (new shape `{ seq, event: RunEvent }`) and moves; `EventPayload` stays behind as an internal validation helper.
|
||||
- `lib/crates/fabro-store/src/run_state.rs` — home of `RunProjection`. The struct moves to `fabro-types` with its pure-data accessors; the event-reducer methods (`apply_event`, `apply_events`) move into a `RunProjectionReducer` trait in `fabro-store` implemented on `fabro_types::RunProjection`. See Unit 3.
|
||||
- `lib/crates/fabro-workflow/src/artifact_snapshot.rs:20-26` — `CapturedArtifactInfo` definition. Four pure-data fields, serde derives only.
|
||||
- `docs/api-reference/fabro-api.yaml:3452-3461` — OpenAPI defines `EventEnvelope` as `allOf [EventSeq, RunEvent]`, wire format `{ seq, event_fields_flattened_in }`. `fabro_types::EventEnvelope { seq: u32, #[serde(flatten)] event: RunEvent }` matches the wire contract exactly — no serialization change, only the Rust representation changes.
|
||||
- `lib/crates/fabro-types/Cargo.toml` — deps are already lightweight (`chrono`, `fabro-model`, `fabro-util`, `serde`, `serde_json`). Our new DTOs fit inside this dep envelope.
|
||||
- Plan format precedent: `docs/plans/2026-04-20-001-fix-cli-server-same-host-assumptions-plan.md` — recently-landed refactor in the same subsystem; we model frontmatter and section style on it.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
- 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.
|
||||
- `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
|
||||
|
||||
None. Internal refactor; the patterns are all established locally.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **`fabro-client` has zero CLI/server/workflow/store coupling.** Its dep list is `fabro-api`, `fabro-http`, `fabro-model`, `fabro-types`, `fabro-util`, plus general-purpose async/serialization crates. Rationale: this is the whole point — make reuse a compile-time guarantee, not a convention. Consumers inherit the transitive surface of these deps (reqwest via `fabro-http`, progenitor-generated client via `fabro-api`, chrono/serde via the rest) — not minimal, but consistent with the crate's "typed SDK for the Fabro HTTP API" scope.
|
||||
- **Domain DTOs live in `fabro-types`; wire shapes live in `fabro-api`.** Rich Rust types (`RunSummary` with `HashMap<String,String>` and `RunId` newtype, `RunProjection` with all the `fabro-types` sub-records) belong with the rest of the domain vocabulary. Single-use request/response shapes (`PruneRunsRequest`, `SandboxFileEntry`, etc.) stay in the auto-generated `fabro-api::types` and are re-exported from `fabro-client::types`.
|
||||
- **`EventEnvelope` restructure.** Change from `{ seq, payload: EventPayload(serde_json::Value) }` to `{ seq: u32, #[serde(flatten)] event: RunEvent }`. The wire contract is unchanged (OpenAPI already specifies `allOf [EventSeq, RunEvent]`). The Rust representation becomes typed end-to-end, eliminating `.payload.as_value() → RunEvent::from_ref(...)` conversions at every consumer. `EventPayload` stays in `fabro-store` as an internal validation helper used by the storage path.
|
||||
- **`RunProjection` method split via `RunProjectionReducer` extension trait.** Move the struct (data) to `fabro-types`, including its pure-data accessors (`node`, `iter_nodes`, `is_empty`, `set_node`, `list_node_visits`, `node_mut`, `current_visit_for`, `reset_for_rewind`) as `pub` inherent methods. Define `RunProjectionReducer` in `fabro-store` with `apply_event`/`apply_events` (and `impl RunProjectionReducer for fabro_types::RunProjection`) so storage behavior stays in `fabro-store` while call-site syntax remains method-style: `use fabro_store::RunProjectionReducer; projection.apply_event(ev)?`. The trait form preserves OOP-style method chaining at ~10 call sites and fits the workspace's preferred convention (methods over free helpers). `build_summary` stays as a `pub(crate)` free function in `fabro-store` — it's a projection-derived summary, not a mutation on the projection itself.
|
||||
- **`ServerTarget` canonical-by-construction, lexical only.** `ServerTarget::from_url` applies today's full HTTP canonicalization inline: lowercase scheme, lowercase host, strip default ports (`:443` on https, `:80` on http), strip trailing `/`, strip `/api/v1` suffix, rebuild authority as `{scheme}://{host}[:{port}]`. `ServerTarget::from_unix_path` applies lexical `.`/`..` resolution (no FS access, no symlink chasing). `PartialEq`/`Eq`/`Hash` operate on the canonical form directly. `ServerTargetKey` is deleted; `ServerTarget` itself serves as the `AuthStore` map key. In OOP style: construction *is* the canonicalizer — no separate `canonicalize()` method. Related helpers attach to `ServerTarget` as inherent methods (`target.loopback_classification()`, `target.build_public_http_client()`) rather than free functions.
|
||||
- **`AuthStore` moves to `fabro-client`.** Default path remains `~/.fabro/auth.json` via `fabro_util::Home`. The public API (`get`/`put`/`remove`/`list`) is narrow enough that we keep it concrete — no `TokenRefresher` trait abstraction. Callers wanting alternative storage can pass an explicit path to `AuthStore::new`. If external-consumer flexibility becomes a real need later, we extract a trait then, not now.
|
||||
- **Renames applied inline with moves.** We don't do a separate rename pass — the DTOs and internal types are renamed as they move. This keeps the compiler-driven find-all-callers loop honest: every broken import is both a move and a rename in one commit.
|
||||
- **Connection API centers on one builder.** Today's `connect_*` functions in `server_client.rs` are CLI-opinionated convenience wrappers. `fabro-client` exposes `Client::builder().target(t).credential(c).oauth_session(s).connect().await?` as the underlying connection API. `fabro-cli` may keep several thin `connect_*` wrappers, but they must remain orchestration-only and funnel into the builder instead of duplicating transport/session assembly logic.
|
||||
- **Refresh rebuilds may use a transport connector hook.** If the CLI needs request-transport customization across OAuth refresh rebuilds (for example, preserving a CLI-specific user-agent), `fabro-client` may carry a `TransportConnector`-style helper as an internal implementation detail. This does not count as a second public connection API.
|
||||
|
||||
- **`OAuthSession` refresh fallback via `CredentialFallback` trait.** Today's refresh flow falls back to a dev-token-from-disk when the OAuth entry is missing, expired, or revoked. That fallback lookup reads CLI-owned sources (`FABRO_DEV_TOKEN` env, `~/.fabro/dev-token`, storage-dir dev-token file, fabro-server pidfile record) that don't belong in `fabro-client`. `OAuthSession` takes an optional `Box<dyn CredentialFallback>` at build time:
|
||||
```text
|
||||
// Directional — not implementation
|
||||
pub trait CredentialFallback: Send + Sync {
|
||||
fn resolve(&self) -> Option<Credential>;
|
||||
}
|
||||
```
|
||||
On refresh failure modes that previously triggered fallback, `OAuthSession` calls `fallback.resolve()`. If `Some(Credential)`, the session rebuilds the client bundle with that credential; if `None`, it surfaces "session expired." The CLI provides a concrete impl in `fabro-cli` that wraps the existing dev-token-loading logic. Named trait (vs bare `Fn` closure) makes the role obvious at the `OAuthSession::builder` call site.
|
||||
|
||||
- **`fabro_types::RunEvent` already tolerates unknown event names.** `EventBody::Unknown { name, properties }` at `lib/crates/fabro-types/src/run_event/mod.rs:695` is the existing fallback — a newer server's unknown event type deserializes into this variant without error. Unit 2's responsibility is to *preserve* this behavior across the `EventEnvelope { seq, #[serde(flatten)] event: RunEvent }` restructure, not to add a new variant.
|
||||
- **Phased delivery.** DTO lift must land before the client extraction — otherwise `fabro-client`'s deps can't be correct. We split the work into three phases (DTO lift → `fabro-client` extraction → `fabro-cli` rewire) and land each phase as a coherent chunk. Each phase compiles and tests pass at its boundary.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Where do `apply_events`/`apply_event` live after `RunProjection` moves?** In `fabro-store` as an extension trait `RunProjectionReducer` implemented on `fabro_types::RunProjection`. Preserves OOP-style method-call syntax at call sites via `use fabro_store::RunProjectionReducer;`. Chosen over free functions because the workspace leans toward methods over free helpers.
|
||||
- **HTTP canonicalization scope in `ServerTarget::from_url`.** Preserve today's full normalization: lowercase scheme + lowercase host + strip default ports + strip trailing `/` + strip `/api/v1` suffix + rebuild authority. Matches today's `canonical_http_target` in `auth_store.rs:350-383` and the existing `https_normalization_collapses_equivalent_urls` test at line 507. Simpler "strip slash + api-v1 only" form was rejected because it would silently invalidate AuthStore entries for users whose URLs differed only in case or default-port.
|
||||
- **OAuthSession refresh fallback mechanism.** Add a `CredentialFallback` trait; `fabro-cli` implements it against its dev-token sources; `OAuthSession` holds `Option<Box<dyn CredentialFallback>>` and calls `fallback.resolve()` on the failure modes that previously fell back to dev-token. Named trait (not bare `Fn`) chosen for role clarity.
|
||||
- **`RunEvent` unknown-variant forward-compat.** Already handled today via `EventBody::Unknown` at `lib/crates/fabro-types/src/run_event/mod.rs:695` (tested at `:974`). Unit 2 verifies the `EventEnvelope` restructure preserves this existing behavior — no new variant, no new code.
|
||||
- **Does `EventEnvelope` need `EventPayload` to travel with it?** No. OpenAPI already defines the wire shape as `seq + RunEvent flattened`. `EventPayload` is a storage-internal validation helper and stays behind.
|
||||
- **Does `AuthStore` need a trait-based abstraction?** No. Concrete type with a configurable file path is sufficient; we extract a trait the day a second implementation exists.
|
||||
- **Does `ArtifactUpload` live in `fabro-types` or `fabro-client`?** `fabro-types`. Source is `fabro-workflow` (capture) → sink is `fabro-client` (upload). Placing the DTO in `fabro-types` prevents `fabro-workflow` from having to depend on `fabro-client`.
|
||||
- **How do we handle the `Client::new_no_proxy(base_url)` constructor used by CLI tests today?** Expose `Client::from_http_client(base_url, http_client)` as the stable public `pub fn`. `Client::new_no_proxy(base_url)` may remain as a small convenience wrapper (in `fabro-client` or CLI-local test code) if it continues to earn its keep.
|
||||
- **`convert_type` serde round-trip helper — does it stay in the CLI or move with the client?** Moves with the client. It's how the client bridges `fabro_api::types::RunSummary` (wire) → `fabro_types::RunSummary` (domain) at response boundaries.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- Exact module file layout inside `fabro-client/src/` may shift slightly as we go (e.g., whether `credential.rs` and `session.rs` stay separate or merge). Guide: keep the sketched layout unless one file shrinks under ~50 lines, at which point merge.
|
||||
- Whether any `pub(crate)` items inside the current `server_client.rs` need to become `pub` when exposed from `fabro-client`. Driven by compiler errors when `fabro-cli` imports across the crate boundary.
|
||||
- Exact form of the CLI's `Credential`-building helper after the move (currently called `resolve_target_bearer`). The shape depends on what survives in `fabro-cli` after the extraction.
|
||||
- Whether `Client` ends up `#[derive(Debug)]` or implements `Debug` manually. Today it isn't. Driven by whether any downstream consumer needs it.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
### Target crate dependency graph
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph New["After refactor"]
|
||||
cli2[fabro-cli]
|
||||
client2[fabro-client]
|
||||
api2[fabro-api]
|
||||
types2[fabro-types]
|
||||
workflow2[fabro-workflow]
|
||||
store2[fabro-store]
|
||||
http2[fabro-http]
|
||||
server2[fabro-server]
|
||||
|
||||
cli2 --> client2
|
||||
cli2 --> workflow2
|
||||
cli2 --> store2
|
||||
cli2 --> server2
|
||||
client2 --> api2
|
||||
client2 --> types2
|
||||
client2 --> http2
|
||||
workflow2 --> types2
|
||||
store2 --> types2
|
||||
server2 --> store2
|
||||
server2 --> api2
|
||||
api2 --> types2
|
||||
end
|
||||
```
|
||||
|
||||
Key property: `fabro-client` has **no** arrow into `fabro-store`, `fabro-workflow`, `fabro-server`, `fabro-cli`, or `fabro-config`.
|
||||
|
||||
### fabro-client module layout
|
||||
|
||||
```text
|
||||
lib/crates/fabro-client/
|
||||
├── Cargo.toml
|
||||
└── src/
|
||||
├── lib.rs — re-exports, crate docs, `pub use types` from fabro-api
|
||||
├── client.rs — Client struct (flattened, no Bundle), send_api/send_http,
|
||||
│ Client::builder(), all ~40 wrapper methods
|
||||
├── target.rs — ServerTarget (canonical-by-construction), Display, FromStr
|
||||
├── credential.rs — Credential { DevToken, OAuth }
|
||||
├── session.rs — OAuthSession, refresh_access_token flow
|
||||
├── auth_store.rs — AuthStore, AuthEntry, StoredSubject
|
||||
├── error.rs — ApiError, classify_api_error, classify_http_response, map_api_error
|
||||
├── sse.rs — drain_sse_payloads, RunEventStream
|
||||
└── loopback.rs — LoopbackClassification (accessed via target.loopback_classification())
|
||||
```
|
||||
|
||||
### Phase sequencing
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
P1[Phase 1: DTO lift to fabro-types]
|
||||
P2[Phase 2: Create fabro-client crate]
|
||||
P3[Phase 3: Rewire fabro-cli]
|
||||
P4[Phase 4: Verification]
|
||||
|
||||
P1 --> P2
|
||||
P2 --> P3
|
||||
P3 --> P4
|
||||
|
||||
subgraph P1u[Phase 1 units]
|
||||
U1[Unit 1: Move RunSummary]
|
||||
U2[Unit 2: Move + restructure EventEnvelope]
|
||||
U3[Unit 3: Move RunProjection struct]
|
||||
U4[Unit 4: Move + rename ArtifactUpload]
|
||||
end
|
||||
|
||||
subgraph P2u[Phase 2 units]
|
||||
U5[Unit 5: Scaffold fabro-client crate]
|
||||
U6[Unit 6: Move pure helpers + ServerTarget]
|
||||
U7[Unit 7: Move AuthStore]
|
||||
U8[Unit 8: Move Client + session + credential]
|
||||
end
|
||||
|
||||
subgraph P3u[Phase 3 units]
|
||||
U9[Unit 9: Rewire CLI orchestrator]
|
||||
U10[Unit 10: Delete moved fabro-cli modules]
|
||||
end
|
||||
|
||||
U1 -.-> P1
|
||||
U2 -.-> P1
|
||||
U3 -.-> P1
|
||||
U4 -.-> P1
|
||||
U5 -.-> P2
|
||||
U6 -.-> P2
|
||||
U7 -.-> P2
|
||||
U8 -.-> P2
|
||||
U9 -.-> P3
|
||||
U10 -.-> P3
|
||||
```
|
||||
|
||||
Within a phase, units may execute in parallel when independent; across phases, the order is strict.
|
||||
|
||||
### Connection API shape
|
||||
|
||||
```text
|
||||
// Directional sketch — not implementation.
|
||||
// fabro-client exposes one builder that replaces today's four connect_* fns.
|
||||
|
||||
Client::builder()
|
||||
.target(ServerTarget::from_str("https://fabro.example.com/api/v1")?)
|
||||
.credential(Credential::DevToken("fabro_dev_...".into()))
|
||||
.oauth_session(session) // optional; enables auto-refresh on 401
|
||||
.connect()
|
||||
.await?
|
||||
|
||||
// fabro-cli's orchestrator becomes roughly:
|
||||
// 1. resolve ServerTarget from args + settings
|
||||
// 2. if Unix + not running: ensure_server_running_on_socket
|
||||
// 3. build Credential from env / auth_store / dev-token-file
|
||||
// 4. Client::builder().target(t).credential(c).oauth_session(s).connect()
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
### Phase 1 — DTO lift to fabro-types
|
||||
|
||||
- [ ] **Unit 1: Move `RunSummary` to `fabro-types`**
|
||||
|
||||
**Goal:** Relocate the `RunSummary` struct from `fabro-store` to `fabro-types` so that crates consuming runs-list data no longer depend on the storage layer.
|
||||
|
||||
**Requirements:** R3, R4.
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-types/src/run_summary.rs`
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs` (add `pub mod run_summary;` + re-export)
|
||||
- Modify: `lib/crates/fabro-store/src/types.rs` (delete `RunSummary` definition; keep re-export `pub use fabro_types::RunSummary;` during transition, or update all call sites and delete outright — prefer the latter)
|
||||
- Modify: call sites across `lib/crates/fabro-cli/` (~4 files), `lib/crates/fabro-server/src/server.rs`, `lib/crates/fabro-store/` (internal uses), any others the compiler surfaces
|
||||
- Test: `lib/crates/fabro-types/src/run_summary.rs` (inline `#[cfg(test)]` module with a round-trip serde test)
|
||||
|
||||
**Approach:**
|
||||
- Copy the struct verbatim from `fabro-store/src/types.rs:10-24` into a new `fabro-types/src/run_summary.rs`. The struct already references only `fabro_types` types (`RunId`, `RunStatus`, `BlockedReason`, etc.), so no type-substitution is needed.
|
||||
- Re-export from `fabro-types/src/lib.rs`: `pub use run_summary::RunSummary;`.
|
||||
- In `fabro-store/src/types.rs`, delete the struct and update any store-internal references to import from `fabro_types::RunSummary`.
|
||||
- Update import sites. Compiler drives the list; expect ~6 files.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Mirror the style of existing small DTO modules in `fabro-types`: `fabro-types/src/run_blob_id.rs`, `fabro-types/src/sandbox_record.rs`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `RunSummary` serialized and round-tripped through `serde_json` produces an identical value. (Carry over or adapt any existing test from `fabro-store`.)
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run -p fabro-types -p fabro-store -p fabro-server -p fabro-cli` passes.
|
||||
- `grep -rn "fabro_store::RunSummary\|fabro_store::types::RunSummary" lib/` returns no results outside `fabro-store` internals.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 2: Move and restructure `EventEnvelope` in `fabro-types`**
|
||||
|
||||
**Goal:** Replace `fabro-store`'s `EventEnvelope { seq, payload: EventPayload(serde_json::Value) }` with `fabro-types`'s `EventEnvelope { seq: u32, #[serde(flatten)] event: RunEvent }`. The wire format is unchanged (OpenAPI already flattens `RunEvent` fields alongside `seq`).
|
||||
|
||||
**Requirements:** R3, R4.
|
||||
|
||||
**Dependencies:** None (independent of Unit 1, can run in parallel).
|
||||
|
||||
**Files:** (verified call-site inventory; compiler drives any residual sites)
|
||||
|
||||
Construction sites (switch to `fabro_types::EventEnvelope { seq, event }`):
|
||||
- Create: `lib/crates/fabro-types/src/event_envelope.rs`
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs` (module + re-export)
|
||||
- Modify: `lib/crates/fabro-store/src/types.rs` (delete old `EventEnvelope`; keep `EventPayload` internal; update tests at lines 127 and 171)
|
||||
- Modify: `lib/crates/fabro-store/src/slate/run_store.rs` (production constructors at lines 194 and 342)
|
||||
- Modify: `lib/crates/fabro-store/src/run_state.rs` (apply_event body at line 79; test fixtures at lines 728, 741, 1086, 1112; test assertions at lines 1133, 1137)
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/runner.rs:372-373` (write path that also constructs an envelope)
|
||||
|
||||
Read sites (switch from `envelope.payload.as_value()` / `&envelope.payload` → `&envelope.event`):
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (7 sites: 888, 1776, 1794, 3307, 3581, 8770, 8771 — includes the `api_event_envelope_from_store` merge-seq logic and two test assertions)
|
||||
- Modify: `lib/crates/fabro-retro/src/retro_agent.rs:311`
|
||||
- Modify: `lib/crates/fabro-workflow/src/lib.rs:95` (`extract_stage_durations_from_events`)
|
||||
- Modify: `lib/crates/fabro-workflow/src/event.rs:3169` (test read)
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/create.rs:1026` (test read)
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/logs.rs:91, 271`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/attach.rs:395, 465, 480`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/store/rebuild.rs:20` (read-then-write hybrid). Reads become `envelope.event`; write-path re-validation becomes `EventPayload::new(event.to_value()?, run_id)?` — note `RunEvent::to_value()` returns `serde_json::Result<Value>` (was infallible `.as_value().clone()`), so the `?` propagates. Callers that already return `anyhow::Result` absorb it naturally.
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/workflow/mod.rs:59`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/cmd/support.rs:794`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/cmd/runner.rs:32`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/cmd/rewind.rs` (seven `.payload.as_value()` reads at 132, 156, 160, 165, 169, 173, 177)
|
||||
|
||||
Type-only references (import switch; no body change needed — compiler drives):
|
||||
- `lib/crates/fabro-cli/src/server_client.rs`, `src/commands/store/{dump,run_export}.rs`
|
||||
- `lib/crates/fabro-workflow/src/run_dump.rs`
|
||||
- `lib/crates/fabro-cli/tests/it/support/mod.rs`
|
||||
|
||||
Write-path `EventPayload::new` sites (UNAFFECTED — stay in fabro-store as internal validation; listed here to document scope):
|
||||
- `lib/crates/fabro-store/src/slate/mod.rs:346`
|
||||
- `lib/crates/fabro-workflow/src/operations/create.rs:259`
|
||||
- `lib/crates/fabro-workflow/src/event.rs:2625, 2643`
|
||||
- `lib/crates/fabro-server/src/server.rs:5226, 8025`
|
||||
- Test fixtures in `lib/crates/fabro-cli/src/commands/store/dump.rs:669` and the store's own test modules
|
||||
|
||||
**Approach:**
|
||||
- New struct in `fabro-types`:
|
||||
```text
|
||||
// Directional — not implementation
|
||||
pub struct EventEnvelope {
|
||||
pub seq: u32,
|
||||
#[serde(flatten)]
|
||||
pub event: RunEvent,
|
||||
}
|
||||
```
|
||||
- Confirm today's `EventBody::Unknown { name, properties }` fallback (at `lib/crates/fabro-types/src/run_event/mod.rs:695`) continues to round-trip through the new `EventEnvelope { seq, #[serde(flatten)] event: RunEvent }` shape — the `#[serde(flatten)]` interacts cleanly with the existing catch-all. No new variant is added; we are only confirming the existing forward-compat behavior survives.
|
||||
- `fabro-store` keeps `EventPayload` strictly internal — every existing write path continues to call `EventPayload::new(value, run_id)?` for `expected_run_id` validation before persisting (unchanged behavior). No write path bypasses that check. Only the external-facing read-path return type changes.
|
||||
- At the store's read boundary (`slate/run_store.rs:194, 342` — where the old `EventEnvelope { seq, payload }` was constructed by pairing a separately-tracked seq with decoded payload bytes): deserialize the raw bytes as `RunEvent` (the on-disk format is raw RunEvent JSON without `seq`), then wrap in `fabro_types::EventEnvelope { seq, event }`. The write path at `slate/run_store.rs:201-203` continues to persist `serde_json::to_vec(payload)?` of the `EventPayload`; the `seq` comes from a separate counter, same as today.
|
||||
- CLI callers that did `event.payload.as_value()` + `RunEvent::from_ref(...)` → change to `&event.event`. This is a win at every call site (fewer conversions).
|
||||
- `runner.rs:372-373` currently builds an `EventPayload::new(event.to_value()?, run_id)?` + `EventEnvelope { seq, payload }`. After this unit, build `fabro_types::EventEnvelope { seq, event }` directly.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Serde `#[serde(flatten)]` usage elsewhere in `fabro-types` (`fabro-types/src/run_event/` has flatten in some variants).
|
||||
- OpenAPI contract at `docs/api-reference/fabro-api.yaml:3452-3461`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `EventEnvelope` round-trips through `serde_json` preserving both `seq` and all `RunEvent` fields, and deserializes the existing wire format identically.
|
||||
- Integration: existing `fabro-store` test `wire_event_envelope_round_trips` still passes after porting (adapt it to construct the new struct shape).
|
||||
- Integration: CLI integration tests that consume events over SSE or HTTP (e.g., `fabro-cli/tests/it/workflow/mod.rs`, `cmd/attach.rs`) continue to pass — proves the wire shape is unchanged.
|
||||
- Forward-compat regression guard: an `EventEnvelope` JSON payload whose event name is unknown to this build of `fabro-types` deserializes into the existing `EventBody::Unknown { name, properties }` without error and re-serializes losslessly. (Covers: the `EventEnvelope` restructure did not break today's fallback at `run_event/mod.rs:695`.)
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run --workspace` passes, including all `fabro-cli::it` event-consuming tests.
|
||||
- `grep -rn "EventPayload" lib/crates/fabro-cli/src/` shows only `runner.rs` / `rebuild.rs` / `dump.rs` usage that persists into the store (legitimate — those write events *into* storage and need the validating wrapper). Read paths no longer touch `EventPayload`.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 3: Move `RunProjection` struct to `fabro-types`**
|
||||
|
||||
**Goal:** Relocate `RunProjection` (the data struct) to `fabro-types`. Move pure-data methods with it. Keep event-reducer methods (`apply_event`, `apply_events`) in `fabro-store` behind a `RunProjectionReducer` extension trait implemented on `fabro_types::RunProjection`, so call-site syntax stays method-style (OOP preference).
|
||||
|
||||
**Requirements:** R3, R4.
|
||||
|
||||
**Dependencies:** Unit 2 (apply_event references EventEnvelope's new shape).
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-types/src/run_projection.rs` (struct `RunProjection` + `PendingInterviewRecord` + `NodeState`; pub inherent data-method accessors)
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs` (add module + re-exports)
|
||||
- Modify: `lib/crates/fabro-store/src/run_state.rs`:
|
||||
- Delete the struct definitions moving to `fabro-types`.
|
||||
- Keep `EventProjectionCache` (storage-internal).
|
||||
- Define `RunProjectionReducer` trait with `apply_event`/`apply_events` and `impl RunProjectionReducer for fabro_types::RunProjection`.
|
||||
- Keep `build_summary` as a `pub(crate)` free function (it's a derived projection-to-summary builder, not a reducer).
|
||||
- Modify: call sites in `lib/crates/fabro-cli/` (~4 store/dump/rebuild/runner files), `lib/crates/fabro-retro/src/retro_agent.rs`, `lib/crates/fabro-workflow/src/run_dump.rs`, `lib/crates/fabro-server/src/server.rs` — add `use fabro_store::RunProjectionReducer;` where the trait methods are called.
|
||||
|
||||
**Approach:**
|
||||
- Copy `RunProjection`, `PendingInterviewRecord`, `NodeState` into `fabro-types/src/run_projection.rs`. All field types are already in `fabro-types`, so this is a straight move.
|
||||
- Move the struct's data-operating methods *with* it to `fabro-types` as `pub` inherent methods: `node`, `iter_nodes`, `is_empty`, `set_node`, `list_node_visits`, `node_mut`, `current_visit_for`, `reset_for_rewind`. These touch only `self` fields and `fabro-types` types. Private fields (e.g., `nodes: HashMap<StageId, NodeState>`) stay private; the reducer trait in `fabro-store` calls these public methods to perform its mutations.
|
||||
- In `fabro-store/src/run_state.rs`, define the reducer trait:
|
||||
```text
|
||||
// Directional — not implementation
|
||||
pub trait RunProjectionReducer {
|
||||
// Primitive reducer: mutate the projection with one event.
|
||||
fn apply_event(&mut self, envelope: &EventEnvelope) -> Result<()>;
|
||||
// Constructor helper: build a fresh projection by folding events over Default.
|
||||
fn apply_events(events: &[EventEnvelope]) -> Result<RunProjection>
|
||||
where Self: Sized;
|
||||
}
|
||||
|
||||
impl RunProjectionReducer for fabro_types::RunProjection {
|
||||
fn apply_event(&mut self, envelope: &EventEnvelope) -> Result<()> { /* moved from impl */ }
|
||||
fn apply_events(events: &[EventEnvelope]) -> Result<RunProjection> {
|
||||
let mut state = RunProjection::default();
|
||||
for event in events { state.apply_event(event)?; }
|
||||
Ok(state)
|
||||
}
|
||||
}
|
||||
```
|
||||
Call-site change: `projection.apply_event(envelope)?` keeps working with one added `use fabro_store::RunProjectionReducer;` per file that uses it (~5-6 files).
|
||||
- Orphan rule permits this — `RunProjectionReducer` is local to `fabro-store`, `fabro_types::RunProjection` is foreign but we're implementing the local trait on it.
|
||||
- `build_summary(projection: &RunProjection, run_id: RunId, ...) -> RunSummary` stays as a `pub(crate)` free function in `fabro-store` — it's a pure builder from projection → summary, not a mutation on the projection.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Extension-trait-on-foreign-struct pattern: `trait LocalTrait { ... }` + `impl LocalTrait for foreign::Struct { ... }`. Standard Rust. The trait name `RunProjectionReducer` communicates the role (it reduces events into the projection).
|
||||
- The workspace's OOP preference: callers invoke `projection.apply_event(ev)?` as a method, not `some_module::apply_event(&mut projection, ev)?` as a free function.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: constructing a default `RunProjection` and applying a sequence of events produces the same projection as before the move (carry over existing fabro-store tests).
|
||||
- Integration: `fabro-cli` store-dump and rebuild scenarios continue to produce byte-identical output (existing scenario tests in `tests/it/scenario/` provide this coverage implicitly).
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `grep -rn "struct RunProjection" lib/crates/fabro-store lib/crates/fabro-types` shows the concrete struct definition only in `fabro-types`; external callers may import either `fabro_types::RunProjection` or the `fabro-store` re-export.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 4: Rename and move `CapturedArtifactInfo` → `ArtifactUpload` in `fabro-types`**
|
||||
|
||||
**Goal:** Rename `CapturedArtifactInfo` to `ArtifactUpload` and move it from `fabro-workflow` to `fabro-types`. Break the `fabro-client → fabro-workflow` dependency chain (not yet active — prevents it from forming during Phase 2).
|
||||
|
||||
**Requirements:** R3, R4, R5.
|
||||
|
||||
**Dependencies:** None (independent of Units 1-3; can run in parallel).
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-types/src/artifact.rs` (struct `ArtifactUpload` with the same four fields).
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs` (add module + re-export).
|
||||
- Modify: `lib/crates/fabro-workflow/src/artifact_snapshot.rs` (delete `CapturedArtifactInfo`; update `ArtifactCollectionSummary.captured_assets` to `Vec<ArtifactUpload>`; update constructor sites to build `ArtifactUpload`).
|
||||
- Modify: `lib/crates/fabro-workflow/src/artifact_upload.rs`, `src/lifecycle/artifact.rs` — update type refs.
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs`, `src/commands/run/runner.rs` — update type refs.
|
||||
|
||||
**Approach:**
|
||||
- Define `ArtifactUpload` in `fabro-types/src/artifact.rs` with identical fields: `path: String`, `mime: String`, `content_md5: String`, `content_sha256: String`, `bytes: u64`. Same serde derives.
|
||||
- Delete `CapturedArtifactInfo` from `fabro-workflow/src/artifact_snapshot.rs`.
|
||||
- Compiler drives the renames across ~6 files.
|
||||
|
||||
**Patterns to follow:**
|
||||
- DTO placement: mirror `fabro-types/src/sandbox_record.rs`.
|
||||
- Field naming stays identical — no rename of fields, only the struct name.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: round-trip serde test for `ArtifactUpload` (inline in the module).
|
||||
- Integration: fabro-workflow's artifact-collection integration tests continue to pass with no behavior change.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run -p fabro-types -p fabro-workflow -p fabro-cli` passes.
|
||||
- `grep -rn "CapturedArtifactInfo" lib/ docs/` returns only results in `docs/plans/` (historical) — no code hits.
|
||||
|
||||
### Phase 2 — Create `fabro-client` crate
|
||||
|
||||
- [ ] **Unit 5: Scaffold `fabro-client` crate**
|
||||
|
||||
**Goal:** Create the new crate with its `Cargo.toml`, empty module structure, and workspace registration. No logic yet.
|
||||
|
||||
**Requirements:** R1.
|
||||
|
||||
**Dependencies:** None (can start any time, but Phase 1 must complete before Units 6-8 can compile).
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-client/Cargo.toml`
|
||||
- Create: `lib/crates/fabro-client/src/lib.rs` (empty except for `pub mod` declarations and crate-level docs)
|
||||
- Create: `lib/crates/fabro-client/src/{client,target,credential,session,auth_store,error,sse,loopback}.rs` as empty stubs
|
||||
- Modify: root `Cargo.toml` — the workspace `members = ["lib/crates/*", ...]` glob already picks up the new crate; also register `fabro-client = { path = "lib/crates/fabro-client" }` under `[workspace.dependencies]` if that pattern is used (it is — see `fabro-http` and `fabro-test` entries in root `Cargo.toml`).
|
||||
|
||||
**Approach:**
|
||||
- Model `Cargo.toml` on `lib/crates/fabro-http/Cargo.toml` (similar scope: a typed wrapper over an HTTP layer). Dependencies:
|
||||
```text
|
||||
fabro-api, fabro-http, fabro-model, fabro-types, fabro-util,
|
||||
anyhow, bytes, chrono, futures, fs2, progenitor-client, rand,
|
||||
serde, serde_json, thiserror, tokio, tokio-util, tracing
|
||||
```
|
||||
- `[dev-dependencies]`: `tempfile`.
|
||||
- Mirror fabro-types's `publish = false`, `edition.workspace = true`, `version.workspace = true`, `[lints] workspace = true`.
|
||||
- Crate-level doc comment in `lib.rs` explaining: typed client for the Fabro HTTP API; the CLI's `fabro-cli` uses this crate; future SDKs will too.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-http/Cargo.toml` — similar scope (infrastructure crate, no domain logic).
|
||||
- `lib/crates/fabro-types/Cargo.toml` — modest dep list, `doctest = false`, workspace lints.
|
||||
|
||||
**Test scenarios:**
|
||||
- Test expectation: none — pure scaffolding. This unit introduces no behavior.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-client` succeeds (should be a no-op build — no code yet).
|
||||
- `cargo build --workspace` still succeeds (adding an empty crate doesn't break anything).
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 6: Move pure helpers and `ServerTarget` into `fabro-client`**
|
||||
|
||||
**Goal:** Move modules with no CLI coupling: SSE parsing, loopback classification, error classification, and the `ServerTarget` enum with canonical-by-construction behavior. Delete `ServerTargetKey`.
|
||||
|
||||
**Requirements:** R2, R5, R6.
|
||||
|
||||
**Dependencies:** Unit 5 (crate must exist).
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-client/src/sse.rs` — populate from `lib/crates/fabro-cli/src/sse.rs`.
|
||||
- Modify: `lib/crates/fabro-client/src/loopback.rs` — populate from `lib/crates/fabro-cli/src/loopback_target.rs` (rename module).
|
||||
- Modify: `lib/crates/fabro-client/src/error.rs` — populate with `ApiError` (ex-`HttpResponseFailure`), `ApiFailure`, `StructuredApiError`, `classify_api_error`, `classify_http_response`, `map_api_error`, `parse_error_response_value`, `is_not_found_error`, `raw_response_failure_error`.
|
||||
- Modify: `lib/crates/fabro-client/src/target.rs` — populate with `ServerTarget { Http(Url), Unix(PathBuf) }`, `FromStr`, `Display`, `PartialEq`/`Eq`/`Hash` on the canonical form. Include `normalized_http_base_url` as a private helper used at construction.
|
||||
- Modify: `lib/crates/fabro-client/src/lib.rs` — re-export `ServerTarget`, `LoopbackClassification`, `ApiError`.
|
||||
- Delete from `fabro-cli`: `lib/crates/fabro-cli/src/loopback_target.rs` (after Phase 3 rewires CLI to use `fabro-client`). **For this unit, replace each CLI file's entire content with a one-line re-export — e.g., `pub(crate) use fabro_client::*;` (or the specific items the CLI consumes).** The file stays on disk as a thin forwarder until Unit 10 deletes it. This avoids duplicate-symbol errors during the intermediate state. Alternative: skip the shim and update every call site in the same commit per-module — more churn per commit, but no intermediate layer to reason about.
|
||||
|
||||
**Approach:**
|
||||
- Rename `HttpResponseFailure` → `ApiError`. Leave `ApiFailure` (internal, used in `should_refresh` logic) as-is — it's not in the user-facing rename list.
|
||||
- Canonicalization in `ServerTarget::from_url`: parse via `fabro_http::Url::parse`, then apply today's full `canonical_http_target` normalization (lowercase scheme, lowercase host, strip default ports `:443`/`:80`, strip trailing `/`, strip `/api/v1` suffix, rebuild authority as `{scheme}://{host}[:{port}]`). Store the canonical `Url`. Implement `Display` to return the canonical string. `PartialEq`/`Eq`/`Hash` on the canonical form directly.
|
||||
- Canonicalization in `ServerTarget::from_unix_path`: lexical cleanup of `.`/`..` components; no FS access. Use `Path::components()` + manual `PathBuf` reconstruction, or consider adding the `path-clean` crate if the hand-rolled version proves ugly (deferred — try stdlib first).
|
||||
- OOP-style methods on `ServerTarget` (replacing today's free helpers):
|
||||
- `target.loopback_classification() -> Result<LoopbackClassification, TargetSchemeError>` (was `is_loopback_or_unix_socket(&target)`)
|
||||
- `target.build_public_http_client() -> Result<(HttpClient, String)>` (was `build_public_http_client(&target)`)
|
||||
- Delete `ServerTargetKey` entirely. `AuthStore` will key by `ServerTarget` directly (Unit 7).
|
||||
- `cli_http_client_builder()` currently lives in `fabro-cli/src/user_config.rs`. It stays in `fabro-cli` — the user-agent string identifies the CLI specifically; other consumers of `fabro-client` will build their own `HttpClient` with their own UA. The builder API `Client::builder()` will accept a pre-built `HttpClient` when the caller wants control, or default to a bare `fabro_http::HttpClientBuilder::new()` for generic consumers.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/sse.rs` and `src/loopback_target.rs` — copy verbatim into new locations; these modules have no CLI-specific deps.
|
||||
- Error-classification pattern from `server_client.rs:1625-1790` — move wholesale with the rename.
|
||||
- `Url` canonicalization: `reqwest`/`url` crate's default behavior handles scheme lowercase, default port stripping. We add `trim_end_matches('/')` and `strip_suffix("/api/v1")` on top.
|
||||
- Lexical path cleaning: standard idiom is to iterate `Path::components()` and skip `.`, pop on `..`, otherwise append.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `ServerTarget::from_url("https://fabro.example.com/api/v1/")` and `ServerTarget::from_url("https://fabro.example.com")` produce equal values.
|
||||
- Happy path: `ServerTarget::from_url("https://EXAMPLE.COM/")`, `"https://example.com:443"`, and `"https://example.com"` all compare equal (migrates today's `https_normalization_collapses_equivalent_urls` test from `auth_store.rs:507`).
|
||||
- Happy path: `ServerTarget::from_url("http://127.0.0.1:80/")` and `"http://127.0.0.1"` compare equal (default-port strip for http).
|
||||
- Happy path: `ServerTarget::from_unix_path("/tmp/./foo/../fabro.sock")` canonicalizes to `ServerTarget::Unix("/tmp/fabro.sock")`.
|
||||
- Edge case: `ServerTarget::from_url("not a url")` returns a parse error.
|
||||
- Edge case: `ServerTarget::from_unix_path("relative/path")` returns an error (relative paths rejected — today's contract).
|
||||
- Edge case: two distinct URL inputs with different casing on scheme (`HTTPS://` vs `https://`) produce equal `ServerTarget`s.
|
||||
- Edge case: Unix paths with trailing `/` canonicalize identically to without it.
|
||||
- Happy path: `target.loopback_classification()` tests (migrate today's `is_loopback_or_unix_socket` tests from `loopback_target.rs`).
|
||||
- Happy path: `drain_sse_payloads` parsing tests (migrate today's tests from `sse.rs`).
|
||||
- Happy path: `ApiError` (ex-`HttpResponseFailure`) classification for 401/404/500 preserves status, body, and parsed error codes.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds after the shim is added to `fabro-cli`.
|
||||
- Migrated tests pass in `fabro-client`.
|
||||
- `grep -rn "HttpResponseFailure\|RunAttachEventStream\|CapturedArtifactInfo\|RefreshableOAuth\|ResolvedBearer\|ClientBundle\|ServerTargetKey" lib/` returns no results outside `docs/plans/` after all Phase 2 units complete. (This unit handles `HttpResponseFailure` and `ServerTargetKey`; others land in later units.)
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 7: Move `AuthStore`, `AuthEntry`, `StoredSubject` into `fabro-client`**
|
||||
|
||||
**Goal:** Relocate the file-locked OAuth token store, keyed by `ServerTarget` (not `ServerTargetKey`).
|
||||
|
||||
**Requirements:** R2, R6, R7.
|
||||
|
||||
**Dependencies:** Unit 6 (`ServerTarget` canonical-by-construction must exist).
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-client/src/auth_store.rs` — populate with `AuthStore`, `AuthEntry`, `StoredSubject`, `AuthStoreError`, `LockError`, adapted to key by `&ServerTarget` directly (via `ServerTarget::to_string()` as the on-disk key).
|
||||
- Modify: `lib/crates/fabro-client/src/lib.rs` — re-export `AuthStore`, `AuthEntry`, `StoredSubject`.
|
||||
- Modify: `lib/crates/fabro-cli/src/auth_store.rs` — replace content with `pub use fabro_client::{AuthStore, AuthEntry, StoredSubject};` shim. Deleted in Unit 10.
|
||||
- Modify: `lib/crates/fabro-cli/Cargo.toml` — add `fabro-client` dep; remove `fs2` (moves to `fabro-client`).
|
||||
- Modify: `lib/crates/fabro-client/Cargo.toml` — add `fs2 = "0.4"`.
|
||||
|
||||
**Approach:**
|
||||
- Wholesale move of `lib/crates/fabro-cli/src/auth_store.rs:1-440` (non-test code) into the new location.
|
||||
- `AuthStore` API changes:
|
||||
- `get(&self, target: &ServerTarget) -> ...` instead of `get(&self, key: &ServerTargetKey) -> ...`
|
||||
- Same for `put`, `remove`, `list` (returns `Vec<(ServerTarget, AuthEntry)>`)
|
||||
- On-disk key stored as `ServerTarget::to_string()` canonical form (which is what `ServerTargetKey::as_str()` returns today — bit-exact for HTTP targets, different for symlinked Unix sockets).
|
||||
- `AuthStoreError::InvalidServerTarget` becomes unreachable because `ServerTarget` is validated at construction — consider removing or keeping as defensive.
|
||||
- Move the test module too. Tests that constructed `ServerTargetKey::new(&target)` simplify to using the `ServerTarget` directly.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Preserve file-locking semantics (flock-based, currently via `fs2::FileExt`).
|
||||
- Preserve the `FABRO_AUTH_FILE` env override.
|
||||
- Default path resolution via `fabro_util::Home::from_env().root().join("auth.json")` stays identical.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: put/get round-trip for an HTTP target (migrated from `auth_store.rs` tests).
|
||||
- Happy path: put/get round-trip for a Unix-socket target.
|
||||
- Edge case: two HTTP URLs that differ only in trailing `/` or case canonicalize to the same key and collide on put (last write wins).
|
||||
- Edge case: list returns all stored entries sorted by key.
|
||||
- Integration: concurrent shared-lock readers don't deadlock with exclusive writers (migrate any existing test of this behavior).
|
||||
- Error path: corrupt JSON file surfaces `AuthStoreError::Corrupt`.
|
||||
- Security: after `put()`, the on-disk `auth.json` has mode `0o600` on Unix (permission bits exactly owner-rw).
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run -p fabro-client -p fabro-cli` passes.
|
||||
- No remaining `fabro_cli::auth_store::ServerTargetKey` references.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 8: Move `Client`, `Credential`, `OAuthSession`, and wire the connection builder**
|
||||
|
||||
**Goal:** Move the `Client` struct and all its wrapper methods into `fabro-client`, flatten `ClientBundle` inline, rename `RefreshableOAuth` → `OAuthSession`, rename `ResolvedBearer` → `Credential`, rename `RunAttachEventStream` → `RunEventStream`, and expose `Client::builder()` as the new connection API.
|
||||
|
||||
**Requirements:** R1, R2, R3, R5.
|
||||
|
||||
**Dependencies:** Units 1-4 (DTOs must be in `fabro-types`), Units 5-7 (crate, helpers, ServerTarget, AuthStore must exist).
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-client/src/credential.rs` — populate with `Credential { DevToken(String), OAuth(AuthEntry) }`, `bearer_token() -> &str`, and the `CredentialFallback` trait.
|
||||
- Modify: `lib/crates/fabro-client/src/session.rs` — populate with `OAuthSession { target, auth_store, fallback: Option<Box<dyn CredentialFallback>> }` and the `refresh_access_token` flow logic.
|
||||
- Modify: `lib/crates/fabro-client/src/client.rs` — populate with `Client` (state flattened, no `Bundle`), `Client::builder()`, `send_api`, `send_http`, `send_http_response`, all 40 typed method wrappers, `RunEventStream` (formerly `RunAttachEventStream`).
|
||||
- Modify: `lib/crates/fabro-client/src/lib.rs` — re-export `Client`, `Credential`, `OAuthSession`, `RunEventStream`, plus `pub mod types` → `pub use fabro_api::types;`.
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs` — replace entire content with `pub use fabro_client::{Client, RunEventStream, Credential, OAuthSession};` + any CLI-specific helpers that don't move (e.g., `load_dev_token_if_available`, `wait_for_local_dev_token`, `resolve_target_bearer`). File shrinks from 1941 → ~200 lines.
|
||||
- Modify: `lib/crates/fabro-cli/Cargo.toml` — remove deps now owned by `fabro-client` only (e.g., `progenitor-client`, `tokio-util`, `bytes` if no other CLI callers remain — verify).
|
||||
|
||||
**Approach:**
|
||||
- Flattening `ClientBundle`: `Client` becomes
|
||||
```text
|
||||
// Directional — not implementation
|
||||
pub struct Client {
|
||||
state: Arc<RwLock<ClientState>>,
|
||||
base_url: String,
|
||||
session: Option<OAuthSession>,
|
||||
refresh_lock: Arc<Mutex<()>>,
|
||||
}
|
||||
struct ClientState {
|
||||
api: fabro_api::ApiClient,
|
||||
http: fabro_http::HttpClient,
|
||||
bearer: Option<String>,
|
||||
}
|
||||
```
|
||||
The old `ClientBundle` name disappears; `ClientState` is private to the module.
|
||||
- `Client::builder()`: new public API. It becomes the underlying connection API. The CLI may keep thin `connect_*` orchestration wrappers around it (handled in Unit 9), but transport/session assembly should live in the builder path rather than being duplicated across wrappers.
|
||||
- `RunEventStream` rename: the struct, its `next_event`/`buffer_sse_events` methods, and the `VecDeque<EventEnvelope>` field. `EventEnvelope` is now `fabro_types::EventEnvelope`.
|
||||
- Method bodies: the 40 wrappers move verbatim. They call `send_api(|client| ...)` — `client` is the `fabro_api::ApiClient` from `ClientState`. `convert_type::<_, fabro_types::RunSummary>(...)` continues to bridge wire → domain.
|
||||
- `Client::from_http_client(base_url, http_client)` — public `pub fn` constructor for test use and non-builder callers. `Client::new_no_proxy(base_url)` may remain as a small convenience wrapper built on top of it.
|
||||
- Preserve `send_api`'s 401 → refresh → retry auto-logic. `OAuthSession` owns the refresh state it needs (`target`, `auth_store`, optional `fallback`); the actual refresh HTTP call uses a bespoke HTTP client built via `target.build_public_http_client()` (method on `ServerTarget`, not a free function — OOP style).
|
||||
- If preserving caller-specific transport behavior across refresh rebuilds requires it, `Client` may carry an internal `TransportConnector` helper that can rebuild the transport with the same customization after credentials change.
|
||||
- `CredentialFallback` trait lives in `fabro-client::credential`:
|
||||
```text
|
||||
// Directional — not implementation
|
||||
pub trait CredentialFallback: Send + Sync {
|
||||
fn resolve(&self) -> Option<Credential>;
|
||||
}
|
||||
```
|
||||
When refresh fails with missing/expired/revoked entry, `OAuthSession` consults `fallback.resolve()`. If `Some(Credential)`, the session rebuilds the client bundle with that credential; if `None`, it raises "session expired" and clears its auth-store entry as today. `fabro-cli` provides a concrete `CliDevTokenFallback` impl (in the CLI's auth layer) that wraps today's `load_dev_token_if_available` logic.
|
||||
- `target.loopback_classification() -> Result<LoopbackClassification, TargetSchemeError>` replaces today's `is_loopback_or_unix_socket(&target)` free helper. Used by `OAuthSession` to enforce the plain-HTTP/loopback guard before refresh.
|
||||
- `ensure_refresh_target_transport` and `refresh_transport_error` move with the refresh logic. They use `LoopbackClassification` (moved in Unit 6).
|
||||
- CLI-specific helpers that stay in `fabro-cli`: `load_dev_token_if_available`, `load_dev_token_if_available_from_sources`, `wait_for_local_dev_token`, `apply_bearer_token_auth`, `apply_dev_token_auth`, `build_authed_unix_socket_client`, `build_unix_socket_probe_client`, `try_connect_unix_socket_api_client_bundle`, `connect_unix_socket_api_client_bundle`, `check_server_ready`, `wait_for_server_ready`. These read fabro-server state on disk or stage dev tokens — CLI concerns. The `Client::builder()` in `fabro-client` offers sufficient primitives for the CLI to compose these around.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `send_api` generic wrapper pattern at `server_client.rs:603-632` — preserve its shape.
|
||||
- OAuth refresh flow at `server_client.rs:642-749` — preserve its error-path branching.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `Client::builder().target(http_target).connect()` produces a usable `Client` whose wrapped `fabro_api::ApiClient` points at the canonical base URL (derived from the target).
|
||||
- Happy path: `Client::builder().target(unix_target).connect()` produces a usable `Client` with `http://fabro` base URL and a Unix-socket-dialing `HttpClient`.
|
||||
- Happy path: call `Client::get_health()` against a mock HTTP server (`mockito` or similar) — fire and forget.
|
||||
- Happy path: each of the 40 wrapper methods continues to work (this is implicitly covered by the full `fabro-cli` integration test suite — no need for per-method unit tests).
|
||||
- Error path: 401 with `access_token_expired` code triggers refresh via `OAuthSession` (migrated from today's server-client tests).
|
||||
- Error path: refresh fails with `refresh_token_expired` → `AuthStore` entry is removed and session-expired error surfaces when no fallback is configured.
|
||||
- Error path: refresh fails with `refresh_token_expired` and a `CredentialFallback` returns `Some(Credential::DevToken(...))` → client rebuilds with the dev-token credential and the subsequent call succeeds. This preserves today's silent-degrade behavior for local dev targets.
|
||||
- Error path: refresh fails and `CredentialFallback::resolve()` returns `None` → session-expired error surfaces (same as no-fallback case).
|
||||
- Error path: `refresh_access_token` rejects plain-HTTP non-loopback targets (migrate the existing `refresh_access_token_rejects_plain_http_non_loopback_targets` test).
|
||||
- Error path: `refresh_access_token` against an HTTP target whose hostname resolves to loopback but isn't a loopback literal is rejected (classification is by literal authority, not DNS).
|
||||
- Happy path: `refresh_access_token` against `http://127.0.0.1:3000` and `http://[::1]:3000` succeeds (loopback literals accepted).
|
||||
- Happy path: `refresh_access_token` against `https://non-loopback.example.com` succeeds (HTTPS accepted regardless of host).
|
||||
- Security: `Credential::DevToken(...)`, `Credential::OAuth(entry)`, `OAuthSession`, and `AuthEntry` either do not derive `Debug` or their `Debug` output does not contain the raw token string.
|
||||
- Edge case: `RunEventStream::next_event` handles SSE chunk boundaries (migrated from today's sse.rs tests).
|
||||
- Integration: `fabro-cli` integration tests continue to pass against the real local `fabro server`. These prove the connection wire-up is correct without fabro-client needing its own integration server.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run --workspace` passes (4395 tests).
|
||||
- `cargo +nightly-2026-04-14 clippy -p fabro-client --all-targets -- -D warnings` clean.
|
||||
- `grep -rn "fabro_cli::server_client::" lib/` returns zero hits outside `fabro-cli/src/server_client.rs` (shim) — all external callers go through `fabro_client::...`.
|
||||
|
||||
### Phase 3 — Rewire `fabro-cli`
|
||||
|
||||
- [ ] **Unit 9: Rewire CLI orchestrator to use `Client::builder()`**
|
||||
|
||||
**Goal:** Update `connect_server_with_settings` and its helpers to build a `fabro_client::Client` via the new builder, pulling `Credential` and `OAuthSession` from CLI-owned sources (env vars, dev-token files, `AuthStore`).
|
||||
|
||||
**Requirements:** R8, R9.
|
||||
|
||||
**Dependencies:** Unit 8 (`Client::builder()` exists).
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs` — shrink the remaining file to just the orchestrator + CLI-specific helpers. Remove dead imports.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/{login,logout,status}.rs` — import `fabro_client::{AuthStore, AuthEntry, StoredSubject}` instead of `crate::auth_store::`.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/install.rs`, `src/commands/run/runner.rs`, and any other file currently importing `crate::server_client::{Client, RunEventStream, ...}` — update to `fabro_client::`.
|
||||
- Modify: `lib/crates/fabro-cli/src/user_config.rs` — `ServerTarget` moves to `fabro-client`; re-export from `user_config` for CLI convenience *or* update all in-crate call sites. Prefer the latter (update call sites) for cleanliness.
|
||||
|
||||
**Approach:**
|
||||
- `connect_server_with_settings(args, settings, base_config_path)` becomes roughly:
|
||||
1. Resolve `ServerTarget` from args + settings (CLI-owned).
|
||||
2. If Unix and no server responds to `/health`: call `start::ensure_server_running_on_socket` (CLI-owned).
|
||||
3. Build `Credential` from `FABRO_DEV_TOKEN` env / `AuthStore` OAuth entry / dev-token file (CLI-owned).
|
||||
4. Build optional `OAuthSession` if the credential is OAuth.
|
||||
5. `Client::builder().target(t).credential(c).oauth_session(s).connect().await`.
|
||||
- `resolve_target_bearer` stays (renamed to `resolve_credential`) but returns `fabro_client::Credential` and calls into `fabro_client::AuthStore`.
|
||||
- `build_public_http_client(target) -> (HttpClient, String)` moves to `fabro-client` (as an inherent method on `ServerTarget` or a module-level helper) because `OAuthSession::refresh_access_token` is its only caller after the split. This is UA-neutral: the refresh call deliberately does not stamp the CLI's user-agent onto OAuth-server traffic. `cli_http_client_builder` is distinct — it stays in `fabro-cli` and applies the `fabro-cli/{version}` user-agent to command traffic from this binary. The two coexist for different purposes; the names communicate the intent.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Today's `connect_managed_unix_socket_api_client_bundle` at `server_client.rs:219-251` shows the try-connect-fail-autostart-retry pattern. Preserve it.
|
||||
- Today's `connect_local_api_client_bundle` at `server_client.rs:253-282` shows the CLI's storage-first flow. Preserve it.
|
||||
|
||||
**Test scenarios:**
|
||||
- Integration: `fabro-cli` integration tests continue to pass. No new unit tests needed — behavior is unchanged from the user's perspective.
|
||||
- Happy path: the three current `connect_*` flows (with-settings, target-direct, local-storage) still produce working clients. Covered by existing tests in `fabro-cli/tests/it/`.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `grep -rn "crate::auth_store\|crate::server_client" lib/crates/fabro-cli/src/ --include="*.rs"` returns only the shrunk `server_client.rs` and `auth_store.rs` shim files themselves.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 10: Delete moved fabro-cli modules and clean up shims**
|
||||
|
||||
**Goal:** Remove the transitional shim files and dead code from `fabro-cli`. Final dep-list cleanup.
|
||||
|
||||
**Requirements:** R9.
|
||||
|
||||
**Dependencies:** Unit 9 (all callers must already use `fabro_client::...` imports).
|
||||
|
||||
**Files:**
|
||||
- Delete: `lib/crates/fabro-cli/src/sse.rs`
|
||||
- Delete: `lib/crates/fabro-cli/src/loopback_target.rs`
|
||||
- Delete: `lib/crates/fabro-cli/src/auth_store.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs` — trim to only the CLI-specific orchestrator + helpers. Likely ends up ~200-400 lines.
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs` or `src/lib.rs` — remove `pub mod sse;`, `pub mod loopback_target;`, `pub mod auth_store;`.
|
||||
- Modify: `lib/crates/fabro-cli/Cargo.toml` — remove deps now used only by `fabro-client` (`fs2`, possibly `progenitor-client`, `tokio-util`, `bytes`, `rand` if no other consumer — verify each by grep).
|
||||
|
||||
**Approach:**
|
||||
- Delete the shim files that were added in Units 6-8.
|
||||
- Verify no residual references to the deleted modules: `grep -rn "mod sse\|mod loopback_target\|mod auth_store" lib/crates/fabro-cli/`.
|
||||
- Dep cleanup: for each candidate-removed dep in `fabro-cli/Cargo.toml`, grep `lib/crates/fabro-cli/src/` for direct usage. Remove only if no usage remains.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Previous dep-cleanup pattern from `docs/plans/2026-04-20-001-fix-cli-server-same-host-assumptions-plan.md` — audit Cargo.toml against direct usage.
|
||||
|
||||
**Test scenarios:**
|
||||
- Test expectation: none — pure deletion. Existing tests provide the regression safety net.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` clean (catches unused deps via `unused_crate_dependencies` if enabled, or via `cargo machete` optionally).
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `ls lib/crates/fabro-cli/src/` no longer shows `sse.rs`, `loopback_target.rs`, or `auth_store.rs`.
|
||||
|
||||
### Phase 4 — Verification
|
||||
|
||||
- [ ] **Unit 11: Full workspace verification**
|
||||
|
||||
**Goal:** Confirm the refactor is complete, clean, and behaviorally identical.
|
||||
|
||||
**Requirements:** R9.
|
||||
|
||||
**Dependencies:** Units 1-10.
|
||||
|
||||
**Files:**
|
||||
- None modified; pure verification.
|
||||
|
||||
**Approach:**
|
||||
- Run the full verification matrix from this repo's `CLAUDE.md`:
|
||||
- `cargo +nightly-2026-04-14 fmt --check --all`
|
||||
- `cargo build --workspace`
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings`
|
||||
- `cargo nextest run --workspace`
|
||||
- Confirm dep graph: `cargo tree -p fabro-client | grep -E "fabro-(cli|store|workflow|server|config)"` returns no rows.
|
||||
- Confirm no leaked old names: `grep -rn "ClientBundle\|RefreshableOAuth\|ResolvedBearer\|HttpResponseFailure\|RunAttachEventStream\|CapturedArtifactInfo\|ServerTargetKey" lib/ --include="*.rs"` returns zero.
|
||||
- Confirm doc `docs/reference/` and `docs/administration/` don't mention removed internals.
|
||||
|
||||
**Test scenarios:**
|
||||
- Test expectation: none — this unit runs existing tests.
|
||||
|
||||
**Verification:**
|
||||
- All four verification commands pass.
|
||||
- Both grep checks return empty.
|
||||
- `cargo tree -p fabro-client` deps align with the Target graph in the High-Level Technical Design section.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** The touched crates are `fabro-types` (gains DTOs), `fabro-store` (loses DTOs, keeps free-function reducers over `fabro_types::RunProjection`), `fabro-workflow` (`CapturedArtifactInfo` → `ArtifactUpload`), `fabro-retro` (imports shift), `fabro-server` (imports shift), `fabro-cli` (loses the 1941-line `server_client.rs`; the residual orchestrator still depends on `fabro-server` for `Bind`, `fabro-config` for `Storage`, and other CLI-scoped crates — "the client surface moves out; CLI orchestration stays"), `fabro-client` (new). Downstream test crates (`fabro-test`, `test/twin/openai`, `test/twin/github`) should not need changes since they don't import from the moved modules — verify during implementation.
|
||||
- **Error propagation:** `ApiError` (ex-`HttpResponseFailure`) is now in `fabro-client`. CLI commands that match on its fields (`status`, `body`, `headers`) continue to work via re-export; no behavior change.
|
||||
- **State lifecycle risks:** `AuthStore` file format is unchanged for HTTP targets (same canonicalization). For Unix-socket targets, the switch from `fs::canonicalize` to lexical-only means existing keys with symlinked socket paths may no longer match after the change. Acceptable per user direction ("We don't care about migration"); users with OAuth sessions against symlinked sockets will re-login.
|
||||
- **API surface parity:** No wire-format changes. OpenAPI spec unchanged. `fabro-server` continues to emit the same JSON for `EventEnvelope` and `RunSummary` responses.
|
||||
- **Integration coverage:** Existing `fabro-cli` integration tests exercise every code path — 4395 tests provide strong safety net. No new integration tests needed.
|
||||
- **Unchanged invariants:**
|
||||
- Subprocess autostart (`fabro server` self-spawn) remains a CLI concern.
|
||||
- Dev-token-from-disk loading (reads `~/.fabro/dev-token`, storage-dir dev-token, fabro-server pidfile record) stays CLI-owned.
|
||||
- TOML-driven `[cli.target]` resolution stays in `fabro-cli/src/user_config.rs`.
|
||||
- OAuth login browser-popup flow (`fabro auth login`) stays in `fabro-cli`.
|
||||
- The CLI's `ServerTargetArgs`, `ServerConnectionArgs`, and command-context plumbing (`command_context.rs`) are untouched.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| `EventEnvelope` restructure breaks a serde consumer that relied on `payload.as_value()` round-tripping unknown JSON. | OpenAPI already defines the wire shape as `seq + RunEvent flattened` — all wire consumers already get the typed shape. `EventPayload` stays in `fabro-store` for write-path validation, so the store-internal round-trip is preserved. Compiler drives CLI/server read-path updates. |
|
||||
| `RunProjection` extension-trait split requires `use fabro_store::RunProjectionReducer;` at call sites that invoke reducer methods. | One added `use` per file (~5-6 files); call sites keep method-call syntax unchanged. |
|
||||
| `ServerTarget` canonical form diverges from today's `ServerTargetKey::as_str()` for symlinked Unix sockets, invalidating existing `AuthStore` entries. | Accepted per user direction. HTTP target canonicalization is bit-identical to today's, so most users are unaffected. |
|
||||
| `fabro-client` ends up with a leaky CLI dep we didn't catch (e.g., the `cli_http_client_builder` user-agent string or a hidden `fabro_util::Home` call). | Unit 11 grep check + `cargo tree -p fabro-client` dep-graph audit catches any leak. `fabro-util` is an allowed dep (we need `Home` for `AuthStore` default); the check is "no `fabro-cli`, `fabro-store`, `fabro-workflow`, `fabro-server`, `fabro-config`". |
|
||||
| Tests in `fabro-cli/tests/it/` rely on `Client::new_no_proxy` via internal visibility. | Replace with `fabro_client::Client::from_http_client(base_url, http_client)` public constructor + local CLI test helper that wraps `no_proxy()` builder. |
|
||||
| Phased rollout leaves `fabro-cli` in a partially-migrated state if we stop after Phase 2. | Each phase compiles and tests pass at its boundary. If we stop mid-refactor, the shim layer keeps `fabro-cli` working. But we shouldn't stop mid-refactor — commit the whole thing. |
|
||||
| `fabro-store::EventPayload` validation semantics subtly change if Unit 2 restructures how events are built server-side. | Server-side write path stays in `fabro-store` and continues to use `EventPayload::new` for validation. Only the read-path return type changes. Unit 2 explicitly calls this out. |
|
||||
| `progenitor-client` version drift between `fabro-api` (0.13) and `fabro-client`'s direct use. | Match versions exactly. Check today's `fabro-cli/Cargo.toml` to confirm `progenitor-client = "0.13"`; copy that version literal. |
|
||||
|
||||
## Security Considerations
|
||||
|
||||
This is a pure refactor — no new endpoints, data stores, or attack surface. However, security-sensitive code is moving, so preserve these invariants across the move:
|
||||
|
||||
- **`auth.json` file mode.** `AuthStore::put` must write the file with mode `0600` on Unix (owner read/write only). Add or carry forward whatever umask/`OpenOptions::mode` the current implementation uses, and add a unit test asserting the resulting permission bits after `put()`. Do not assume umask handles this; set it explicitly.
|
||||
- **Refresh-flow plain-HTTP/loopback guard.** The guard that refuses to send refresh-token credentials over plaintext HTTP to non-loopback targets (today's `ensure_refresh_target_transport` + `is_loopback_or_unix_socket`) is being split across `loopback.rs` (Unit 6), `session.rs` (Unit 8), and `target.rs` canonicalization (Unit 6). Beyond migrating the existing `refresh_access_token_rejects_plain_http_non_loopback_targets` test, add Unit 8 scenarios for: (a) refresh against `https://non-loopback` succeeds; (b) refresh against an IP literal that happens to be loopback (e.g., `http://127.0.0.1:3000`) succeeds; (c) refresh against a hostname that resolves to loopback but is not a loopback literal is rejected (classification is based on literal authority, not DNS — preserve that).
|
||||
- **`Debug`/`Display` impls on token-bearing types.** `Credential` (holds raw bearer strings), `OAuthSession` (carries `AuthStore` which holds `AuthEntry`), and `AuthEntry` must not derive `Debug` in a form that prints token bytes. Either don't derive `Debug` at all, or implement it manually to redact `access_token`/`refresh_token` fields (use `fabro-util`'s redaction helper if it suits). Add one unit test per secret-bearing type asserting the `Debug` output does not contain a known fixture token. The `Open Questions` entry about `Client` deriving `Debug` is resolved here for the token-bearing types: do not auto-derive anything that prints tokens.
|
||||
- **`ServerTarget` symlink trust boundary.** Switching from `fs::canonicalize` to lexical canonicalization means the `ServerTarget` key is a best-effort identity, not a security boundary — two symlinked paths that point to the same socket now compare unequal, and a third-party-writable symlink could cause an `AuthStore` lookup against path A to return a token that's presented to a socket opened via path B. This is fine for the intended operating model (fabro's socket lives under user-controlled `~/.fabro/` and the user trusts that directory). Document this as an explicit assumption in the `fabro-client` crate docs so a future consumer choosing a non-home socket path understands the trust boundary.
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- No user-facing documentation changes. Reference docs (`docs/reference/`, `docs/administration/`) describe the CLI from the outside; internal crate reorganization is invisible to users.
|
||||
- No rollout / monitoring / migration concerns — pure refactor.
|
||||
- Consider adding a `lib/crates/fabro-client/README.md` later that describes the crate's purpose and points to integration examples. Deferred to follow-up work (not part of this plan).
|
||||
- The file `CLAUDE.md`'s "Rust crates" inventory at line 43 mentions `fabro-cli`, `fabro-workflow`, `fabro-agent`, `fabro-server`, etc. Add a one-line entry for `fabro-client` during Unit 5 or 11.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin document:** No `ce:brainstorm` requirements doc — this plan was scoped directly through conversation. Problem frame, decisions, and scope were confirmed interactively.
|
||||
- **Prior plans in the same subsystem:**
|
||||
- `docs/plans/2026-04-20-001-fix-cli-server-same-host-assumptions-plan.md` — tightened the CLI/server target contract; this plan continues that direction.
|
||||
- `docs/plans/2026-04-05-cli-deglobalize-server-url-and-storage-dir-plan.md` — made target resolution explicit; precondition for this extraction.
|
||||
- `docs/plans/2026-04-02-002-feat-http-store-client-auto-start-plan.md` — introduced the autostart logic this plan explicitly keeps in `fabro-cli`.
|
||||
- **Primary code:**
|
||||
- `lib/crates/fabro-cli/src/server_client.rs`
|
||||
- `lib/crates/fabro-cli/src/auth_store.rs`
|
||||
- `lib/crates/fabro-cli/src/loopback_target.rs`
|
||||
- `lib/crates/fabro-cli/src/sse.rs`
|
||||
- `lib/crates/fabro-cli/src/user_config.rs`
|
||||
- `lib/crates/fabro-store/src/types.rs`
|
||||
- `lib/crates/fabro-store/src/run_state.rs`
|
||||
- `lib/crates/fabro-workflow/src/artifact_snapshot.rs`
|
||||
- **OpenAPI contract:** `docs/api-reference/fabro-api.yaml:3452-3461` (EventEnvelope schema confirms `seq + RunEvent flattened` wire shape).
|
||||
|
|
@ -1,725 +0,0 @@
|
|||
---
|
||||
title: "refactor: Extract Record/Repository abstractions in fabro-store"
|
||||
type: refactor
|
||||
status: completed
|
||||
date: 2026-04-20
|
||||
origin: docs/brainstorms/2026-04-20-fabro-store-record-abstractions-requirements.md
|
||||
---
|
||||
|
||||
# refactor: Extract Record/Repository abstractions in fabro-store
|
||||
|
||||
## Overview
|
||||
|
||||
`fabro-store` currently has four hand-written `Slate*Store` types (`SlateAuthCodeStore`, `SlateAuthTokenStore`, blob plumbing on `RunDatabase`, free functions in `catalog.rs`) that each duplicate the same K/V plumbing on top of SlateDB: key construction, JSON serialization, get/put/delete/scan loops, optional per-key consume mutex, optional GC-by-prefix-scan. This plan replaces that duplication with a thin reusable typed K/V layer (`Repository<R: Record>`) plus per-record wrapper Stores that hold any domain-specific helpers (consume locks, replay caches, etc.).
|
||||
|
||||
The Run aggregate (event log, projection cache, broadcast channel) stays as it is. Only the simple K/V records (RefreshToken, AuthCode, Blob, RunCatalogEntry) move to the new shape.
|
||||
|
||||
This is a greenfield refactor — no production deployments, backwards-compat can be broken freely (see origin: `docs/brainstorms/2026-04-20-fabro-store-record-abstractions-requirements.md`).
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Adding a new persisted record type today requires copying ~200 LOC of plumbing into a new `Slate*Store` and editing names. Each copy is one more place where serialization, locking, or key encoding can drift. As more record families land (sessions, vault entries, agent state), the duplication compounds.
|
||||
|
||||
The brainstorm's chosen response: a `Record` trait + `Repository<R>` typed K/V layer + named domain `*Store` wrappers + a security boundary that's designed once for the whole crate (see origin Key Decisions).
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
All requirements traced from the origin document.
|
||||
|
||||
- **R1.** `trait Record` with associated `type Id: RecordId`, `type Codec: Codec<Self>` (no default — explicit per impl), `const PREFIX: &'static str`, and `fn id(&self) -> Self::Id`. `PREFIX` MUST be a non-empty `/`-separated path of non-empty segments — no leading or trailing `/`, no empty segments, `/` is reserved within a segment. `Repository::new` `debug_assert!`s the constraint. (origin R1)
|
||||
- **R2.** `trait RecordId: Sized { fn key_segments(&self) -> Vec<String>; fn from_key_segments(segs: &[&str]) -> Result<Self>; }` with built-in impls for `[u8; 32]` (hex), `String`, `RunBlobId`, and `RunId` (date + ulid). `from_key_segments` is the parse counterpart used by `Repository::scan_stream` and `scan_ids_stream` — the only path to reconstruct `R::Id` from the SlateDB key for both value-carrying records and ZST marker records (e.g. `RunCatalogEntry`). Implementations of `key_segments` MUST NOT include the `\0` byte in any returned segment. `Repository` validates this **at runtime** before assembling any SlateKey (in `put`/`put_at`/`get`/`delete`/`exists`/scan-prefix construction): a segment containing `\0` returns `Err(Error::InvalidKeySegment)` rather than silently corrupting the keyspace. Validation is one byte scan per segment per call — negligible vs the SlateDB op. (origin R2 — extended at plan time)
|
||||
- **R3.** `trait Codec<R>` with three built-in implementations: `JsonCodec` (literal `serde_json` forwarding for value-carrying records), `RawBytesCodec` (byte-identity for `Blob`), `MarkerCodec` (for ZST marker records — `encode(_) -> Vec::new()`, `decode(&[]) -> R::default()`; bound `R: Default + Sized`). Snapshot test on a stable synthetic struct locks the `JsonCodec` wire format. **Wire-format change tracking:** `RefreshToken` JSON wire format is byte-identical to today (literal serde_json forward). `AuthCode` JSON wire format gains a new `code` field per R7 — acceptable under greenfield. (origin R3)
|
||||
- **R4.** `Repository<R>` (`pub(crate)`) exposes:
|
||||
- For value-carrying records: `get(&id)`, `put(&r)`, `delete(&id)`, `scan_stream() -> Stream<(R::Id, R)>`, `scan_prefix_stream(extra_segments)`, `gc(predicate)`.
|
||||
- For all records (including markers): `put_at(&id, &r)` (writes a key derived from the explicit id rather than from `r.id()`; `put` becomes sugar for `put_at(&r.id(), r)`), `exists(&id) -> bool`, `scan_ids_stream() -> Stream<R::Id>` (keys-only enumeration; doesn't touch values). Marker records (`R::Codec = MarkerCodec`) interact with `Repository` exclusively through the id-only API: `put_at`, `delete`, `exists`, `scan_ids_stream`. (origin R4 — extended at plan time)
|
||||
- **R5.** Named domain `*Store` wrappers; `Repository` field is private; security boundary against external callers walking sensitive tables. (origin R5)
|
||||
- **R6.** `RefreshTokenStore` keeps existing API; `consume_and_rotate` uses `transaction(...)` under `KeyedMutex` guard; replay cache stays in-memory. (origin R6)
|
||||
- **R7.** `AuthCodeStore` keeps observable behaviour but `insert` changes signature from `insert(code: &str, entry: AuthCode)` to `insert(entry: AuthCode)` since `AuthCode` now carries its own `code` field (per the brainstorm decision). All existing callers update their construction pattern: compute the code, then construct `AuthCode { code, identity, ... }` in one literal. This is a public API change accepted under greenfield. (origin R7 — clarified at plan time)
|
||||
- **R8.** `BlobStore` exposes `read`/`write`/`exists` (no `delete`, no `list`/`scan` — see R5 boundary). `RunDatabase::write_blob` and `RunDatabase::read_blob` keep signatures and delegate to `BlobStore`. `RunDatabase::list_blobs` keeps signature and continues using its existing free-function key scan path until/unless a future record needs blob enumeration through `Repository`. (origin R8 — clarified at plan time)
|
||||
- **R9.** `RunCatalogIndex` exposes `add(&run_id)` (writes a `RunCatalogEntry` marker key), `remove(&run_id)`, `list(query)` (uses `Repository::scan_ids_stream` to enumerate marker keys, applies query filter, sorts by `(year, month, day, hour, minute, run_id)` per `catalog.rs:39-49`). Replaces `catalog.rs` free functions. `RunCatalogEntry` is a ZST marker (no fields); the run id lives only in the key. (origin R9 — extended at plan time)
|
||||
- **R10.** `transaction(&db, |tx| ...)` helper, `pub(crate)`, `FnOnce`, single-batch atomic write, encode errors short-circuit; fault-injection test required. (origin R10)
|
||||
- **R11.** `Database` exposes five accessors (lazy `OnceCell` init): `blobs()` lands in U2b, `catalog_index()` in U4, `auth_codes()` is preserved in U5, `refresh_tokens()` (renamed from `auth_tokens()`) lands in U6, `runs()` is unchanged. (origin R11)
|
||||
- **R12.** `RunDatabase`'s event-sourcing machinery + public method signatures unchanged. `Database` consumes `RunCatalogIndex`. `RunDatabase::write_blob`/`read_blob` delegate to `BlobStore` (per R8); `RunDatabase::list_blobs` keeps its current free-function path. (origin R12 — clarified at plan time)
|
||||
- **R13.** `KeyedMutex<K>` extracted as shared helper; cleanup-under-shard-lock invariant; never exposes the inner Arc. (origin R13)
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Run aggregate event-sourcing machinery (`RunDatabase` event log, projection cache, broadcast channel, `recover_next_seq`, `EventProjectionCache`, atomic seq counter) is not refactored.
|
||||
- No marker capability traits (`ExpiringRecord`, `ConsumableRecord`, `IndexedRecord`, `ContentAddressed`).
|
||||
- No record schema versioning or migration framework.
|
||||
- No swap-out of the storage backend (still SlateDB on `Arc<dyn ObjectStore>`).
|
||||
- No changes to `ArtifactStore` or other non-SlateDB storage.
|
||||
- No changes to public `Database::create_run` / `open_run` / `delete_run` / `list_runs` API signatures or observable behaviour. Internals consume new `RunCatalogIndex` per R12.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs` — `SlateAuthTokenStore`, the most complex existing store (consume_and_rotate with WriteBatch, KeyedMutex, replay cache).
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs` — `SlateAuthCodeStore`, mirror of the same pattern minus replay cache.
|
||||
- `lib/crates/fabro-store/src/slate/run_store.rs:283-302` — `RunDatabase::write_blob`/`read_blob`/`list_blobs`, today's blob plumbing.
|
||||
- `lib/crates/fabro-store/src/slate/catalog.rs` — three free functions (`write_index`, `delete_index`, `list_run_ids`) called from `Database::create_run`/`list_runs`/`delete_run`.
|
||||
- `lib/crates/fabro-store/src/slate/mod.rs` — `Database` (lazy `OnceCell` per store), `Runs` accessor, run lifecycle methods that thread catalog calls.
|
||||
- `lib/crates/fabro-store/src/keys.rs` — `SlateKey` builder (`pub(crate)`, `\0`-separated segments), per-record key constructors, parse helpers. **Stays `pub(crate)`** under R2's data-only `key_segments()` design.
|
||||
- `lib/crates/fabro-store/src/lib.rs` — current `pub use` re-exports of `Slate*Store` types.
|
||||
|
||||
### Pattern: lazy store init via `OnceCell`
|
||||
|
||||
Today (`slate/mod.rs:208-228`):
|
||||
|
||||
```text
|
||||
auth_codes: Arc<OnceCell<Arc<SlateAuthCodeStore>>>
|
||||
auth_tokens: Arc<OnceCell<Arc<SlateAuthTokenStore>>>
|
||||
```
|
||||
|
||||
`Database::auth_codes()` / `auth_tokens()` use `get_or_try_init` to construct the store with `Arc::new(self.open_db().await?)`. New `BlobStore`, `RunCatalogIndex` follow the same shape. No new pattern needed.
|
||||
|
||||
### Pattern: KeyedMutex (today inlined per store)
|
||||
|
||||
Both `auth_tokens.rs:85-118` and `auth_codes.rs:48-77` carry the same `DashMap<K, Arc<Mutex<()>>>` + clone Arc + lock + decide-on-drop-via-strong-count==2 pattern. R13 extracts it.
|
||||
|
||||
### Pattern: today's WriteBatch usage
|
||||
|
||||
`auth_tokens.rs:101-110` builds one `slatedb::WriteBatch`, puts both keys, calls `db.write(batch).await?`. The `transaction(...)` helper preserves this exact shape — single batch, single commit.
|
||||
|
||||
### External References
|
||||
|
||||
None — this is an internal refactor. SlateDB API is already understood from existing usage. No new dependencies.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
No prior `docs/solutions/` entries on this topic — first refactor of this kind in `fabro-store`.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
Most decisions carry forward from the origin Key Decisions section.
|
||||
|
||||
- **Two worlds**: Run aggregate stays as-is; only K/V records move to `Repository<R>`. (origin)
|
||||
- **Hand-written `*Store` wrappers on a thin `Repository`**, no marker capability traits. (origin)
|
||||
- **Multi-segment IDs via data-only `key_segments() -> Vec<String>`**: keeps `SlateKey` `pub(crate)`. (origin)
|
||||
- **Codec specified explicitly per impl** (no associated-type default): avoids unstable `associated_type_defaults`. (origin)
|
||||
- **`transaction(...)` is `pub(crate)`**, single-batch atomic, `FnOnce`. Wrapper Stores compose it via domain-named methods. (origin)
|
||||
- **Repository for security-sensitive records is store-private** (`pub(crate)` Repository, `pub(super)` field on the wrapper Store). External boundary enforced by visibility; internal discipline by code review. (origin + pass-2 review)
|
||||
|
||||
Plan-time additions:
|
||||
|
||||
- **KeyedMutex location**: `lib/crates/fabro-store/src/keyed_mutex.rs` (top-level module, not under `slate/`, since it's not slatedb-specific). Resolves origin deferred Q1.
|
||||
- **Migration order** (resolves origin deferred Q2): U1 (KeyedMutex precursor) and U2a (trait scaffolding + Repository + transaction) are independent and can land in either order. U2b (Blob + BlobStore + Database::blobs) follows U2a. Then U3, U4, U5, U6 can be parallelized. U7 closes with re-exports + fabro-server cleanup. Each unit lands as one commit; each compiles and tests pass independently. See dependency graph in Implementation Units.
|
||||
- **Per-Repository batch helper deferred** (resolves origin deferred Q3): not added in this refactor. Only `transaction(...)` ships. If profiling shows the cross-record machinery cost is meaningful for the single-type case, add later.
|
||||
- **Module organization**: traits + Repository + Tx live in a new top-level `record/` module (`lib/crates/fabro-store/src/record/{mod,codec,repository,transaction}.rs`); per-record wrapper Stores stay under `slate/` (since they're slatedb-bound). `KeyedMutex` is its own top-level module.
|
||||
- **`AuthCode` schema change**: `code` becomes the first field. JSON shape changes by one field. Acceptable under greenfield; test fixtures update mechanically.
|
||||
- **Test approach**: continue the existing pattern — real SlateDB on `object_store::memory::InMemory`, no mocks (per repo `CLAUDE.md` testing posture and existing `auth_tokens.rs:194-201` style).
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Where does `KeyedMutex` live?** → `lib/crates/fabro-store/src/keyed_mutex.rs` (top-level module).
|
||||
- **Migration order?** → U1 + U2a parallelizable → U2b → U3, U4, U5, U6 parallelizable → U7. See Implementation Units dependency graph.
|
||||
- **Per-Repository batch helper?** → Deferred, not in this refactor.
|
||||
- **Module organization for traits?** → New `record/` module at `lib/crates/fabro-store/src/record/`.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Exact internal types for `Tx`** — whether it owns or borrows the `WriteBatch`, whether `put` returns `&mut Self` for chaining. Mechanical; affects no caller. The contract (`FnOnce`, single commit, encode short-circuit) is fixed in R10.
|
||||
- **Stream adapter for `scan_stream`** — `slatedb::DbIterator` exposes `async fn next(&mut self)` but does not impl `Stream`. Implementer chooses between `futures::stream::unfold`, a hand-rolled `poll_next`, or returning the iterator directly behind a thin newtype. None affect callers; pick the simplest that types cleanly.
|
||||
- **`gc(predicate)` exact signature for the closure capture lifetime** — `impl Fn(&R) -> bool` may need a `+ Send` bound depending on how the stream-and-batch implementation interleaves with `Send` futures. Implementer adjusts at the type-error site.
|
||||
- **Whether `BlobStore` lives at `lib/crates/fabro-store/src/slate/blob_store.rs` or a deeper path** — file location is mechanical.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
### Trait scaffolding shape
|
||||
|
||||
```text
|
||||
trait Record: Sized + Send + Sync + 'static {
|
||||
type Id: RecordId;
|
||||
type Codec: Codec<Self>;
|
||||
const PREFIX: &'static str; // "/"-separated, split by Repository
|
||||
fn id(&self) -> Self::Id;
|
||||
}
|
||||
|
||||
trait RecordId: Sized {
|
||||
fn key_segments(&self) -> Vec<String>;
|
||||
fn from_key_segments(segs: &[&str]) -> Result<Self>;
|
||||
}
|
||||
|
||||
trait Codec<R> {
|
||||
fn encode(r: &R) -> Result<Vec<u8>>;
|
||||
fn decode(bytes: &[u8]) -> Result<R>;
|
||||
}
|
||||
|
||||
// Built-in codecs
|
||||
struct JsonCodec; // literal forward to serde_json::to_vec / from_slice
|
||||
struct RawBytesCodec; // identity on bytes — encode(&Blob(bytes)) returns bytes; decode(bytes) returns Blob(bytes)
|
||||
struct MarkerCodec; // for ZST marker records (R: Default + Sized) — encode(_) -> Vec::new(); decode(&[]) -> R::default()
|
||||
|
||||
// Built-in RecordId impls (each implements both directions)
|
||||
impl RecordId for [u8; 32] { /* key_segments: vec![hex(self)]; from_key_segments: parse hex */ }
|
||||
impl RecordId for String { /* key_segments: vec![self.clone()]; from_key_segments: clone segs[0] */ }
|
||||
impl RecordId for RunBlobId { /* one hex segment, both directions */ }
|
||||
impl RecordId for RunId { /* key_segments: [<YYYY-MM-DD>, <ulid>]; from_key_segments: parse segs[1] */ }
|
||||
```
|
||||
|
||||
### Repository shape
|
||||
|
||||
```text
|
||||
pub(crate) struct Repository<R: Record> {
|
||||
db: Arc<slatedb::Db>,
|
||||
_r: PhantomData<R>,
|
||||
}
|
||||
|
||||
impl<R: Record> Repository<R> {
|
||||
// Value-carrying API
|
||||
pub(crate) async fn get(&self, id: &R::Id) -> Result<Option<R>>;
|
||||
pub(crate) async fn put(&self, r: &R) -> Result<()>; // sugar for put_at(&r.id(), r)
|
||||
pub(crate) async fn delete(&self, id: &R::Id) -> Result<()>;
|
||||
pub(crate) fn scan_stream(&self) -> impl Stream<Item = Result<(R::Id, R)>>;
|
||||
pub(crate) fn scan_prefix_stream(&self, extra: &[&str]) -> impl Stream<Item = Result<(R::Id, R)>>;
|
||||
pub(crate) async fn gc(&self, predicate: impl Fn(&R) -> bool) -> Result<u64>;
|
||||
|
||||
// Id-only API — works for any record, required for ZST marker records
|
||||
pub(crate) async fn put_at(&self, id: &R::Id, r: &R) -> Result<()>;
|
||||
pub(crate) async fn exists(&self, id: &R::Id) -> Result<bool>;
|
||||
pub(crate) fn scan_ids_stream(&self) -> impl Stream<Item = Result<R::Id>>;
|
||||
pub(crate) fn scan_prefix_ids_stream(&self, extra: &[&str]) -> impl Stream<Item = Result<R::Id>>;
|
||||
}
|
||||
|
||||
// Marker (index) record example
|
||||
#[derive(Default)]
|
||||
pub(crate) struct RunCatalogEntry; // ZST — id lives only in the key
|
||||
|
||||
impl Record for RunCatalogEntry {
|
||||
type Id = RunId;
|
||||
type Codec = MarkerCodec;
|
||||
const PREFIX: &'static str = "runs/_index/by-start";
|
||||
fn id(&self) -> RunId { unreachable!("marker — use put_at(&id, &RunCatalogEntry)") }
|
||||
}
|
||||
|
||||
// RunCatalogIndex usage:
|
||||
// add(&run_id) -> repo.put_at(&run_id, &RunCatalogEntry).await
|
||||
// remove(&run_id) -> repo.delete(&run_id).await
|
||||
// list(query) -> repo.scan_ids_stream().filter(query).sort()
|
||||
```
|
||||
|
||||
### transaction shape
|
||||
|
||||
```text
|
||||
pub(crate) async fn transaction<T, F>(db: &slatedb::Db, f: F) -> Result<T>
|
||||
where F: FnOnce(&mut Tx) -> Result<T>
|
||||
{
|
||||
let mut tx = Tx::new();
|
||||
let value = f(&mut tx)?; // closure Err → return early, no DB write
|
||||
db.write(tx.into_batch()).await?; // exactly one commit
|
||||
Ok(value)
|
||||
}
|
||||
|
||||
pub(crate) struct Tx { batch: WriteBatch }
|
||||
impl Tx {
|
||||
pub(crate) fn put<R: Record>(&mut self, r: &R) -> Result<&mut Self> { ... }
|
||||
pub(crate) fn delete<R: Record>(&mut self, id: &R::Id) -> Result<&mut Self> { ... }
|
||||
}
|
||||
```
|
||||
|
||||
### Wrapper Store shape (RefreshTokenStore example)
|
||||
|
||||
```text
|
||||
pub struct RefreshTokenStore {
|
||||
db: Arc<slatedb::Db>, // for transaction(...)
|
||||
repo: Repository<RefreshToken>, // pub(super) at most
|
||||
consume_locks: KeyedMutex<[u8; 32]>,
|
||||
replay_revocations: DashMap<[u8; 32], DateTime<Utc>>, // in-memory only
|
||||
}
|
||||
|
||||
impl RefreshTokenStore {
|
||||
pub async fn consume_and_rotate(...) -> Result<ConsumeOutcome> {
|
||||
let _guard = self.consume_locks.lock(presented_hash).await;
|
||||
let existing = self.repo.get(&presented_hash).await?;
|
||||
match existing {
|
||||
None => Ok(ConsumeOutcome::NotFound),
|
||||
Some(token) if now >= token.expires_at => Ok(ConsumeOutcome::Expired),
|
||||
Some(token) if token.used => Ok(ConsumeOutcome::Reused(token)),
|
||||
Some(token) => {
|
||||
let mut old = token.clone();
|
||||
old.used = true;
|
||||
old.last_used_at = now;
|
||||
transaction(&self.db, |tx| {
|
||||
tx.put(&old)?;
|
||||
tx.put(&new_token)?;
|
||||
Ok(())
|
||||
}).await?;
|
||||
Ok(ConsumeOutcome::Rotated(old, Box::new(new_token)))
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
U1[U1: KeyedMutex extraction]
|
||||
U2a[U2a: Traits + Repository + transaction]
|
||||
U2b[U2b: Blob + BlobStore + Database::blobs]
|
||||
U3[U3: RunDatabase blob delegation]
|
||||
U4[U4: RunCatalogIndex; delete catalog.rs]
|
||||
U5[U5: AuthCodeStore migration]
|
||||
U6[U6: RefreshTokenStore migration; transaction wired in]
|
||||
U7[U7: Re-exports + fabro-server import cleanup]
|
||||
|
||||
U2a --> U2b
|
||||
U2b --> U3
|
||||
U2a --> U4
|
||||
U2a --> U5
|
||||
U2a --> U6
|
||||
U1 --> U5
|
||||
U1 --> U6
|
||||
U2b --> U7
|
||||
U3 --> U7
|
||||
U4 --> U7
|
||||
U5 --> U7
|
||||
U6 --> U7
|
||||
```
|
||||
|
||||
U1 and U2a are independent of each other and can land in either order. U2b depends on U2a. U3 depends on U2b (it needs `BlobStore`). U4, U5, U6 each depend on U2a (they need `Repository` and `transaction`); U5 and U6 also depend on U1 (`KeyedMutex`). U3, U4, U5, U6 can be parallelized after their dependencies land. U7 is the final cleanup pass.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 1: Extract `KeyedMutex<K>` shared helper**
|
||||
|
||||
**Goal:** Move the per-key `DashMap<K, Arc<Mutex<()>>>` + auto-cleanup-at-strong-count-2 pattern out of `auth_tokens.rs` and `auth_codes.rs` into a single shared helper. No behaviour change.
|
||||
|
||||
**Requirements:** R13.
|
||||
|
||||
**Dependencies:** None. Independent precursor PR.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-store/src/keyed_mutex.rs`
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs` (add `mod keyed_mutex;` + `pub(crate) use`)
|
||||
- Modify: `lib/crates/fabro-store/src/slate/auth_tokens.rs` (replace `refresh_locks: DashMap<...>` field + inline lock pattern with `consume_locks: KeyedMutex<[u8; 32]>`)
|
||||
- Modify: `lib/crates/fabro-store/src/slate/auth_codes.rs` (replace `code_locks: DashMap<...>` similarly)
|
||||
- Test: `lib/crates/fabro-store/src/keyed_mutex.rs` (unit tests inline)
|
||||
|
||||
**Approach:**
|
||||
- `KeyedMutex<K: Hash + Eq + Clone>` exposes only `pub async fn lock(&self, key: K) -> Guard<'_>`.
|
||||
- `Guard<'_>` holds the `Arc<Mutex<()>>` internally, releases the inner `Mutex` on drop, then performs the cleanup check (strong_count == 2 → remove from `DashMap`).
|
||||
- The cleanup check and entry insertion happen under the same `DashMap` shard lock — use `DashMap::entry().and_modify().or_insert_with()` or equivalent so a concurrent `lock(&key)` cannot observe a stale Arc.
|
||||
- No public access to the inner `Arc`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:85-118` (today's inline pattern — preserve semantics).
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs:48-77` (mirror pattern).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Happy path:* `lock(K1)` then `lock(K2)` proceed independently (no contention between distinct keys).
|
||||
- *Edge case:* `lock(K1)` from two tasks serializes — second waits until first drops Guard.
|
||||
- *Edge case:* Auto-cleanup — after the only outstanding Guard drops, the `DashMap` no longer contains the entry for that key (verified via internal accessor or by counting `len()`).
|
||||
- *Integration:* Stress test — 16 concurrent tasks `lock(K)` on the same key; verify exactly one progresses at a time and the map is empty after all complete.
|
||||
- *Integration race regression:* Stress test that hammers the same key from N tasks across many drop cycles — verify two threads cannot acquire `lock(&key)` and end up with different `Mutex` instances (cleanup-under-shard-lock invariant).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-store` passes.
|
||||
- `auth_tokens.rs` and `auth_codes.rs` no longer carry their inline `refresh_locks` / `code_locks` fields and inline lock plumbing.
|
||||
- All existing concurrent_consume_has_one_winner / concurrent_rotation_has_one_winner tests pass unmodified.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2a: Trait scaffolding (`Record`, `RecordId`, `Codec`, `Repository`, `transaction`)**
|
||||
|
||||
**Goal:** Land the new abstraction with a synthetic test-only Record exercising the full `Repository` API and the `transaction(...)` atomicity contract. No production consumer yet.
|
||||
|
||||
**Requirements:** R1, R2, R3, R4, R5 (boundary spec), R10 (transaction).
|
||||
|
||||
**Dependencies:** None. Independent of U1; either order fine.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-store/src/record/mod.rs` (re-exports `Record`, `RecordId`)
|
||||
- Create: `lib/crates/fabro-store/src/record/codec.rs` (`trait Codec<R>`, `JsonCodec`, `RawBytesCodec`, `MarkerCodec`)
|
||||
- Create: `lib/crates/fabro-store/src/record/repository.rs` (`Repository<R>` and methods)
|
||||
- Create: `lib/crates/fabro-store/src/record/transaction.rs` (`Tx`, `transaction()`)
|
||||
- Create: `lib/crates/fabro-store/src/record/record_id.rs` (built-in `impl RecordId` for `[u8; 32]`, `String`, `RunId`, `RunBlobId` — both `key_segments` and `from_key_segments` directions)
|
||||
- Modify: `lib/crates/fabro-store/src/error.rs` — add a new public variant `Error::InvalidKeySegment { segment: String }` returned by `Repository` key-assembly when a `RecordId::key_segments` impl produces a segment containing the `\0` separator byte. Also add `Error::KeyParse(String)` returned by `Repository::scan_stream` / `scan_ids_stream` when `RecordId::from_key_segments` rejects the parsed segments.
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs` (add `mod record;`, `pub(crate) use record::...;`)
|
||||
- Test: `lib/crates/fabro-store/src/record/repository.rs` (unit tests with a synthetic test-only Record to exercise get/put/delete/scan_stream/scan_prefix_stream/gc)
|
||||
- Test: `lib/crates/fabro-store/src/record/transaction.rs` (unit tests for `transaction(...)` including encode-failure fault injection)
|
||||
- Test: `lib/crates/fabro-store/src/record/codec.rs` (snapshot test for `JsonCodec` byte-identity using a stable synthetic struct via `insta::assert_snapshot!`)
|
||||
|
||||
**Approach:**
|
||||
- `Record::PREFIX` is a `&'static str` containing `/`-separated segments (`"auth/refresh"`, `"blobs/sha256"`, etc.). `Repository` splits on `/` once and writes `\0`-separated `SlateKey` segments. `/` is reserved inside any single segment. **Key-assembly invariant (runtime-enforced):** `Repository` checks every segment (PREFIX-derived OR id-derived) for `\0` before assembling the SlateKey, in every operation that constructs a key (`put`/`put_at`/`get`/`delete`/`exists`/scan-prefix). A segment containing `\0` returns `Err(Error::InvalidKeySegment { segment: String })`. This is a runtime error, not a `debug_assert!` — release builds get the same protection. Adds one byte-scan per segment per call (negligible).
|
||||
- `Repository::scan_stream` adapts `slatedb::DbIterator::next` into `impl Stream<Item = Result<(R::Id, R)>>` via `futures::stream::unfold` or hand-rolled `poll_next` (implementer's choice). For each scanned entry: parse the SlateDB key into segments (split on `\0`), strip the `R::PREFIX` segments, pass the remaining segments to `R::Id::from_key_segments` to reconstruct the typed Id; decode the value via `R::Codec::decode`; yield `(id, value)`. For ZST marker records using `MarkerCodec`, decode is trivially `R::default()` — yielding `(id, marker)` where the marker carries no data and the id from the key is the actual information.
|
||||
- `Repository::scan_ids_stream` is a keys-only variant: same key-parsing as `scan_stream`, but skips value bytes entirely (yields `Stream<Item = Result<R::Id>>`). Required for ZST marker records (where `decode` would be wasted), useful as a perf optimization for any record where the caller only needs ids.
|
||||
- `Repository::put_at(id, &r)` is the explicit-id put: writes the key derived from `id` (not from `r.id()`). `Repository::put(&r)` is sugar for `put_at(&r.id(), r)`. ZST markers use `put_at` exclusively because they don't carry an id (their `Record::id` is `unreachable!`).
|
||||
- `Repository::gc(predicate)` scans the prefix, decodes each value, evaluates the (sync, no-I/O) predicate, collects matching keys into a `Vec`, then issues a single `slatedb::WriteBatch` containing all deletes. Returns the count.
|
||||
- `JsonCodec::encode` is literally `serde_json::to_vec(value)`; `decode` is `serde_json::from_slice(bytes)`. The implementation IS the byte-identity proof. Snapshot test guards against accidental future changes.
|
||||
- `MarkerCodec::encode<R>(_: &R) -> Ok(Vec::new())`; `decode<R: Default>(bytes) -> Ok(R::default())` (asserts `bytes.is_empty()`).
|
||||
- `transaction(&db, f)` runs `f(&mut tx)`. On `Err`, returns the error without writing anything. On `Ok`, calls `db.write(tx.into_batch()).await`. `Tx::put` calls `R::Codec::encode(value)` and pushes onto the batch — encode errors propagate via `?` from inside the closure. `Tx::put_at(&id, &r)` is the explicit-id variant for ZST markers.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/mod.rs:208-228` (`OnceCell`-based store accessor on `Database`).
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:79-121` (single `WriteBatch` + single `db.write` — `transaction(...)` mirrors this).
|
||||
- `lib/crates/fabro-store/src/keys.rs:11-23` (`SlateKey` builder usage — `Repository` calls these `pub(crate)` methods).
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:194-201` (test fixture pattern: `Database::new(Arc::new(InMemory::new()), "", Duration::from_millis(1), None)` then `db.<store>().await.unwrap()`).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Happy path (Repository):* `put` then `get` returns the same value; `delete` then `get` returns `None`.
|
||||
- *Happy path (scan_stream):* `put` 5 records, `scan_stream().collect()` yields all 5 with correct `(id, value)` pairs.
|
||||
- *Happy path (scan_prefix_stream):* records under different sub-prefixes filter correctly.
|
||||
- *Happy path (gc):* `put` 10 records, `gc(|r| predicate true for half)` deletes 5, returns count 5; `scan_stream` confirms 5 remain.
|
||||
- *Edge case (Repository):* `get` on missing id returns `None`; `delete` on missing id is a no-op.
|
||||
- *Edge case (Repository):* empty prefix scan returns empty stream.
|
||||
- *Error path (Codec):* malformed bytes from `decode` propagate as `Error::Other` (or whatever the existing error type is).
|
||||
- *Error path (transaction):* closure returns `Err` → `db.write` is NOT called (verify via store state unchanged after).
|
||||
- *Error path (transaction fault injection):* in the test module, define `TestRecord` with `type Codec = TestFailCodec;` where `TestFailCodec::encode` returns `Err` on a poisoned input. Run `transaction(&db, |tx| { tx.put(&good)?; tx.put(&poisoned)?; Ok(()) })` and assert: (1) the helper returns `Err`, (2) `db.get(key_for(&good))` returns `None`, (3) `db.get(key_for(&poisoned))` returns `None`. This proves the all-or-nothing invariant against the encode-error-mid-batch path (not just the closure-Err short-circuit). **Required by R10.**
|
||||
- *Edge case (transaction):* empty closure (no puts/deletes) → no batch commit overhead, returns `Ok`.
|
||||
- *Happy path (MarkerCodec / ZST marker):* define a synthetic `TestMarker` ZST + `impl Record for TestMarker { type Codec = MarkerCodec; ... }`. `repo.put_at(&id, &TestMarker)` then `repo.exists(&id) == true`; `repo.scan_ids_stream().collect()` yields the id; `repo.delete(&id)` then `exists == false`.
|
||||
- *Edge case (key-assembly invariant):* in release builds, `RecordId::key_segments` returning a string containing `\0` causes the next `Repository` op to return `Err(Error::InvalidKeySegment)` rather than silently corrupting the keyspace. Test asserts the error is returned and the DB is unchanged.
|
||||
- *Snapshot (JsonCodec byte-identity):* `insta::assert_snapshot!(std::str::from_utf8(&JsonCodec::encode(&sample)?).unwrap())` against a fixed synthetic struct with deterministic timestamps and IDs. Locks the JSON wire format string itself; any future change to `JsonCodec` (envelope, version tag, field reordering) fails the snapshot.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-store` passes including the new synthetic-record tests.
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` passes.
|
||||
- `Repository<R>` and `transaction` are `pub(crate)`; the `record/` module is internal to `fabro-store`.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2b: `Blob` record + `BlobStore` wrapper + `Database::blobs()` accessor**
|
||||
|
||||
**Goal:** First production consumer of the new abstraction. Land `BlobStore` and the `Database::blobs()` accessor. `RunDatabase::write_blob` continues to use the raw DB this unit (delegation lands in U3).
|
||||
|
||||
**Requirements:** R5 (boundary applied to first wrapper), R8 (`BlobStore` API), R11 (`Database::blobs()`).
|
||||
|
||||
**Dependencies:** U2a.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-store/src/slate/blob_store.rs` (`Blob` record + `BlobStore` wrapper)
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs` (public re-export of `BlobStore` and `Blob`)
|
||||
- Modify: `lib/crates/fabro-store/src/slate/mod.rs` (`Database` gets `blobs: Arc<OnceCell<Arc<BlobStore>>>` field + `Database::blobs() -> Result<Arc<BlobStore>>` accessor)
|
||||
- Test: `lib/crates/fabro-store/src/slate/blob_store.rs` (unit tests inline)
|
||||
|
||||
**Approach:**
|
||||
- `Blob(pub Bytes)` newtype. `impl Record for Blob { type Id = RunBlobId; type Codec = RawBytesCodec; const PREFIX = "blobs/sha256"; fn id(&self) -> RunBlobId { RunBlobId::new(&self.0) } }`. (`RunBlobId::new(content)` is the actual constructor in `lib/crates/fabro-types/src/run_blob_id.rs`; it computes the sha256 internally.)
|
||||
- `BlobStore` wraps `Repository<Blob>`. `Repository` field is private. No `.scan_stream()` or `.gc()` exposed.
|
||||
- `Database::blobs()` follows the existing `auth_codes()`/`auth_tokens()` pattern at `slate/mod.rs:208-228`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/mod.rs:208-228` (`OnceCell`-based store accessor on `Database`).
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:194-201` (test fixture pattern: `Database::new(Arc::new(InMemory::new()), "", Duration::from_millis(1), None)`).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Happy path:* `write(bytes_a)` returns `id_a`; `read(&id_a)` returns `Some(bytes_a)`; `write(bytes_a)` again returns the same `id_a` (content-addressed); `exists(&id_a) == true`, `exists(&unknown) == false`.
|
||||
- *Edge case:* `write(empty bytes)` succeeds; reading back returns `Some(empty)`.
|
||||
- *Integration (no delete):* `BlobStore` exposes no `delete` — verified at compile time by the absence of the method.
|
||||
- *Integration (cross-path equivalence with raw DB):* a blob written via `BlobStore::write(bytes)` is byte-identical when read directly from SlateDB via `db.get(blob_key(&id))`. Locks the invariant that `RawBytesCodec::encode` is byte-identity (no envelope, no length prefix). The same equivalence is checked end-to-end in U3 once `RunDatabase::write_blob` delegates.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-store` passes including new tests.
|
||||
- `Database::blobs()` returns an `Arc<BlobStore>` and supports the round-trip tests.
|
||||
- Existing tests (including `delete_run_keeps_global_cas_blobs` at `slate/mod.rs:451-466`) still pass — `RunDatabase::write_blob` continues to use the raw DB this unit, so no existing observable behaviour changes.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 3: `RunDatabase` blob methods delegate to `BlobStore`**
|
||||
|
||||
**Goal:** Internal refactor only — `RunDatabase::write_blob` and `RunDatabase::read_blob` keep their public signatures and delegate to `BlobStore`. `RunDatabase::list_blobs` is **not touched**; it keeps its existing free-function key-scan path at `run_store.rs:365-380` since `BlobStore` intentionally has no `list` method per R8's boundary. No callers change. No tests change. (If a future record needs blob enumeration through `Repository`, `BlobStore::list_ids` could be added later via `Repository::scan_ids_stream`; out of scope for this refactor.)
|
||||
|
||||
**Requirements:** R8 (delegation), R12 (`RunDatabase` public surface unchanged).
|
||||
|
||||
**Dependencies:** U2b.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-store/src/slate/run_store.rs` — `write_blob` and `read_blob` only. Each constructs a stack-local `BlobStore::new(self.inner.db.clone())` and delegates. `list_blobs` is left exactly as-is. No `RunDatabaseInner` field changes. No constructor signature changes. No `Database::create_run`/`open_run`/`open_run_reader` changes.
|
||||
|
||||
**Approach:**
|
||||
- `RunDatabase` keeps the raw `Db` field as today. `write_blob` and `read_blob` construct a stack-local `BlobStore` from the existing `Arc<Db>` and delegate (~24-byte stack alloc per call; `BlobStore` is stateless). `list_blobs` is unchanged — it continues calling the existing free function at `run_store.rs:365-380`.
|
||||
- Existing `delete_run_keeps_global_cas_blobs` test (`slate/mod.rs:451-466`) MUST continue to pass — it accesses blobs through `RunDatabase::write_blob`/`read_blob` and the test is the canonical contract that blobs survive run deletion.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/run_store.rs:283-302` (today's `write_blob`/`read_blob` bodies — preserve return types and error behavior; only the implementation changes).
|
||||
- `lib/crates/fabro-store/src/slate/run_store.rs:365-380` (today's `list_blobs` free function — left untouched).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Integration:* `RunDatabase::write_blob(bytes)` followed by `RunDatabase::read_blob(&id)` returns `Some(bytes)` (existing behaviour).
|
||||
- *Integration:* `Database::create_run` → `run.write_blob` → `Database::delete_run` → blob still readable via a different run's `read_blob` (the `delete_run_keeps_global_cas_blobs` invariant).
|
||||
- *Integration:* `RunDatabase::list_blobs` returns the same set as before for a run that wrote N blobs.
|
||||
|
||||
**Verification:**
|
||||
- All existing tests in `lib/crates/fabro-store/src/slate/mod.rs` pass unmodified.
|
||||
- `RunDatabase::write_blob`/`read_blob`/`list_blobs` signatures and behaviour are observably unchanged (no caller in `fabro-workflow`, `fabro-server`, etc. needs updating).
|
||||
- `cargo nextest run --workspace` passes.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 4: `RunCatalogIndex` replaces `catalog.rs`**
|
||||
|
||||
**Goal:** Migrate the three free functions in `catalog.rs` to a `RunCatalogIndex` wrapper Store on top of `Repository<RunCatalogEntry>`. Wire `Database::create_run`/`list_runs`/`delete_run` to use it. Delete `catalog.rs`.
|
||||
|
||||
**Requirements:** R9 (`RunCatalogIndex` API + sort matches today), R12 (catalog calls live on `Database`), R11 (`Database::catalog_index()`).
|
||||
|
||||
**Dependencies:** U2a.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-store/src/slate/run_catalog_index.rs` (`RunCatalogEntry` record + `RunCatalogIndex` wrapper)
|
||||
- Modify: `lib/crates/fabro-store/src/slate/mod.rs`:
|
||||
- Add `catalog_index: Arc<OnceCell<Arc<RunCatalogIndex>>>` field on `Database`
|
||||
- Add `Database::catalog_index()` accessor
|
||||
- `Database::create_run` (lines 119, 127) replaces `catalog::write_index(&db, run_id).await?` with `self.catalog_index().await?.add(run_id).await?`
|
||||
- `Database::list_runs` (line 169) replaces `catalog::list_run_ids(&db, query).await?` with `self.catalog_index().await?.list(query).await?`
|
||||
- `Database::delete_run` (line 204) replaces `catalog::delete_index(&db, run_id).await?` with `self.catalog_index().await?.remove(run_id).await?`
|
||||
- Delete: `lib/crates/fabro-store/src/slate/catalog.rs`
|
||||
- Modify: `lib/crates/fabro-store/src/slate/mod.rs` (remove `mod catalog;` import; remove the test-side `use catalog::*` if any)
|
||||
- Test: `lib/crates/fabro-store/src/slate/run_catalog_index.rs` (unit tests inline)
|
||||
|
||||
**Approach:**
|
||||
- `RunCatalogEntry` is a ZST marker: `#[derive(Default)] pub(crate) struct RunCatalogEntry;`. `Record::Id = RunId`, `Codec = MarkerCodec`, `PREFIX = "runs/_index/by-start"`. `id(&self)` is `unreachable!("marker — use put_at(&id, &RunCatalogEntry)")` since the marker carries no id.
|
||||
- `impl RecordId for RunId` writes two segments: `<YYYY-MM-DD>` (from `self.created_at().format("%Y-%m-%d")`) followed by `self.to_string()`. `from_key_segments` parses the ULID from `segs[1]` (the date segment is redundant — derivable from the ULID timestamp).
|
||||
- `RunCatalogIndex::add(&RunId)` calls `repo.put_at(&run_id, &RunCatalogEntry).await`. Value bytes are empty per `MarkerCodec`.
|
||||
- `RunCatalogIndex::remove(&RunId)` calls `repo.delete(&run_id).await`.
|
||||
- `RunCatalogIndex::list(query)` uses `repo.scan_ids_stream()` to enumerate marker keys (no value decoding — cheap), collects into a `Vec<RunId>`, filters by `query.start`/`query.end` against `run_id.created_at()` (today's logic at `catalog.rs:27-37`), and sorts by `(year, month, day, hour, minute, run_id)` — the same key as `catalog.rs:39-49`.
|
||||
- `Database::list_runs`'s post-list summary-building loop (lines 170-183) is **NOT** absorbed into `RunCatalogIndex` — only the catalog scan + filter + sort move. The summary loop stays in `Database` because it needs `RunDatabase::has_any_events` and `RunDatabase::build_summary`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/catalog.rs:7-50` (today's three functions — preserve filter and sort semantics exactly).
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs::SlateAuthCodeStore::new` (wrapper Store construction signature).
|
||||
- `lib/crates/fabro-store/src/slate/mod.rs:208-228` (`OnceCell` accessor pattern).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Happy path:* `add(run_id_1); add(run_id_2); list(default query)` returns both, sorted by `(year, month, day, hour, minute, run_id)` ascending exactly per `catalog.rs:39-49`. Existing `create_open_list_and_delete_full_lifecycle_in_shared_db` test (`slate/mod.rs:421-447`) is the canonical regression — it MUST pass with identical output before and after migration.
|
||||
- *Edge case:* `list` with `query.start` set later than all `run_id.created_at()` returns empty.
|
||||
- *Edge case:* `list` with `query.end` set earlier than all `run_id.created_at()` returns empty.
|
||||
- *Edge case:* `add(run_id); remove(run_id); list()` returns empty.
|
||||
- *Integration:* `Database::create_run(rid_1); Database::list_runs(default)` returns the run summary (full integration through `Database` — verifies the migration didn't break the surface).
|
||||
- *Integration:* `Database::delete_run(rid_1); Database::list_runs(default)` no longer returns it.
|
||||
- *Integration:* All existing tests in `slate/mod.rs::tests` (notably `create_open_list_and_delete_full_lifecycle_in_shared_db`, `delete_run_keeps_global_cas_blobs`, `reopening_store_rebuilds_from_shared_db`) pass unmodified.
|
||||
|
||||
**Verification:**
|
||||
- `lib/crates/fabro-store/src/slate/catalog.rs` is deleted.
|
||||
- `cargo nextest run -p fabro-store` passes.
|
||||
- `Database::list_runs` produces identical results to the pre-refactor state for the same input.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 5: Migrate `AuthCodeStore` to `Repository<AuthCode>`; add `code` field to `AuthCode`**
|
||||
|
||||
**Goal:** Refactor `SlateAuthCodeStore` → `AuthCodeStore` on top of `Repository<AuthCode>` and `KeyedMutex<String>`. Add `code: String` as the first field of `AuthCode` so `Record::id` can return it. Update insert/consume signatures and call sites.
|
||||
|
||||
**Requirements:** R7 (API + struct change), R5 (security boundary), R13 (uses KeyedMutex from U1).
|
||||
|
||||
**Dependencies:** U1, U2a.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-store/src/slate/auth_codes.rs`:
|
||||
- Rename `SlateAuthCodeStore` → `AuthCodeStore`
|
||||
- Add `code: String` as first field of `AuthCode`
|
||||
- `impl Record for AuthCode { type Id = String; type Codec = JsonCodec; const PREFIX = "auth/code"; fn id(&self) -> String { self.code.clone() } }`
|
||||
- Refactor `insert(code: &str, entry: AuthCode)` → `insert(&self, entry: AuthCode)` per R7 (the `entry` now carries its own `code`; one-arg form is the chosen signature)
|
||||
- Refactor `consume(&self, code: &str)` to use `self.repo.get(&code.to_string())` then `self.repo.delete(...)` under `KeyedMutex` guard
|
||||
- Refactor `gc_expired(&self, cutoff)` to use `self.repo.gc(|entry| entry.expires_at <= cutoff)`
|
||||
- Field changes: drop `db: Arc<slatedb::Db>` (now via `repo`); drop `code_locks: DashMap<...>` (now via `consume_locks: KeyedMutex<String>`)
|
||||
- Modify: `lib/crates/fabro-store/src/slate/mod.rs`:
|
||||
- Rename the field `auth_codes: Arc<OnceCell<Arc<SlateAuthCodeStore>>>` → `Arc<OnceCell<Arc<AuthCodeStore>>>`
|
||||
- Update `Database::auth_codes()` return type
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs`: drop `SlateAuthCodeStore` from `pub use`; add `AuthCodeStore` and `AuthCode`; **add temporary alias** `pub type SlateAuthCodeStore = AuthCodeStore;` so `fabro-server` keeps compiling until U7 lands. (Without this alias the workspace breaks between U5 and U7.)
|
||||
- Modify: `lib/crates/fabro-server/src/auth/cli_flow.rs:1226` (OAuth code-mint AuthCode literal — add `code: code.clone()` as first field; reorder so `code` is computed before the literal). After this change, the call switches from `store.insert(&code, entry)` (today's `auth_codes.rs:41`) to `store.insert(entry)` per R7.
|
||||
- Modify: `lib/crates/fabro-server/src/auth/cli_flow.rs:1390` (test fixture AuthCode literal)
|
||||
- Modify: `lib/crates/fabro-server/tests/it/api/cli_auth_token.rs:82` (test fixture AuthCode literal)
|
||||
- Test: `lib/crates/fabro-store/src/slate/auth_codes.rs` (existing test module updates to construct `AuthCode { code: "...", ... }` — `auth_codes.rs:126`)
|
||||
|
||||
**Approach:**
|
||||
- The `code` field becomes the first field of `AuthCode` so the JSON shape is `{"code":"...","identity":...,...}` — adds one field to the wire format. Greenfield → acceptable.
|
||||
- `AuthCodeStore::insert(entry)` calls `self.repo.put(&entry)` (no extra arg needed since `entry.code` carries the key).
|
||||
- `AuthCodeStore::consume(code)` takes `&str`, holds `consume_locks.lock(code.to_string())` guard, then `repo.get(&code.to_string())`, branches on expiry/found, deletes via `repo.delete(&code.to_string())`. Single-use semantics preserved.
|
||||
- `gc_expired` is one line via `repo.gc(|c| c.expires_at <= cutoff)`.
|
||||
- Repository field is `pub(super)` per R5 boundary.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs:33-100` (preserve API behavior).
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs:103-200` (existing test patterns — update for new struct shape, otherwise preserve).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Happy path:* `insert(AuthCode { code, ... })` then `consume(&code)` returns the entry and a second `consume` returns `None` (single-use).
|
||||
- *Edge case:* `consume` on a non-existent code returns `None`.
|
||||
- *Edge case:* `consume` on an expired code deletes the row and returns `None` (today's behaviour at `auth_codes.rs:67-71`).
|
||||
- *Error path:* none surfaced by today's code beyond serde errors — preserve.
|
||||
- *Integration:* All existing `auth_codes.rs` tests pass with updated struct construction (e.g., `concurrent_consume_has_one_winner` at `auth_codes.rs:152` MUST still pass — KeyedMutex preserves single-winner behaviour).
|
||||
- *Integration (boundary):* `AuthCodeStore`'s `repo` field is not accessible from outside the wrapper (compile-time check via test that the field is private; or simply: no public method on `AuthCodeStore` returns `&Repository<AuthCode>`).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-store` passes.
|
||||
- `cargo nextest run -p fabro-server` passes (if server uses `AuthCode` struct literally; update imports per U7 if needed).
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs` no longer imports `slatedb::Db` directly.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 6: Migrate `RefreshTokenStore` to `Repository<RefreshToken>` + `transaction(...)` for `consume_and_rotate`**
|
||||
|
||||
**Goal:** The most complex migration. Refactor `SlateAuthTokenStore` → `RefreshTokenStore` on top of `Repository<RefreshToken>` and `KeyedMutex<[u8; 32]>`. Replace the hand-built `slatedb::WriteBatch` in `consume_and_rotate` with `transaction(&db, ...)`. Preserve replay revocation cache as in-memory only. R10 atomicity is verified by U2a's transaction-layer fault-injection test (no separate U6 fault-injection test — see Execution note).
|
||||
|
||||
**Requirements:** R6 (API + transaction usage + replay cache invariant), R5 (security boundary), R10 (transaction atomicity), R13 (KeyedMutex).
|
||||
|
||||
**Dependencies:** U1, U2a.
|
||||
|
||||
**Execution note:** `consume_and_rotate` is security-sensitive. The R10 atomicity contract is exercised by U2a's transaction-layer fault-injection test using a synthetic test-only `Record` + `Codec` whose `encode` fails on the second `put` (`RefreshToken` cannot itself trigger a JSON encode failure). U6 keeps the existing `concurrent_rotation_has_one_winner` (`auth_tokens.rs:311`) test as the consume-layer atomicity regression net.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-store/src/slate/auth_tokens.rs`:
|
||||
- Rename `SlateAuthTokenStore` → `RefreshTokenStore`
|
||||
- `impl Record for RefreshToken { type Id = [u8; 32]; type Codec = JsonCodec; const PREFIX = "auth/refresh"; fn id(&self) -> [u8; 32] { self.token_hash } }`
|
||||
- Refactor `insert_refresh_token(token)` → uses `self.repo.put(&token)`
|
||||
- Refactor `find_refresh_token(&hash)` → uses `self.repo.get(&hash)`
|
||||
- Refactor `consume_and_rotate(presented_hash, new_token, now)` → uses `transaction(&self.db, |tx| { tx.put(&old_token)?; tx.put(&new_token)?; Ok(()) })` while holding `consume_locks.lock(presented_hash)` guard. Outcomes (`Rotated`, `Reused`, `Expired`, `NotFound`) preserved exactly.
|
||||
- Refactor `delete_chain(chain_id)` → uses `self.repo.gc(|t| t.chain_id == chain_id)`
|
||||
- Refactor `gc_expired(cutoff)` → uses `self.repo.gc(|t| t.expires_at <= cutoff)`
|
||||
- Field changes: drop `refresh_locks: DashMap<...>` (now `consume_locks: KeyedMutex<[u8; 32]>`); keep `replay_revocations: DashMap<[u8; 32], DateTime<Utc>>` UNCHANGED (in-memory only per R6). Add a doc-comment on the `replay_revocations` field: `/// In-memory only by design (origin R6) — persisting attacker-supplied hashes adds an unbounded-growth surface under token-stuffing attack with no security benefit. Do NOT migrate to Repository<R>.` so future contributors don't "complete the abstraction" by routing this through a persisted Repository.
|
||||
- `mark_refresh_token_replay` and `was_recently_replay_revoked` keep their existing impls — they touch only the in-memory `DashMap`.
|
||||
- Modify: `lib/crates/fabro-store/src/slate/mod.rs` (rename field type; update `Database::auth_tokens()` → `Database::refresh_tokens()` per R11; **add temporary inherent shim** `pub async fn auth_tokens(&self) -> Result<Arc<RefreshTokenStore>> { self.refresh_tokens().await }` so existing `fabro-server` callers compile until U7 removes them.)
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs`: drop `SlateAuthTokenStore` from `pub use`; add `RefreshTokenStore` and `RefreshToken`; **add temporary alias** `pub type SlateAuthTokenStore = RefreshTokenStore;` so `fabro-server` keeps compiling until U7 lands.
|
||||
- Modify: `lib/crates/fabro-store/src/slate/auth_tokens.rs:201` (the in-crate test fixture call `db.auth_tokens().await.unwrap()` → `db.refresh_tokens().await.unwrap()`)
|
||||
- Test: `lib/crates/fabro-store/src/slate/auth_tokens.rs` (preserve all existing tests; the U2a transaction-layer fault-injection test covers R10)
|
||||
|
||||
**Approach:**
|
||||
- `RefreshTokenStore` holds `db: Arc<slatedb::Db>` (for `transaction`), `repo: Repository<RefreshToken>` (`pub(super)`), `consume_locks: KeyedMutex<[u8; 32]>`, `replay_revocations: DashMap<[u8; 32], DateTime<Utc>>`.
|
||||
- `consume_and_rotate` flow:
|
||||
1. `let _guard = self.consume_locks.lock(presented_hash).await;`
|
||||
2. `let existing = self.repo.get(&presented_hash).await?;`
|
||||
3. Branch on `None` / expired / used / proceed exactly as today.
|
||||
4. For the "proceed" branch: clone `existing` as `old_token`, set `used = true`, `last_used_at = now`. Then `transaction(&self.db, |tx| { tx.put(&old_token)?; tx.put(&new_token)?; Ok(()) }).await?`.
|
||||
5. Return `ConsumeOutcome::Rotated(old_token, Box::new(new_token))`.
|
||||
6. Mutex strong-count cleanup happens via `KeyedMutex` per U1 — no inline check here.
|
||||
- Replay cache: `mark_refresh_token_replay` and `was_recently_replay_revoked` stay as-is. R6 explicitly forbids moving them into `Repository<R>`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:79-121` (today's `consume_and_rotate` — preserve outcomes and ordering exactly; only the WriteBatch construction moves into `transaction(...)`).
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:123-161` (today's `delete_chain` and `gc_expired` — both collapse to `repo.gc(predicate)` calls).
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs:163-178` (replay revocation methods — preserve unchanged).
|
||||
|
||||
**Test scenarios:**
|
||||
- *Happy path:* `insert_refresh_token(t1); find_refresh_token(&hash) == Some(t1)`.
|
||||
- *Happy path (rotation):* `insert(old); consume_and_rotate(old_hash, new, now)` returns `Rotated(old_used, new)`; both `find(&old_hash)` and `find(&new_hash)` succeed; `old.used == true`.
|
||||
- *Edge case (NotFound):* `consume_and_rotate(unknown_hash, ...)` returns `NotFound`.
|
||||
- *Edge case (Expired):* `consume_and_rotate(expired_hash, ...)` returns `Expired`; old token is NOT marked `used`.
|
||||
- *Edge case (Reused):* `consume_and_rotate(used_hash, ...)` returns `Reused(existing)`.
|
||||
- *Integration (concurrency):* 16 concurrent `consume_and_rotate` on the same hash — exactly one returns `Rotated`, 15 return `Reused`. (Existing `concurrent_rotation_has_one_winner` test, MUST pass unmodified.)
|
||||
- *Integration (delete_chain):* `insert` two tokens with the same `chain_id`, `delete_chain(chain_id)` returns 2, both vanish.
|
||||
- *Integration (gc_expired):* `insert` an expired token + a live token, `gc_expired(now)` returns 1, expired vanishes, live remains.
|
||||
- *Integration (replay revocation):* `mark_refresh_token_replay(h)` then `was_recently_replay_revoked(&h)` is true; after 60s TTL, false.
|
||||
- *Integration (atomicity):* the R10 transaction-layer atomicity test lives in U2a (synthetic Record + Codec). U6 does not duplicate it — `RefreshToken` cannot itself trigger a JSON encode failure without unrealistic fixtures, so the consume-layer test would either reduce to a closure-Err short-circuit (strictly weaker) or require a fragile mock. The U2a test plus `concurrent_rotation_has_one_winner` are the regression net.
|
||||
|
||||
**Verification:**
|
||||
- All existing tests in `auth_tokens.rs:181-403` pass without behavioural change (the test fixtures may need import-rename updates only).
|
||||
- `cargo nextest run -p fabro-store` passes.
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs` no longer imports `slatedb::WriteBatch` directly.
|
||||
- `RefreshTokenStore`'s `repo` field is private (compile-time check).
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 7: Update public re-exports + `fabro-server` imports**
|
||||
|
||||
**Goal:** Update `fabro-store::lib.rs` re-exports to the new names; update `fabro-server` to use the new type names. Mechanical cleanup.
|
||||
|
||||
**Requirements:** R11 (Database surface).
|
||||
|
||||
**Dependencies:** U2b, U3, U4, U5, U6.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs`:
|
||||
- Drop temporary `pub type SlateAuthCodeStore = AuthCodeStore;` and `pub type SlateAuthTokenStore = RefreshTokenStore;` aliases that U5/U6 introduced
|
||||
- Add `BlobStore`, `RunCatalogIndex` to `pub use slate::{...}` (the new accessor types from U2b/U4)
|
||||
- Verify other re-exports (`AuthCode`, `RefreshToken`, `ConsumeOutcome`, `Database`, `RunDatabase`, `Runs`, `AuthCodeStore`, `RefreshTokenStore`) are still correct
|
||||
- Modify: `lib/crates/fabro-store/src/slate/mod.rs`: drop the temporary `Database::auth_tokens()` shim that U6 introduced (callers now use `refresh_tokens()` directly)
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs:799-829` (4 type-name sites: `Arc<SlateAuthCodeStore>` → `Arc<AuthCodeStore>`, `Arc<SlateAuthTokenStore>` → `Arc<RefreshTokenStore>`)
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs:507,508` (2 accessor sites: `db.auth_tokens()` → `db.refresh_tokens()`)
|
||||
- Modify: `lib/crates/fabro-server/src/auth/cli_flow.rs:380, 462, 541, 660, 1236, 1388, 1660, 1898, 1987, 2042, 2126` (12 accessor sites: `db.auth_tokens()` → `db.refresh_tokens()`; verify each by grep before edit)
|
||||
- Modify: `lib/crates/fabro-server/src/auth/cli_flow.rs:449, 1039, 1410, 2129` (4 `RefreshToken { ... }` literal sites — should be unchanged in shape since `RefreshToken` struct itself doesn't change, but verify imports)
|
||||
- Modify: `lib/crates/fabro-server/tests/it/api/cli_auth_token.rs:80, 82, 146, 149` (4 sites: accessor calls + `AuthCode { ... }` and `RefreshToken { ... }` literals — `AuthCode` literal needs `code` field per U5)
|
||||
- Note: `server.rs`, `jwt_auth.rs`, `auth/mod.rs`, `web_auth.rs` were spot-checked and contain no `SlateAuth*Store` or accessor references — no edits needed there. Final verification grep below catches drift.
|
||||
|
||||
**Approach:**
|
||||
- Rename via grep-replace, since the types are referenced by qualified name only.
|
||||
- `Database::auth_tokens()` → `Database::refresh_tokens()` per R11. Update all callers accordingly.
|
||||
- If any `fabro-server` code constructs `AuthCode` literals (e.g., during the OAuth code flow), add the `code` field to those literals.
|
||||
|
||||
**Patterns to follow:**
|
||||
- N/A — pure rename + import update.
|
||||
|
||||
**Test scenarios:**
|
||||
- *Test expectation: none — pure rename / re-export update.* No new behavioural test required.
|
||||
- *Verification:* `cargo build --workspace` passes; `cargo nextest run --workspace` passes.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run --workspace` passes (including `fabro-server` and `fabro-cli` integration tests).
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` passes.
|
||||
- `cargo +nightly-2026-04-14 fmt --check --all` passes.
|
||||
- `grep -r "Slate\(Auth\|RefreshToken\)" lib/ apps/` returns no production references (test-fixture references are also updated).
|
||||
- `grep -rn '\.auth_tokens()' lib/ apps/` returns zero matches (the `auth_tokens()` accessor was renamed to `refresh_tokens()`; this catches any caller the import-update missed, since a stale `.auth_tokens()` would only fail at compile time if no other type in scope happens to expose a method by that name).
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** `fabro-server` (`serve.rs`, `auth/mod.rs`, `auth/cli_flow.rs`, `jwt_auth.rs`, `web_auth.rs`) imports `Slate*Store` types from `fabro-store` and calls `Database::auth_codes()` / `auth_tokens()`. All of these need import + accessor-name updates in U7. No `fabro-server` logic changes — purely mechanical.
|
||||
- **Error propagation:** `fabro_store::Error` gains two new public variants in U2a: `InvalidKeySegment { segment: String }` (returned by `Repository` key-assembly when a `RecordId::key_segments` impl produces a segment containing the `\0` separator) and `KeyParse(String)` (returned by `scan_stream`/`scan_ids_stream` when `RecordId::from_key_segments` rejects the parsed segments). Existing variants are unchanged. New error paths from `JsonCodec::encode` (`serde_json::Error`) and `MarkerCodec` propagate through the same `Result<T, Error>` shape via the existing variants.
|
||||
- **State lifecycle risks:**
|
||||
- U2a's `transaction(...)` MUST commit all-or-nothing — covered by R10's fault-injection test in U2a (synthetic Record + TestFailCodec).
|
||||
- U5's `AuthCode` schema change (adding `code` field) means any in-flight or persisted code from before the migration would not deserialize. Greenfield → no concern in practice; flag in PR description anyway.
|
||||
- U1's `KeyedMutex` cleanup race (cleanup-under-shard-lock invariant) is the load-bearing concurrency guarantee — covered by U1 stress test.
|
||||
- **API surface parity:** `Database::auth_tokens()` rename → `refresh_tokens()` is observable. Callers in `fabro-server` are the only consumers; updating them in U7. No external repos consume `fabro-store`.
|
||||
- **Integration coverage:** Cross-layer scenarios (Database → wrapper Store → Repository → SlateDB) are covered by:
|
||||
- U2a's transaction fault-injection test (proves R10 atomicity at the helper layer)
|
||||
- U2b's `BlobStore` round-trip + cross-path equivalence test (proves the full stack works for the simplest record and that `RawBytesCodec` is byte-identity)
|
||||
- U4's `Database::list_runs` integration test (proves the catalog migration preserves observable behaviour)
|
||||
- U6's `concurrent_rotation_has_one_winner` (proves KeyedMutex + transaction integration at the consume layer)
|
||||
- The `delete_run_keeps_global_cas_blobs` test in `slate/mod.rs:451` continues to enforce the cross-store blob invariant.
|
||||
- **Unchanged invariants:**
|
||||
- `RunDatabase` event log, projection cache, broadcast channel, `recover_next_seq`, `EventProjectionCache` — all untouched.
|
||||
- `Database::create_run` / `open_run` / `delete_run` / `list_runs` public signatures and observable behaviour — preserved.
|
||||
- `RunDatabase::write_blob` / `read_blob` / `list_blobs` public signatures — preserved (delegation is internal).
|
||||
- All existing `*_db.rs` tests pass without modification (tests touching renamed types update imports; tests touching `AuthCode` literals add the `code` field).
|
||||
- Wire format for `RefreshToken` JSON is byte-identical to today (`JsonCodec` is literal `serde_json::to_vec` forwarding; U2a's snapshot test on a synthetic struct catches accidental future envelope/version/reordering changes).
|
||||
- Wire format for `AuthCode` JSON gains a new `code` field per R7/U5 — the value goes from `{"identity":...,"login":...,...}` to `{"code":"...","identity":...,...}`. Acceptable under greenfield (no production deployments). All existing AuthCode rows in any non-empty test/dev SlateDB become un-decodable after upgrade and must be discarded.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| `transaction(...)` is implemented with non-atomic semantics (e.g., commits per-put on closure error), silently weakening refresh-token rotation atomicity. | R10 fault-injection test in U2a explicitly asserts an encode error on the Nth `put` leaves the DB unchanged. Implementer cannot ship a non-atomic helper without breaking the test. `concurrent_rotation_has_one_winner` in U6 is the consume-layer regression net. |
|
||||
| `AuthCode` struct change in U5 breaks `fabro-server` OAuth code flow. | U5 includes a grep for `AuthCode { ` literals; all are updated in the same commit. `cargo build --workspace` failure is the canary. |
|
||||
| `KeyedMutex` cleanup race: a concurrent `lock(K)` observes a stale Arc after `strong_count == 2` cleanup, leading to two threads holding "the lock for K" against different Mutex instances. | U1 implementation MUST hold the `DashMap` shard lock for both the cleanup check and the entry insertion. U1 includes a stress test that hammers the same key across many drop cycles. |
|
||||
| `Repository<R>::scan_stream` cannot reconstruct `R::Id` from values for records whose Id isn't a field (e.g. ZST markers, content-addressed records). | Resolved at plan time: `RecordId::from_key_segments` parses Id from the key, and `Repository::scan_ids_stream` enumerates ids without touching values. ZST markers (`MarkerCodec`) use the id-only API exclusively. |
|
||||
| `RunDatabase` blob delegation in U3 changes construction of `RunDatabase` inside `Database::create_run`/`open_run`/`open_run_reader`, breaking subtle ordering assumptions. | Resolved at plan time: U3 uses stack-local `BlobStore` construction inside each blob method — no `RunDatabaseInner` field changes, no constructor signature changes. Existing `delete_run_keeps_global_cas_blobs` and full-lifecycle tests are the regression net. |
|
||||
| `gc(predicate)` predicate is `impl Fn(&R) -> bool` — a future caller passes an `async` closure or one that does I/O, blocking the scan. | R4 explicitly states the predicate is sync `Fn` and MUST NOT perform I/O or block. Documented; relies on convention + code review (no compile-time enforcement). |
|
||||
| `JsonCodec::encode` is "literally `serde_json::to_vec`" but a future maintainer adds an envelope/version tag for "v2" without realizing it breaks every existing on-disk record. | U2a's snapshot test on a stable synthetic struct fails loudly on any byte change to JsonCodec output (envelope, version tag, field reordering). PR review should catch the snapshot acceptance. |
|
||||
| Migration order assumption: U2b lands and exposes `BlobStore` publicly before U3 wires `RunDatabase` to it; an external caller could start using `Database::blobs()` directly between U2b and U3. | Acceptable — both paths produce identical results; cross-path equivalence is locked by U2b's test (RawBytesCodec is byte-identity). After U3, `RunDatabase::write_blob` and `Database::blobs().write` are equivalent surfaces. |
|
||||
| Pinning `Repository<R>` to `pub(crate)` is by convention only against future in-crate contributors — nothing prevents a new module under `fabro-store/src/` from constructing a second `Repository<RefreshToken>` and bypassing `RefreshTokenStore`. | Documented in R5: "for crate-internal contributors it is convention + code review." Considered alternative (sealed-per-record module with `pub(super)`) was rejected in pass-2 review for being heavier than the threat warrants. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- No external docs to update — `fabro-store` has no public-facing documentation in `docs/`.
|
||||
- No CLI changes; no rollout/monitoring impact.
|
||||
- No migration script needed — greenfield, on-disk format for `RefreshToken` is byte-identical (locked by snapshot); `AuthCode` schema change in U5 is an additive field, but greenfield means existing dev databases are throwaway.
|
||||
- After U7 lands, a follow-up issue may be filed for: (a) per-Repository batch helper (deferred from origin Q3); (b) `BlobStore` lifecycle question if the simpler stack-local construction in U3 ages poorly.
|
||||
|
||||
## Verification Notes (2026-04-21)
|
||||
|
||||
Post-implementation audit against the plan. All 7 units are implemented; build, nextest (`fabro-store` 68 / `fabro-server` 359), clippy (nightly-2026-04-14 `-D warnings`), and fmt pass. U7 grep checks (`Slate(Auth|RefreshToken)`, `.auth_tokens()`) return zero hits. `slate/catalog.rs` is deleted.
|
||||
|
||||
Minor gaps that do not affect correctness or production surface:
|
||||
|
||||
- **U2a — `scan_prefix_ids_stream` not implemented.** Appears in the Repository *design* sketch (line 186) but is not listed in R4. No current caller. Add lazily if a future consumer needs prefix-scoped id enumeration.
|
||||
- **U4 — two edge-case tests from plan not individually present.** `run_catalog_index.rs` tests cover add/list/remove round-trip and start/end filter, but not (a) `add(rid); remove(rid); list()` returns empty, nor (b) start-later-than-all / end-earlier-than-all returning empty. The integration paths in `slate::tests` and `list_applies_start_and_end_filters` exercise the same code paths, so no functional regression risk.
|
||||
- **U3 — `BlobStore::new(Arc::new(self.inner.db.clone()))` shape.** Plan suggested stack-local `BlobStore::new(self.inner.db.clone())`, but `BlobStore::new` requires `Arc<Db>` so the call wraps in `Arc::new`. Functionally equivalent; cosmetic.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin document:** `docs/brainstorms/2026-04-20-fabro-store-record-abstractions-requirements.md`
|
||||
- Today's K/V stores:
|
||||
- `lib/crates/fabro-store/src/slate/auth_tokens.rs`
|
||||
- `lib/crates/fabro-store/src/slate/auth_codes.rs`
|
||||
- `lib/crates/fabro-store/src/slate/catalog.rs`
|
||||
- `lib/crates/fabro-store/src/slate/run_store.rs`
|
||||
- Database accessor pattern: `lib/crates/fabro-store/src/slate/mod.rs:208-228`
|
||||
- Key construction: `lib/crates/fabro-store/src/keys.rs`
|
||||
- Public re-exports today: `lib/crates/fabro-store/src/lib.rs`
|
||||
- Server callers: `lib/crates/fabro-server/src/serve.rs:799-829`, `lib/crates/fabro-server/src/server.rs`, `lib/crates/fabro-server/src/auth/mod.rs`
|
||||
- Workspace build commands and test posture: `CLAUDE.md` (`cargo nextest`, `cargo +nightly-2026-04-14 clippy`, `cargo +nightly-2026-04-14 fmt`)
|
||||
|
|
@ -1,354 +0,0 @@
|
|||
---
|
||||
title: "refactor: unify run vocabulary and metadata snapshot layout"
|
||||
type: refactor
|
||||
status: active
|
||||
date: 2026-04-20
|
||||
origin: /Users/bhelmkamp/.claude/plans/make-a-full-plan-pure-wombat.md
|
||||
deepened: 2026-04-20
|
||||
---
|
||||
|
||||
# refactor: unify run vocabulary and metadata snapshot layout
|
||||
|
||||
## Overview
|
||||
|
||||
Align the run domain vocabulary and metadata-branch layout around the event-sourced projection the code already maintains in memory. The refactor renames `RunRecord` to `RunSpec`, collapses metadata snapshots into a trimmed `RunProjection` in `run.json`, normalizes per-stage files to `stages/{node_id}@{visit}/...`, and updates every metadata-branch consumer to read that unified shape.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The durable write path is already projection-oriented, but the git metadata branch still presents the same run through multiple accidental shapes:
|
||||
|
||||
- `run.json` is only the spec slice (`RunRecord`)
|
||||
- run lifecycle state is split across `start.json`, `status.json`, `checkpoint.json`, `sandbox.json`, `retro.json`, and `conclusion.json`
|
||||
- node payloads use multiple incompatible path conventions under `nodes/`
|
||||
- fork, rewind, rebuild, retro upload, and CLI dump/export all read or write those legacy files directly
|
||||
|
||||
That mismatch leaks implementation history into the domain model and makes every consumer reason about special cases. The current tree on `main` still shows the old design in `RunDump`, `MetadataStore`, fork/rewind/rebuild operations, CLI rewind recovery, and `fabro store dump`. This plan makes the metadata branch a true serialized projection snapshot and removes the split-file vocabulary drift.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Rename `RunRecord` to `RunSpec` and rename `RunProjection.run` to `RunProjection.spec` everywhere in Rust code and tests. Do not ship alias shims.
|
||||
- R2. Introduce a metadata-only serializer that writes `run.json` as a trimmed `RunProjection`, stripping bulky `NodeState` text fields (`prompt`, `response`, `diff`, `stdout`, `stderr`) while preserving all other projection data.
|
||||
- R3. Standardize metadata-branch and export layout around `run.json`, `graph.fabro`, `retro/*.md`, `events.jsonl`, `checkpoints/*.json`, artifact exports, and `stages/{node_id}@{visit}/...`. Stop writing top-level `start.json`, `status.json`, `checkpoint.json`, `sandbox.json`, `retro.json`, and `conclusion.json`.
|
||||
- R4. Replace metadata helpers and writers that special-case `checkpoint.json` with snapshot-oriented helpers that can write a full projection commit and still return the metadata-branch commit SHA when checkpoint flows need it.
|
||||
- R5. Update metadata consumers (`fork`, `rewind`, `rebuild_meta`, CLI rewind recovery, retro upload, store dump/export) to read the unified projection layout without changing user-visible behavior.
|
||||
- R6. Add additive query methods on `RunSpec` and `RunProjection` for common reads while keeping existing public-field access valid.
|
||||
- R7. Update crate tests, CLI integration tests, and snapshots to the new layout with no coverage regression.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No backward-compatibility read path for old metadata branches. This repo is still pre-launch greenfield.
|
||||
- No OpenAPI or generated TypeScript client change. Server APIs expose run state independently of metadata-branch file layout.
|
||||
- Keep `graph.fabro`, `retro/prompt.md`, `retro/response.md`, `events.jsonl`, `checkpoints/*.json`, and artifact export support.
|
||||
- Do not move artifact exports away from `artifacts/nodes/{node_id}/visit-{n}/...` unless implementation proves a hard blocker; artifact path cleanup is not the point of this refactor.
|
||||
- Do not convert fork/rewind to read events directly from durable storage; they continue to operate from metadata branches.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-types/src/run.rs` and `lib/crates/fabro-store/src/run_state.rs` define the core vocabulary and projection shape that this refactor renames and extends.
|
||||
- `lib/crates/fabro-workflow/src/run_dump.rs` and `lib/crates/fabro-cli/src/commands/store/run_export.rs` currently duplicate layout/serialization logic and already drift on node path format.
|
||||
- `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.
|
||||
- `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
|
||||
|
||||
- No matching `docs/solutions/` entries were present in this repo at planning time, so this plan is grounded in current code and test patterns rather than prior internal solution notes.
|
||||
|
||||
### External References
|
||||
|
||||
- None. This is an internal Rust refactor with sufficient local context.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- Hard rename `RunRecord` to `RunSpec` and `RunProjection.run` to `RunProjection.spec`.
|
||||
Rationale: the current names are the main source of spec/projection confusion, and a greenfield codebase does not benefit from preserving legacy aliases.
|
||||
- `run.json` becomes the single top-level serialized projection snapshot for metadata branches and exports, including `conclusion`.
|
||||
Rationale: leaving `conclusion.json` behind would preserve the accidental fragmentation this refactor is trying to remove.
|
||||
- Use a dedicated metadata serializer wrapper instead of changing `RunProjection`'s canonical serde implementation.
|
||||
Rationale: ordinary projection serde remains valuable for tests and internal round-trips, while metadata snapshots need one specific trimmed representation.
|
||||
- Normalize per-stage paths to `stages/{stage_id}/{filename}` using `StageId::Display`.
|
||||
Rationale: this removes visit-1 special cases and aligns the on-disk layout with the stage identifier already exposed in APIs and logs.
|
||||
- Replace `MetadataStore::write_checkpoint` with a snapshot-oriented commit helper rather than passing renamed data through a stale `checkpoint_json` API.
|
||||
Rationale: checkpoint commits still need a returned SHA, but the helper should describe the new snapshot semantics instead of the deleted file.
|
||||
- Delete the CLI-only `StoreRunExport` duplication and reuse the workflow dump builder.
|
||||
Rationale: this refactor changes layout semantics in one place; keeping two near-identical serializers would make future drift likely.
|
||||
- Keep artifact exports under `artifacts/nodes/{node_id}/visit-{n}/...` in this unit.
|
||||
Rationale: artifact lookup is already keyed by `StageId` at API boundaries, but changing artifact paths would widen scope without addressing the metadata-vocabulary problem.
|
||||
- Query methods remain additive.
|
||||
Rationale: field privacy is a follow-up concern, and this refactor already changes many call sites.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- Should `conclusion.json` survive as a separate top-level file?
|
||||
No. It should collapse into `run.json` with the rest of the projection.
|
||||
- Should CLI export keep its own serializer?
|
||||
No. Reuse the workflow dump/export builder so metadata branches and `fabro store dump` cannot diverge again.
|
||||
- Does the layout change need to cover CLI rewind recovery as well as workflow operations?
|
||||
Yes. `lib/crates/fabro-cli/src/commands/run/rewind.rs` currently reads `checkpoint.json` from the metadata branch and must switch with the rest of the readers.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- 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 `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
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
```text
|
||||
Durable event store
|
||||
-> RunProjection { spec, start, status, checkpoint, conclusion, retro, sandbox, nodes, ... }
|
||||
-> Metadata serializer (trim bulky node text fields)
|
||||
-> Metadata/export tree:
|
||||
run.json # trimmed RunProjection snapshot
|
||||
graph.fabro # readable workflow source
|
||||
stages/<node@visit>/... # prompt.md, response.md, status.json, provider_used.json,
|
||||
# diff.patch, script_invocation.json, script_timing.json,
|
||||
# parallel_results.json, stdout.log, stderr.log
|
||||
retro/prompt.md
|
||||
retro/response.md
|
||||
events.jsonl
|
||||
checkpoints/<seq>.json
|
||||
artifacts/nodes/<id>/visit-<n>/...
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [ ] **Unit 1: Rename run vocabulary to spec/projection**
|
||||
|
||||
**Goal:** Replace the legacy `RunRecord`/`run` vocabulary with `RunSpec`/`spec` across the domain model and its consumers.
|
||||
|
||||
**Requirements:** R1
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-types/src/run.rs`
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/records/{run.rs,mod.rs}`
|
||||
- Modify: `lib/crates/fabro-store/src/run_state.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/{runtime_store.rs,run_lookup.rs}`
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/{pull_request.rs,retro.rs,types.rs,execute/tests.rs}`
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/{create.rs,start.rs,fork.rs,rebuild_meta.rs}`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/{run/create.rs,run/fork.rs,run/rewind.rs,runs/inspect.rs,pr/create.rs,store/dump.rs}`
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs`
|
||||
- Test: `lib/crates/fabro-types/tests/run_record_serde.rs` (rename to `run_spec_serde.rs`)
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/create.rs`
|
||||
|
||||
**Approach:**
|
||||
- Make this a pure mechanical rename first so later layout changes can focus on behavior rather than symbol churn.
|
||||
- Rename `Persisted::run_record` and other outward-facing internal helpers to `spec`-oriented names in the same pass.
|
||||
- Keep the data shape unchanged in this unit; only names move.
|
||||
|
||||
**Execution note:** Land as a mechanical rename before touching metadata serialization or file layout.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-types/src/stage_id.rs` accessor style for the later query-method unit.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `run_spec_serde.rs` round-trips a `RunSpec` with templated settings and blob refs exactly as the old `RunRecord` test did.
|
||||
- Happy path: `RunProjection::apply_event` stores `spec` on `RunCreated` and updates the spec's `definition_blob` on `RunSubmitted`.
|
||||
- Edge case: workspace code compiles with no lingering `RunRecord` or `run_record` identifiers in Rust source.
|
||||
|
||||
**Verification:**
|
||||
- The workspace compiles after the rename with no alias shims.
|
||||
- Rust source no longer contains `RunRecord` or `run_record` identifiers.
|
||||
|
||||
- [ ] **Unit 2: Add trimmed projection serialization and additive query methods**
|
||||
|
||||
**Goal:** Define the metadata snapshot serialization contract and expose additive readers on `RunSpec` and `RunProjection`.
|
||||
|
||||
**Requirements:** R2, R6
|
||||
|
||||
**Dependencies:** Unit 1
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-store/src/serializable_projection.rs`
|
||||
- Modify: `lib/crates/fabro-store/src/lib.rs`
|
||||
- Modify: `lib/crates/fabro-store/src/run_state.rs`
|
||||
- Modify: `lib/crates/fabro-types/src/run.rs`
|
||||
- Test: `lib/crates/fabro-store/src/serializable_projection.rs`
|
||||
- Test: `lib/crates/fabro-store/src/run_state.rs`
|
||||
- Test: `lib/crates/fabro-types/tests/run_spec_methods.rs`
|
||||
|
||||
**Approach:**
|
||||
- Add a metadata-only serializer wrapper around `RunProjection` that strips `NodeState.prompt`, `response`, `diff`, `stdout`, and `stderr` from `run.json` while preserving top-level fields and the non-bulky node metadata.
|
||||
- Keep ordinary `RunProjection` serde untouched so existing test helpers and internal round-trips keep working.
|
||||
- Add query methods such as `RunSpec::id()`, `RunSpec::graph()`, `RunProjection::spec()`, `RunProjection::status()`, and `RunProjection::current_checkpoint()` without changing field visibility.
|
||||
|
||||
**Execution note:** Start with failing round-trip tests before wiring the new serializer into metadata writers.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing `RunProjection::node`, `iter_nodes`, and `list_node_visits` helpers in `lib/crates/fabro-store/src/run_state.rs`
|
||||
- `StageId` accessor methods in `lib/crates/fabro-types/src/stage_id.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: a projection with full top-level state and one populated node round-trips through the metadata serializer, deserializes back, and keeps all non-bulky fields intact while clearing the bulky text fields.
|
||||
- Happy path: `RunSpec` getters expose `run_id`, `graph`, `settings`, `workflow_slug`, `working_directory`, and labels from a representative fixture.
|
||||
- Edge case: an empty projection round-trips unchanged.
|
||||
- Edge case: projections containing `foo@1` and `foo@2` nodes preserve both `StageId` keys across the round-trip.
|
||||
- Edge case: `RunProjection::status()` returns `None` when no status record exists and the correct enum when one does.
|
||||
|
||||
**Verification:**
|
||||
- The metadata serializer can round-trip a projection into the trimmed wire shape and back.
|
||||
- New accessors compile without forcing existing field access call sites to change.
|
||||
|
||||
- [ ] **Unit 3: Unify metadata and export writers around one snapshot layout**
|
||||
|
||||
**Goal:** Make one authoritative dump/export builder produce the unified `run.json` + `stages/` layout for both metadata branches and CLI export.
|
||||
|
||||
**Requirements:** R2, R3, R4
|
||||
|
||||
**Dependencies:** Unit 2
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/run_dump.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/lifecycle/git.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/finalize.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/git.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/store/{dump.rs,run_export.rs}`
|
||||
- Test: `lib/crates/fabro-workflow/src/git.rs`
|
||||
- Test: `lib/crates/fabro-workflow/src/pipeline/finalize.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/store_dump.rs`
|
||||
|
||||
**Approach:**
|
||||
- Replace `RunDump::metadata_init`, `metadata_checkpoint`, `metadata_finalize`, and the CLI-only `StoreRunExport::from_store_state_and_events` path with one authoritative builder that starts from a `RunProjection`.
|
||||
- Have metadata snapshots always emit `run.json` through the trimmed serializer, `graph.fabro` when present, and stage files under `stages/{stage_id}/...`.
|
||||
- Keep export-only concerns (`events.jsonl`, `checkpoints/*.json`, hydrated blobs, artifact bytes) as opt-in helpers on the shared builder rather than as a second serializer.
|
||||
- Remove top-level split JSON files, including `conclusion.json`, from both metadata branches and CLI export.
|
||||
- Update checkpoint persistence in lifecycle code to use the new generic snapshot commit helper instead of a `checkpoint.json`-specific API.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing `RunDumpEntry` helpers in `lib/crates/fabro-workflow/src/run_dump.rs`
|
||||
- `StageId::Display` in `lib/crates/fabro-types/src/stage_id.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: an init-state projection writes only `run.json` and `graph.fabro` when no stages or retro data exist.
|
||||
- Happy path: a checkpoint-state projection writes `run.json` plus `stages/<id>@1/` files for prompt, response, status, provider, diff, script metadata, stdout, and stderr when present.
|
||||
- Happy path: CLI dump/export uses the same builder and still emits `events.jsonl`, `checkpoints/*.json`, `retro/*.md`, and artifact payloads.
|
||||
- Edge case: a node with multiple visits writes both `stages/build@1/...` and `stages/build@2/...` with no visit-1 special case.
|
||||
- Edge case: `run.json` contains `start`, `status`, `checkpoint`, `sandbox`, `retro`, and `conclusion`, but not bulky node text payloads.
|
||||
|
||||
**Verification:**
|
||||
- Writer/export code no longer contains legacy `nodes/` metadata stage paths or top-level split-file emission logic.
|
||||
- Shared writer tests prove metadata branches and CLI export emit the same projection layout.
|
||||
|
||||
- [ ] **Unit 4: Update metadata readers, recovery flows, and rebuild logic**
|
||||
|
||||
**Goal:** Move every metadata-branch consumer from standalone file reads to projection reads, including the rebuild and rewind recovery paths.
|
||||
|
||||
**Requirements:** R4, R5
|
||||
|
||||
**Dependencies:** Unit 3
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-checkpoint/src/metadata.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/{fork.rs,rewind.rs,rebuild_meta.rs}`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/rewind.rs`
|
||||
- Test: `lib/crates/fabro-checkpoint/src/metadata.rs`
|
||||
- Test: `lib/crates/fabro-workflow/src/operations/{fork.rs,rewind.rs,rebuild_meta.rs}`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/fork.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/recovery.rs`
|
||||
- Test: `lib/crates/fabro-workflow/tests/it/{integration.rs,daytona_integration.rs}`
|
||||
|
||||
**Approach:**
|
||||
- Add `MetadataStore::read_run_projection` and `read_run_spec`; either delete `read_checkpoint`/`read_start_record` or demote them to projection-field extractors after callers switch.
|
||||
- Update `fork` to read the source projection, clone the spec/start/sandbox slices it intentionally carries forward, inject the new run ID, and write the new run's metadata branch through the unified snapshot writer.
|
||||
- Update rewind parallel detection to read `projection.spec.graph`, and update CLI rewind recovery to pull the restored checkpoint from the projection snapshot instead of `checkpoint.json`.
|
||||
- Rewrite `rebuild_meta` to emit one snapshot commit per metadata commit (init/checkpoint/finalize) through the shared writer while preserving `git_commit_sha` backfill semantics inside `projection.checkpoint`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing timeline and run-SHA backfill helpers in `lib/crates/fabro-workflow/src/operations/{rewind.rs,rebuild_meta.rs}`
|
||||
- `RunStoreHandle::state()` projection access in `lib/crates/fabro-workflow/src/runtime_store.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: a forked run gets a new `run.json` projection with the new run ID, inherited sandbox/start context, and no top-level split JSON files.
|
||||
- Error path: forking still fails cleanly when the source metadata branch lacks `run.json` or the target checkpoint lacks a run commit SHA.
|
||||
- Happy path: rewind parallel detection still recognizes interior parallel groups from `projection.spec.graph`.
|
||||
- Happy path: CLI rewind recovery reads the checkpoint from the projection snapshot and replays `RunRewound` plus restored checkpoint events correctly.
|
||||
- Integration: rebuild-meta emits one `run.json` snapshot per metadata commit, and each snapshot contains the expected checkpoint payload and backfilled `git_commit_sha`.
|
||||
- Error path: rebuild-meta remains atomic on failure and still refuses to overwrite an existing metadata branch.
|
||||
|
||||
**Verification:**
|
||||
- Metadata consumers no longer require top-level `checkpoint.json`, `start.json`, or `sandbox.json`.
|
||||
- Fork, rewind, and rebuild tests pass against the unified layout.
|
||||
|
||||
- [ ] **Unit 5: Sweep downstream docs, retro prompts, and snapshots**
|
||||
|
||||
**Goal:** Align retro tooling, integration tests, and snapshots with the unified metadata vocabulary and file layout.
|
||||
|
||||
**Requirements:** R3, R5, R7
|
||||
|
||||
**Dependencies:** Unit 4
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-retro/src/retro_agent.rs`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/cmd/{store_dump.rs,start.rs,fork.rs}`
|
||||
- Modify: `lib/crates/fabro-cli/tests/it/scenario/recovery.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/git.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/finalize.rs`
|
||||
- Modify: `lib/crates/fabro-workflow/tests/it/{integration.rs,daytona_integration.rs}`
|
||||
- Test: the files above
|
||||
|
||||
**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 `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 `docs-internal/testing-strategy.md`
|
||||
- Existing retro upload flow in `lib/crates/fabro-retro/src/retro_agent.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: retro sandbox upload includes `run.json` projection data, and the prompt tells the retro agent to inspect `run.json` plus `graph.fabro`/stage files rather than `checkpoint.json`.
|
||||
- Happy path: `fabro store dump` snapshots show `run.json`, `graph.fabro`, `stages/...`, `retro/*.md`, `events.jsonl`, and `checkpoints/*.json`, with no legacy split JSON files.
|
||||
- Happy path: integration and Daytona tests read run spec and checkpoint data through the new projection helpers and still observe correct `git_commit_sha` behavior.
|
||||
- Edge case: tests that previously referred to missing `status.json` or `sandbox.json` continue to assert the public command behavior without relying on those internal filenames existing.
|
||||
|
||||
**Verification:**
|
||||
- Snapshot and integration tests reference only the new layout.
|
||||
- Retro tooling and test names no longer describe deleted files such as `conclusion.json` or `checkpoint.json` as metadata-branch invariants.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** metadata snapshots are written from lifecycle init/checkpoint/finalize and rebuild-meta; they are read by fork, rewind, CLI rewind recovery, retro upload, store dump/export, and metadata-focused tests.
|
||||
- **Error propagation:** deserialization errors shift from file-specific entities (`checkpoint`, `run record`) to projection parsing plus field-extraction errors; reader helpers should preserve branch/path context so failures stay diagnosable.
|
||||
- **State lifecycle risks:** partial migration of writers/readers would silently break metadata-driven flows; the refactor must switch readers and writers in the same series and preserve checkpoint commit SHA capture.
|
||||
- **API surface parity:** `StageId` already uses `node@visit`, so metadata paths, CLI exports, and test fixtures should align on the same identifier format. Artifact exports are the deliberate exception in this unit and remain on `artifacts/nodes/...`.
|
||||
- **Integration coverage:** the highest-value end-to-end paths are checkpoint persistence, fork from checkpoint, rewind + resume recovery, rebuild metadata from durable state, and `fabro store dump`.
|
||||
- **Unchanged invariants:** event semantics, durable-store state accumulation, `graph.fabro` export, and artifact export support remain intact; the refactor changes metadata serialization shape, not workflow execution behavior.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| A reader still depends on `checkpoint.json`, `start.json`, or `sandbox.json` after those files stop being written | Exhaustively update metadata helper call sites and keep dedicated fork/rewind/recovery integration coverage in the same series |
|
||||
| `run.json` trimming accidentally drops state consumers still need | Add round-trip tests that prove all non-bulky top-level and node metadata survives the trimmed serializer |
|
||||
| Shared writer migration leaves CLI export and metadata branches on subtly different layouts | Delete or subsume `StoreRunExport` in the same series rather than maintaining parallel serializers |
|
||||
| `git_commit_sha` handling regresses during fork or rebuild | Preserve dedicated tests for missing-SHA errors, backfilled SHAs, and forked checkpoint snapshots |
|
||||
| Large mechanical rename obscures behavioral regressions in review | Land the rename first, keep later units behavior-focused, and use targeted tests for each behavior-bearing unit |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- Update inline comments, test names, and docstrings that still describe `run.json` as a run record or refer to `checkpoint.json`, `status.json`, `sandbox.json`, or `nodes/...` as metadata-branch invariants.
|
||||
- No rollout or migration plan is needed for existing branches because the repo is still pre-launch; local stale metadata branches can be regenerated or discarded.
|
||||
- Snapshot updates should follow the repo's `cargo insta pending-snapshots` discipline rather than bulk-accepting blindly.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Source plan:** `/Users/bhelmkamp/.claude/plans/make-a-full-plan-pure-wombat.md`
|
||||
- Related code:
|
||||
- `lib/crates/fabro-types/src/run.rs`
|
||||
- `lib/crates/fabro-store/src/run_state.rs`
|
||||
- `lib/crates/fabro-workflow/src/run_dump.rs`
|
||||
- `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: `docs-internal/testing-strategy.md`
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,472 +0,0 @@
|
|||
---
|
||||
title: "feat: Add object-store step to the browser install wizard"
|
||||
type: feat
|
||||
status: completed
|
||||
date: 2026-04-22
|
||||
origin: docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md
|
||||
---
|
||||
|
||||
# feat: Add object-store step to the browser install wizard
|
||||
|
||||
## Overview
|
||||
|
||||
Add a first-run `Object store` step to the browser install wizard between `Server` and `LLM`. The step lets the operator choose one shared object-store mode for both SlateDB and artifacts: `Local disk` or `AWS S3`. The S3 path collects `bucket`, `region`, and one of two credential modes: runtime credentials (deployment-provided AWS auth such as ECS/EKS/IRSA metadata flows, instance profiles, or AWS env vars already present in the server process) or manually-entered `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`.
|
||||
|
||||
> **Terminology.** This plan uses **runtime credentials** to refer to the deployment-provided AWS auth path (what the UI labels `Use AWS runtime credentials`). Earlier drafts called this "ambient", "ambient runtime", or "default chain"; those were shorthand for "credentials supplied by the runtime rather than typed into the wizard". **Manual credentials** refers to the static access-key-pair path.
|
||||
|
||||
The implementation is broader than a UI form. It touches the install API contract, server-side install session state, settings/env persistence, the browser wizard flow, and the server's runtime object-store initialization. The key technical requirement is that manual AWS credentials stored in `server.env` must actually be consumed by the S3 object-store builder at install-finish time and on subsequent server boots.
|
||||
|
||||
The wizard's goal is that `POST /install/finish` produces a fully bootable server with no subsequent operator env-editing step. A UI-only variant that writes `settings.toml` but requires the operator to separately place `AWS_*` into process env or `server.env` defeats that goal — it leaves the wizard claiming completion without persisting the secrets it just collected, and turns the "type keys into the wizard" affordance into a trap. That UX goal is what keeps Unit 2's runtime bridge load-bearing; the existing `process env -> server.env` precedence in `server_secrets.rs` is the precedence mechanism we reuse, not a standalone architectural invariant.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
The browser install flow currently covers canonical URL, LLM credentials, and GitHub, but it does not expose the existing object-store configuration surface that already exists in server settings. Operators who want S3-backed SlateDB/artifact storage have to finish the wizard and then hand-edit `settings.toml` plus startup secrets.
|
||||
|
||||
That defeats the point of a remote-first web install flow. The object-store choice belongs in the install wizard because it is foundational server infrastructure, not an advanced follow-up tweak. The plan keeps the local storage root model unchanged: `server.storage.root` remains host-local storage, while the new step chooses only the shared object store used by `server.slatedb` and `server.artifacts` (see origin: `docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md`).
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
### Wizard placement and step ordering (R1-R3)
|
||||
|
||||
- Add a first-class `Object store` wizard step after `Server` and before `LLM`, and make the UI copy explicit that the local host storage root still exists and this step only chooses the shared object store.
|
||||
|
||||
### Storage mode and scope (R4-R9)
|
||||
|
||||
- Offer exactly two wizard-managed modes: `Local disk` and `AWS S3`. The choice applies to both `server.slatedb` and `server.artifacts`. The S3 path uses one shared bucket with fixed prefixes `slatedb` and `artifacts` in config, which correspond to `slatedb/` and `artifacts/` keys in the bucket at runtime. No split backends, custom prefixes, endpoint, or path-style options are exposed in the wizard.
|
||||
|
||||
### Credential collection and persistence (R10-R15)
|
||||
|
||||
- The S3 path collects `bucket`, `region`, and one of two credential modes: runtime credentials or manual access-key credentials. Manual mode collects only `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, persists them as server-only startup secrets, and explicitly excludes STS/session-token inputs.
|
||||
|
||||
### Validation and session handling (R16-R18)
|
||||
|
||||
- S3 configuration is live-validated before the wizard advances. Validation errors render inline and should distinguish shape errors from access failures where practical. The review/session surfaces summarize the chosen object-store mode without echoing secret values.
|
||||
|
||||
### Review display (R19)
|
||||
|
||||
- The review step shows the chosen mode, and for S3 shows bucket, region, credential mode, and the fixed `slatedb` / `artifacts` prefixes.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- No changes to the terminal `fabro install` flow in this pass.
|
||||
- No attempt to make `server.storage.root` remote or optional. Host-local storage remains required.
|
||||
- No support for separate object-store backends for SlateDB and artifacts.
|
||||
- No S3-compatible endpoint/path-style options in the wizard.
|
||||
- No STS/session-token/manual-profile flows.
|
||||
- No SlateDB tuning changes such as `disk_cache` defaults; existing defaults remain in force.
|
||||
- No generic install-wizard refactor from the current monolithic `install-app.tsx` into route-local files unless a small local helper extraction is needed to keep the patch readable.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- **Install API contract:** `docs/api-reference/fabro-api.yaml` currently exposes install session, LLM, server, GitHub, and finish endpoints. `InstallSessionResponse` has `llm`, `server`, `github`, and `prefill`, but no storage/object-store field.
|
||||
- **Browser install client:** `apps/fabro-web/app/install-api.ts` is a thin raw-fetch wrapper over the install routes. It already follows the pattern `POST /test` then `PUT /step` for LLM and GitHub token validation.
|
||||
- **Browser install UI:** `apps/fabro-web/app/install-app.tsx` is the install wizard host. Step order, current-step routing, back/next links, session hydration, and review summary are all hard-coded there today.
|
||||
- **Server install session/router:** `lib/crates/fabro-server/src/install.rs` owns `PendingInstall`, the per-step DTOs, the `/install/*` handlers, `completed_steps`, and the `post_install_finish` persistence path.
|
||||
- **Shared install persistence:** `lib/crates/fabro-install/src/lib.rs` already centralizes pure install-time settings mutation (`merge_server_settings`, `write_token_settings`, `write_github_app_settings`) and direct persistence (`persist_install_outputs_direct`).
|
||||
- **Runtime object-store wiring:** `lib/crates/fabro-server/src/serve.rs` builds local/S3 object stores from resolved settings. The current S3 path uses `AmazonS3Builder::from_env()` directly, so it sees process env but does not currently consult `server.env`.
|
||||
- **Server secret precedence:** `lib/crates/fabro-server/src/server_secrets.rs` already defines the server runtime precedence model as `process env -> server.env`. `docs/administration/server-configuration.mdx` documents the same rule.
|
||||
- **Install router tests:** `lib/crates/fabro-server/tests/it/api/install.rs` covers install session/auth, finish semantics, and artifact metadata creation. `apps/fabro-web/app/install-app.test.tsx` already exercises wizard rehydration and GitHub callback flows.
|
||||
|
||||
### Existing Patterns to Reuse
|
||||
|
||||
- **Separate validation and persistence endpoints:** `POST /install/llm/test` and `POST /install/github/token/test` validate external credentials without mutating session state; `PUT /install/llm` and `PUT /install/github/token` persist only after client-side success.
|
||||
- **Redacted session snapshots:** `install.rs` stores raw secrets in memory but exposes only redacted summaries through `GET /install/session`. The LLM and GitHub flows already prove the pattern for "configured but not rehydrated" secret inputs.
|
||||
- **Shared settings helpers:** `fabro-install` is already the right place for pure config/env mutation helpers used by both CLI/server install surfaces.
|
||||
- **Server-env precedence tests:** `lib/crates/fabro-server/src/server.rs` already has coverage proving process env wins over `server.env`.
|
||||
|
||||
### External References
|
||||
|
||||
- `object_store::aws::AmazonS3Builder` supports `new()`, explicit access-key setters, and explicit env-driven credential-provider inputs. That is the right primitive for preserving AWS role-based runtime auth while avoiding accidental leakage from unrelated `AWS_*` process env settings such as endpoint overrides.
|
||||
- `object_store` list operations are a good fit for install-time validation because they exercise the real bucket/prefix access path without writing metadata during the wizard.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
- No `docs/solutions/` entry currently covers object-store-backed install flows or S3 credential bridging. This is net-new planning ground.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Use a dedicated object-store install contract.** Add a new install step and API shape instead of overloading `InstallServerConfigInput`. The server session response gets a separate redacted `object_store` summary field so the review screen and re-entry flow do not have to infer object-store state from raw settings text.
|
||||
- **Use `object_store` as the session/completion token, and `/install/object-store` as the route.** The user-facing label stays `Object store`, while the route stays readable and the completed-step token matches current string-based step handling.
|
||||
- **Keep `Local disk` as a settings no-op.** For the local path, do not write new `[server.slatedb]` / `[server.artifacts]` sections just to restate current defaults. `post_install_finish` already rebuilds `settings.toml` from a fresh TOML document on every run, so selecting `Local disk` naturally drops previously-written S3 sections without needing subtractive settings edits. The session/review surfaces still record the operator's choice during the wizard.
|
||||
- **Write explicit S3 config only when S3 is selected.** The S3 path writes `[server.artifacts] provider = "s3"`, `prefix = "artifacts"`, `[server.artifacts.s3] bucket/region`, and the analogous `[server.slatedb]` config with `prefix = "slatedb"`. Prefix values are stored without trailing slashes because artifact paths are joined by `ArtifactStore::prefixed_raw()` in `lib/crates/fabro-store/src/artifact_store.rs`, while SlateDB base prefixes are normalized by `normalize_base_prefix()` in `lib/crates/fabro-store/src/slate/mod.rs`.
|
||||
- **Extend `fabro-install` instead of hand-building new TOML in `install.rs`.** Add pure helper(s) in `lib/crates/fabro-install/src/lib.rs` for object-store settings mutation and server-env edits so the server install code stays declarative and future CLI parity has a reusable base.
|
||||
- **Support both env sets and env removals during direct install persistence, scoped to wizard-managed keys.** This feature needs explicit removal support for `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` when the operator switches away from manual-credential mode. However, `server.env` may contain AWS keys the operator set for reasons unrelated to Fabro's object store (workflow-level tools, other integrations). Removal must be scoped to keys the wizard itself placed: wizard-written env lines carry a marker comment (for example, `# managed by fabro-install: object-store`) and the removal path only deletes keys that still carry that marker. Keys in `server.env` without the marker survive untouched, even when the current wizard mode would not write them.
|
||||
- **Keep `server.env` persistence convergent on retry, not atomic at the install-flow level, but atomic at the filesystem level.** `server.env` mutations are applied immediately and persist even if later settings/vault writes fail. This plan does not widen scope into changing that broader install behavior. The new AWS-key removal path should follow the same model: retries must converge the file to the newly chosen state, and tests should make that lifecycle explicit. Each individual write must be atomic at the filesystem level — `envfile::merge_env_file` should write to a sibling tempfile in the same directory, `fchmod` it to `0600`, `fsync`, `rename(2)` it into place, and `fsync` the parent directory, so readers never observe a truncated or partial-credentials file.
|
||||
- **Make the runtime object-store builder env-aware without inheriting unrelated `AWS_*` process env.** Refactor the S3 builder path to start from `AmazonS3Builder::new()`, apply bucket/region/path-style/endpoint from resolved settings, and feed credential-related lookup values through the existing `process env -> server.env` precedence model. Reuse `ServerSecrets::{with_env_lookup,get}` rather than introducing a second precedence system; `server_secrets.rs` should only change if a tiny helper extraction is needed for readability.
|
||||
- **Allow only the credential-provider env inputs the runtime actually needs.** The env-aware builder should explicitly map the supported static-key, web-identity, container-credential, and metadata-provider inputs that `object_store` understands. It must not honor `AWS_ENDPOINT`, `AWS_ENDPOINT_URL_S3`, or similar endpoint-override env vars from process env or `server.env`; endpoint continues to come only from resolved settings, which keeps the wizard on the AWS-only path and avoids validation probing arbitrary internal hosts.
|
||||
- **Use explicit static credentials only when both halves are present, but scope that rule to the static access-key path.** If exactly one of `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` is available from the combined lookup, return a clear install/runtime error for the static-key path instead of falling back. Do not reinterpret other runtime-credential inputs or widen the rule into a generic failure mode for non-static provider flows.
|
||||
- **Use non-mutating prefix probes for S3 validation.** The validation endpoint should build the same object-store shape the runtime will use, then perform non-writing access probes against both `artifacts` and `slatedb` prefixes. Avoid using `write_metadata()` during the wizard because that adds avoidable side effects to a step the user may back out of.
|
||||
- **Keep wizard secret re-entry behavior consistent with existing install steps.** Manual AWS credentials are never returned in `GET /install/session`. If the user re-enters the step after saving manual credentials, the credential mode and bucket/region are shown, the secret fields remain blank, blank submit preserves the stored pair, and entering either secret field switches into replacement mode that requires both fields.
|
||||
- **Enforce `0600` permissions on `server.env`.** `fabro-config::envfile::set_private_permissions` already applies `0600` on unix and propagates the `io::Error` when the `chmod` fails; Unit 1's test only needs to assert the resulting permission bits on both create and update paths and decide whether the current non-unix no-op is acceptable for this feature. AWS access keys are long-lived, high-value credentials; world-readable or group-readable persistence would be an obvious pivot path for local attackers or low-privilege co-tenants.
|
||||
- **Hold raw AWS credentials in a redaction-safe wrapper, zeroized on session end.** The raw `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` values are reachable only through an `expose_secret()`-style accessor used exclusively at the builder boundary and at the `server.env` write boundary. The wrapper's `Serialize`/`Debug`/`Display` must print a fixed redaction token, never the raw value. Every error path — including those produced by `AmazonS3Builder` / `object_store` / `reqwest` — must be rewritten into install-domain error types that do not interpolate the raw secret; `format!("{}", raw_key)` and direct `tracing::*` field capture of the unwrapped value are forbidden. Assertions on at least two paths (validation-error response and finish-error response with a fabricated but structurally-realistic key) must confirm the raw value does not appear in response bodies or captured tracing output. The in-memory copy on `PendingInstall` uses the same `Zeroize`/`SecretString` wrapper and must be cleared on finish success, explicit session reset, install-session expiry, and when the operator submits a provider/mode change that no longer needs the stored pair.
|
||||
- **Do not widen scope into CLI parity or S3-compatible backends.** The plan stays anchored to the browser wizard requirements document and does not pull in `fabro install`, endpoint/path-style UI, or STS.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **How should local object-store choice persist?** Leave local object-store config implicit through existing defaults; only the S3 path writes explicit object-store sections.
|
||||
- **Where should manual AWS credentials live?** In `server.env`, not in the vault, and they must be removable when the chosen mode no longer needs them.
|
||||
- **How does the server actually consume manual AWS credentials?** Through an env-aware object-store builder that follows the existing `process env -> server.env` precedence model instead of relying on raw process env alone.
|
||||
- **What should install-time validation probe do?** Build the real object-store configuration and perform side-effect-free access probes against the fixed `artifacts` and `slatedb` prefixes.
|
||||
- **Do we need CLI install changes now?** No. This plan is browser-install-only.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Exact OpenAPI schema factoring:** Whether `credential_mode` becomes a dedicated schema or remains an inline string enum is mechanical. The important part is that the save payload and session summary are separate types.
|
||||
- **Exact shape of the validation success response:** `204 No Content` or `{ ok: true }` are both workable. Match the existing install API style chosen by the implementer, but keep the error path aligned with `readInstallError()`.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
### User flow
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
A[Welcome]
|
||||
B[Server]
|
||||
C[Object store]
|
||||
D[LLM]
|
||||
E[GitHub]
|
||||
F[Review]
|
||||
G[Finish]
|
||||
|
||||
A --> B --> C --> D --> E --> F --> G
|
||||
```
|
||||
|
||||
### Mode matrix
|
||||
|
||||
| Wizard choice | settings.toml | server.env | Validation |
|
||||
|---|---|---|---|
|
||||
| `Local disk` | No new object-store sections; current defaults continue to resolve local SlateDB + local artifacts | Remove stale wizard-managed `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` entries if present | No network probe; validation is a no-op beyond schema checks |
|
||||
| `AWS S3` + `Use AWS runtime credentials` | Write explicit S3 sections for both `server.artifacts` and `server.slatedb` with fixed prefixes `artifacts` / `slatedb` and shared bucket/region | Remove stale wizard-managed static AWS key vars if present | Probe S3 access using runtime credentials supplied by the deployment environment |
|
||||
| `AWS S3` + `Enter AWS access key credentials` | Same explicit S3 sections as above | Set `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` | Probe S3 access using the submitted explicit key pair |
|
||||
|
||||
### Dependency graph
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
U1[U1 Contract and shared install helpers]
|
||||
U2[U2 Env-aware object-store runtime and validation]
|
||||
U3[U3 Install router/session/finish integration]
|
||||
U4[U4 Browser wizard step and review UI]
|
||||
U5[U5 Docs and generated surfaces]
|
||||
|
||||
U1 --> U3
|
||||
U2 --> U3
|
||||
U1 --> U4
|
||||
U3 --> U4
|
||||
U3 --> U5
|
||||
U4 --> U5
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Contract and shared install helpers**
|
||||
|
||||
**Goal:** Add the durable install contract for the new object-store step and extend shared install persistence helpers so the server install flow can write/remove object-store env keys without ad hoc logic.
|
||||
|
||||
**Requirements:** R1-R3, R4-R15, R19
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/api-reference/fabro-api.yaml`
|
||||
- Modify: `lib/crates/fabro-install/src/lib.rs`
|
||||
- Regenerate: `lib/packages/fabro-api-client/` (via `cd lib/packages/fabro-api-client && bun run generate`; includes new/modified models under `src/api/install-api.ts`, `src/models/install-session-response.ts`, and `src/models/install-object-store*.ts`)
|
||||
- Test: `lib/crates/fabro-install/src/lib.rs`
|
||||
|
||||
**Approach:**
|
||||
- Add a dedicated object-store save payload and redacted session summary to the install OpenAPI surface, plus `POST /install/object-store/test` and `PUT /install/object-store`.
|
||||
- Model the save payload with one shared choice for both storage domains:
|
||||
- `provider: "local" | "s3"`
|
||||
- optional S3 payload with `bucket`, `region`, `credential_mode`
|
||||
- manual mode only: `access_key_id`, `secret_access_key`
|
||||
- Keep the session summary separate from the save payload so secrets never appear in `InstallSessionResponse`.
|
||||
- Add a pure `fabro-install` helper for writing the S3 settings shape into a mutable TOML doc, including fixed prefixes `artifacts` and `slatedb`.
|
||||
- Expand direct install persistence so it can remove stale env keys as well as merge new ones. The current CLI path (`server_env_remove` inside `fabro-cli`) and the shared `fabro_install::persist_install_outputs_direct` / `envfile::merge_env_file` are not symmetric today; extending `persist_install_outputs_direct` to accept a remove-list is part of this unit, not a free reuse. Hoisting the CLI's existing removal code into the shared crate is acceptable.
|
||||
- After the OpenAPI edit, run `cd lib/packages/fabro-api-client && bun run generate` so downstream units (and the web app) can consume the new `InstallObjectStore*` models.
|
||||
- Treat the local path as a no-op for object-store config but still return the AWS key removals so retries over stale `server.env` state converge correctly.
|
||||
- `persist_install_outputs_direct` must write `server.env` with `0600` permissions (create or rewrite) and must fail closed if it cannot set them. A unit test must assert the permission bits on both create and update paths.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `merge_server_settings`, `write_token_settings`, and `write_github_app_settings` in `lib/crates/fabro-install/src/lib.rs`
|
||||
- Existing install OpenAPI shapes in `docs/api-reference/fabro-api.yaml`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: local object-store selection writes no explicit object-store sections and requests removal of stale AWS key vars.
|
||||
- Happy path: S3 runtime-credential selection writes both `server.artifacts` and `server.slatedb` S3 sections with `bucket`, `region`, and fixed prefixes `artifacts` / `slatedb`.
|
||||
- Happy path: S3 manual-credential selection writes the same S3 config and returns `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` env edits.
|
||||
- Edge case: prefixes are written without trailing `/` in TOML and still represent `artifacts/` / `slatedb/` at runtime.
|
||||
- Edge case: unrelated `server.env` keys survive the set/remove rewrite unchanged.
|
||||
- Error path: malformed helper input (for example, S3 mode without bucket/region) fails before serializing install output.
|
||||
- Integration: direct persistence removes stale wizard-managed AWS keys when the selected mode no longer needs them while leaving unmarked operator-managed keys untouched.
|
||||
|
||||
**Verification:**
|
||||
- `fabro-install` helper tests cover local, S3 runtime, S3 manual, and env-removal behavior.
|
||||
- The generated TypeScript client exposes the new session field and object-store models expected by the web app.
|
||||
|
||||
- [x] **Unit 2: Env-aware object-store runtime and install-time validation**
|
||||
|
||||
**Goal:** Refactor object-store creation so manual AWS credentials stored in `server.env` are actually consumable at runtime and during install-finish metadata writes, while also providing a shared, side-effect-free validation path for the new install step.
|
||||
|
||||
**Requirements:** R7-R15 primary (shared S3 shape and credential-mode runtime consumption). R16-R18 only at the validation-helper layer, where Unit 2 translates object-store failures into install-domain validation outcomes that Units 3 and 4 surface.
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs`
|
||||
- Modify: `lib/crates/fabro-server/src/install.rs`
|
||||
- Test: `lib/crates/fabro-server/src/serve.rs`
|
||||
- Test: `lib/crates/fabro-server/src/install.rs` or `lib/crates/fabro-server/tests/it/api/install.rs`
|
||||
|
||||
**Approach:**
|
||||
- Refactor the S3 builder path in `serve.rs` so it accepts the resolved `ObjectStoreSettings` plus an env lookup following `process env -> server.env`. The existing `ServerSecrets::{with_env_lookup,get}` API already matches the needed precedence shape; Unit 2 should reuse it rather than inventing a second lookup type.
|
||||
- Start from `AmazonS3Builder::new()`, not `from_env()`. Apply bucket/region from resolved settings, continue to honor settings-driven `endpoint` / `path_style` for hand-configured advanced deployments, and feed only the explicit credential-provider env inputs the runtime needs through the injected lookup.
|
||||
- Runtime-credential path: populate the builder from the lookup only for static-key vars and the `object_store`-supported runtime provider hints (web identity, ECS/EKS container credentials, IMDS-related inputs). Do not load endpoint-override env vars from process env or `server.env`.
|
||||
- Manual validation path: do not add a one-off explicit-credentials parameter. Instead, build a temporary overlay lookup that returns the submitted `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` and suppresses any `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN` values that would otherwise come from process env or `server.env`. Non-credential lookups (for example region defaults) delegate to the same `ServerSecrets::get` the runtime uses, so the overlay composes through `ServerSecrets`, not around it. This keeps validation and startup on the same builder path and ensures the probe uses exactly the typed key pair rather than silently authenticating with stronger ambient credentials that happen to be available in the environment.
|
||||
- If both `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are available from the effective lookup, apply them explicitly with builder setters. If only one of the two keys is present, return a clear static-credential error instead of falling back.
|
||||
- Route `build_artifact_object_store`, `build_slatedb_store`, and `write_artifact_store_metadata()` through the env-aware path so manual credentials work immediately after `/install/finish`, not only on a later restart.
|
||||
- Add a shared install validation helper that:
|
||||
- short-circuits `Local disk`
|
||||
- for S3, builds the real object-store configuration for the chosen credential mode
|
||||
- pins the client to the submitted region (no global-endpoint fallback), so a bucket that lives in a different region surfaces as a distinct error rather than succeeding via transparent cross-region redirect
|
||||
- performs non-mutating access probes on both `artifacts` and `slatedb` prefixes via `object_store.list_with_delimiter(Some(&Path::from(prefix.trim_end_matches('/').to_string())))`
|
||||
- applies a short connect timeout plus a 20-second total timeout for the probe path, with no silent retry in v1
|
||||
- treats any successful response, including an empty result set, as "prefix reachable"
|
||||
- distinguishes, in the install-domain error translation, between `bucket_not_found`, `bucket_region_mismatch`, `access_denied`, and `prefix_access_failed` where the underlying SDK response makes the distinction possible
|
||||
- lives in `install.rs` as install-specific orchestration over the shared builder path in `serve.rs`
|
||||
- wraps lower-level failures in install-step-specific messages such as `Bucket is required.`, `Region is required. Use a value like us-east-1.`, `Enter both AWS access key fields or switch to runtime credentials.`, `Could not access bucket <bucket> in region <region> with the selected credentials.`, and `Fabro reached the bucket but could not verify access to slatedb/ and artifacts/. Validation requires bucket list access plus object access under both prefixes.`
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing builder path in `lib/crates/fabro-server/src/serve.rs`
|
||||
- `ServerSecrets` precedence rules in `lib/crates/fabro-server/src/server_secrets.rs`
|
||||
|
||||
**Technical design:** *(directional only)*
|
||||
|
||||
```text
|
||||
runtime startup:
|
||||
server_secrets = ServerSecrets::load(server_env_path)
|
||||
env_lookup(name) = server_secrets.get(name) // process env first, then server.env
|
||||
build_object_store_from_settings_with_lookup(settings, env_lookup)
|
||||
|
||||
install validation, manual mode:
|
||||
server_secrets = ServerSecrets::load(server_env_path)
|
||||
env_lookup(name) = overlay_aws_static_keys(
|
||||
submitted_keys, // only AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
|
||||
suppress = {AWS_SESSION_TOKEN}, // do not leak ambient STS tokens
|
||||
base = server_secrets.get // same lookup runtime uses
|
||||
)
|
||||
build_object_store_from_settings_with_lookup(settings, env_lookup)
|
||||
|
||||
install validation, runtime mode:
|
||||
server_secrets = ServerSecrets::load(server_env_path)
|
||||
env_lookup(name) = server_secrets.get(name)
|
||||
build_object_store_from_settings_with_lookup(settings, env_lookup)
|
||||
```
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: env-aware S3 builder succeeds when credentials are supplied only through the injected lookup, not process env.
|
||||
- Happy path: manual validation overlay uses the same lookup semantics as runtime and overrides only the submitted static-key pair.
|
||||
- Happy path: runtime-credential mode still succeeds when the deployment provides auth through the supported env/metadata provider paths.
|
||||
- Edge case: the fixed prefixes `artifacts` and `slatedb` (stored without trailing `/` in TOML) still probe the intended `artifacts/` and `slatedb/` key namespaces in the bucket.
|
||||
- Error path: only one of `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` is present on the effective lookup -> clear static-credential error.
|
||||
- Error path: S3 validation failure is reported as an install-step access failure, not an opaque panic.
|
||||
- Error path: `AWS_ENDPOINT`, `AWS_ENDPOINT_URL_S3`, or similar endpoint-override env vars are ignored by the wizard-managed validation/runtime path.
|
||||
- Error path: manual-mode validation with intentionally-wrong submitted keys fails even when a valid distinct AWS key pair (or session token) is available in process env — the overlay must suppress the ambient keys.
|
||||
- Error path: validation against a bucket that lives in a different region than the submitted region reports `bucket_region_mismatch` rather than succeeding via redirect.
|
||||
- Integration: artifact-store metadata writing after `/install/finish` uses the same env-aware path and no longer ignores manual AWS credentials in `server.env`.
|
||||
|
||||
**Verification:**
|
||||
- `serve.rs` tests cover static-credential injection and partial-credential failure.
|
||||
- Install-side validation tests cover local no-op validation and S3 access failure surfacing.
|
||||
|
||||
- [x] **Unit 3: Install router, session state, and finish integration**
|
||||
|
||||
**Goal:** Extend the server-side browser install flow with a new object-store step, redacted session summary, and finish-time persistence that requires the new step.
|
||||
|
||||
**Requirements:** R10-R18 primary (route exposure, session redaction, finish-time persistence and env set/remove, validation surface). Secondary: R1 (step completion order) and R14-R15 (secret lifecycle). Units 1 and 2 own R4-R9 and R7-R15 respectively at the contract/runtime layer.
|
||||
|
||||
**Dependencies:** Unit 1, Unit 2
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/install.rs`
|
||||
- Test: `lib/crates/fabro-server/tests/it/api/install.rs`
|
||||
|
||||
**Approach:**
|
||||
- Add object-store state to `PendingInstall` and introduce the server-side DTOs/enums needed for the new step.
|
||||
- Add:
|
||||
- `POST /install/object-store/test`
|
||||
- `PUT /install/object-store`
|
||||
- redacted `object_store` data in `GET /install/session`
|
||||
- Keep the new object-store routes behind the same install-token auth boundary as the existing install endpoints, and make sure neither session snapshots nor validation/save errors ever echo submitted AWS secret material.
|
||||
- Update `completed_steps()` to return step tokens in wizard order: `server`, `object_store`, `llm`, `github`.
|
||||
- Require the object-store step in `POST /install/finish` before config is written.
|
||||
- Use the new `fabro-install` helper(s) to:
|
||||
- mutate the settings doc for S3 mode
|
||||
- set or remove AWS key vars according to credential mode
|
||||
- Keep the secret-handling pattern aligned with existing install steps:
|
||||
- raw access keys stay only in server memory until finish
|
||||
- session snapshots return only bucket/region/credential mode/configured state
|
||||
- Preserve the current finish-error ergonomics, but split env mutation reporting by direction once removals become first-class: on finish failure, keep `leftover_env_keys` for keys that were inserted before the failure, and add `removed_env_keys` for keys that were successfully removed before the failure. Successful finish responses remain unchanged; the new field is a failure-path recovery signal only.
|
||||
- Keep the broader install rollback behavior unchanged: settings/vault writes still roll back on later failure, while `server.env` mutations remain non-atomic and converge on retry rather than being restored automatically.
|
||||
- If the session already holds manual AWS credentials in memory and the operator revisits the step, blank secret fields on re-submit preserve the stored pair; entering one or both fields switches into replacement mode, and replacement requires both fields.
|
||||
- Any `PUT /install/object-store` with `provider = "local"` or `credential_mode = "runtime"` must clear any previously-stored manual AWS key pair from the in-memory session before returning, so a subsequent `POST /install/object-store/test` does not construct an overlay from stale submitted keys. `POST /install/object-store/test` must reject overlay application when the submitted mode is not `manual`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `post_install_llm_test` + `put_install_llm` in `lib/crates/fabro-server/src/install.rs`
|
||||
- `redacted_llm()` / `redacted_github()` session-shaping helpers
|
||||
- Existing `POST /install/finish` persistence/error pattern
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `POST /install/object-store/test` returns success for `Local disk` without issuing a network probe.
|
||||
- Happy path: `POST /install/object-store/test` validates S3 runtime-credential and manual-credential payloads through the shared builder path.
|
||||
- Happy path: `PUT /install/object-store` with `Local disk` stores session state and marks `object_store` complete.
|
||||
- Happy path: `GET /install/session` includes the redacted object-store summary after save.
|
||||
- Happy path: `POST /install/finish` with local object-store selection writes no AWS key vars.
|
||||
- Happy path: `POST /install/finish` with S3 manual credentials writes both AWS key vars into `server.env`.
|
||||
- Happy path: `POST /install/finish` with S3 runtime credentials removes stale wizard-managed AWS key vars from an existing `server.env` while leaving unmarked keys untouched.
|
||||
- Edge case: reloading the session after manual-credential save shows the chosen mode and bucket/region but not the credential values, and a blank re-submit preserves the in-memory pair.
|
||||
- Error path: `POST /install/finish` before the object-store step is complete returns the existing missing-step style error.
|
||||
- Error path: failed finish after env merge includes AWS key names in `leftover_env_keys`.
|
||||
- Error path: failed finish after a stale-key removal reports the removed names in `removed_env_keys`, leaves the file-level mutation in place, and a retry still converges to the selected mode.
|
||||
- Integration: the object-store step does not disturb existing GitHub token/app finish behavior.
|
||||
|
||||
**Verification:**
|
||||
- Install API integration tests cover new step save/session/finish semantics.
|
||||
- Finish tests prove both env-set and env-remove behavior for AWS keys.
|
||||
|
||||
- [x] **Unit 4: Browser wizard step and review summary**
|
||||
|
||||
**Goal:** Add the new `Object store` UI step, reorder the browser wizard, and surface the redacted object-store summary in the review screen without refactoring the entire install app.
|
||||
|
||||
**Requirements:** R1-R3 (wizard placement/copy), R12-R13 (form inputs for manual credentials), R16 (inline validation errors), R17-R18 (redacted session re-entry), R19 (review rows). Server-side validation and persistence come from Units 2 and 3.
|
||||
|
||||
**Dependencies:** Unit 1, Unit 3
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/fabro-web/app/install-app.tsx`
|
||||
- Modify: `apps/fabro-web/app/install-api.ts`
|
||||
- Test: `apps/fabro-web/app/install-app.test.tsx`
|
||||
- Test: `apps/fabro-web/app/install-api.test.ts`
|
||||
|
||||
**Approach:**
|
||||
- Insert the new step into `INSTALL_STEPS` and `currentStep` routing, using `/install/object-store` between `/install/server` and `/install/llm`.
|
||||
- Update navigation:
|
||||
- `Server` next -> `Object store`
|
||||
- `Object store` back -> `Server`, next -> `LLM`
|
||||
- `LLM` back -> `Object store`
|
||||
- `GitHub` back -> `LLM`
|
||||
- Update the step-preview list in `WelcomeScreen` to include 'Object store — choose local disk or AWS S3 for SlateDB and artifacts' between 'Server URL' and 'LLMs'.
|
||||
- Render provider choice (`Local disk` / `AWS S3`) and credential mode (`Use AWS runtime credentials` / `Enter AWS access key credentials`) using the existing `OptionCard` pattern inside `fieldset`/`legend` wrappers, matching `GithubStrategyPicker`. Selecting `Local disk` hides the S3 sub-form entirely; selecting `Use AWS runtime credentials` hides the access-key inputs.
|
||||
- Default provider on first entry is `Local disk` (the common path becomes a one-click Continue). The S3 sub-form is collapsed until the operator picks `AWS S3`. Even with default-selected `Local disk`, the step must still be completed (`PUT /install/object-store`) before finish.
|
||||
- Add local component state for:
|
||||
- provider choice (`local` vs `s3`)
|
||||
- bucket/region
|
||||
- credential mode (`runtime` vs `access_key`)
|
||||
- access key id / secret access key
|
||||
- Within one unsaved visit to the step, toggling `AWS S3 -> Local disk -> AWS S3` preserves the typed bucket/region/credential fields in local component state so accidental toggles do not wipe work. After a successful save or a session rehydrate, the session snapshot becomes the source of truth and the manual secret inputs return blank.
|
||||
- Client-side preflight before submit: when `AWS S3` is selected, require non-empty `bucket` and `region`; when `Enter AWS access key credentials` is selected, additionally require both `access_key_id` and `secret_access_key`. Error copy matches the tone of the existing `"Enter the canonical server URL before continuing."` style string.
|
||||
- Keep manual credential fields blank on rehydrate; only hydrate redacted summary data from the session response. If the session summary indicates manual credentials are already stored in the pending install state, show helper text such as `Credentials saved. Leave both fields blank to keep them, or enter both fields to replace them.` Blank submit preserves the stored pair; entering either field requires both and replaces the stored pair.
|
||||
- Extend the thin install API wrapper with new test/save helpers for the object-store step.
|
||||
- Reuse the existing `StepPanel` pattern and inline error handling; do not split the install wizard into new route files in this pass.
|
||||
- Submit behavior: local mode saves immediately and shows `Saving...` with the primary action disabled while the request is in flight. S3 mode runs `POST /install/object-store/test` before save and shows `Checking access...` on the primary action while validation/save is in flight. If the validation probe exceeds the server-side 20-second timeout, show `Timed out while checking S3 access. Verify the bucket, region, and network path, then try again.`
|
||||
- Field order and copy are fixed for consistency: provider choice first; if `AWS S3` is selected, show `Bucket` (placeholder `my-fabro-data`), `Region` (placeholder `us-east-1`), then the credential-mode picker. If manual credentials are selected, show `AWS access key ID` and `AWS secret access key` in that order. Secret inputs are password-masked and use `autocomplete="off"`, `autocapitalize="none"`, and `spellcheck={false}`.
|
||||
- Keep the form behavior aligned with the existing wizard's accessibility/responsiveness baseline: explicit labels, keyboard-reachable provider/credential-mode controls, password-masked secret input, and a single-column layout that still reads cleanly on narrow screens. Inline validation errors should render in an `aria-live` region with `role="alert"`. Client-side preflight focuses the first invalid field. Selecting `AWS S3` moves focus to the `Bucket` input, selecting manual credentials moves focus to `AWS access key ID`, and `OptionCard` controls remain keyboard activatable via Enter/Space.
|
||||
- Extend `ReviewScreen` with object-store summary rows, implemented with `SummaryRow`:
|
||||
- Local: one row `Object store` -> `Local disk`.
|
||||
- S3: `Object store` -> `AWS S3`; `Bucket` -> value (monospaced); `Region` -> value (monospaced); `Credentials` -> `Runtime credentials` or `Access key` (static label only; no redacted key identifier is shown); `Prefixes` -> `slatedb/, artifacts/` (single row).
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing `LLM` and `GitHub token` submit flows in `apps/fabro-web/app/install-app.tsx`
|
||||
- Existing "configured but redacted" hydration pattern from `hydrateProviderSelection()` and GitHub username rehydrate behavior
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: wizard stepper/order now includes `Object store` between `Server` and `LLM`.
|
||||
- Happy path: local selection advances to `LLM` and does not require bucket/region/AWS credential fields.
|
||||
- Happy path: S3 runtime-credential selection requires bucket/region and surfaces runtime-credential copy.
|
||||
- Happy path: S3 manual-credential selection requires bucket/region/access key id/secret access key before save.
|
||||
- Edge case: rehydrated session with S3 manual mode preserves bucket/region/mode, leaves secret fields blank, and shows the "credentials saved" helper text.
|
||||
- Edge case: review screen shows `Local disk` or the redacted S3 summary as appropriate.
|
||||
- Error path: object-store validation errors from the server render inline on the step.
|
||||
- Error path: client-side preflight errors, access-denied errors, and timeout errors use the agreed copy and land focus on the appropriate field/error region.
|
||||
- Integration: existing GitHub callback/done tests still pass after `completed_steps` and step order change.
|
||||
|
||||
**Verification:**
|
||||
- Web tests cover new step routing, validation gating, rehydration, and review summary.
|
||||
- The new step integrates without breaking the existing install token and GitHub callback flows.
|
||||
|
||||
- [x] **Unit 5: Documentation and generated surfaces**
|
||||
|
||||
**Goal:** Bring the user-facing docs and generated/bundled outputs into sync with the new wizard step and server-runtime secret surface.
|
||||
|
||||
**Requirements:** R14-R15 documentation (server.env runtime secret surface for AWS keys) and R8-R9 (scope of the wizard-managed modes); user-facing docs for the new step exist because Units 3 and 4 introduce the feature.
|
||||
|
||||
**Dependencies:** Unit 3, Unit 4
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/administration/deploy-server.mdx`
|
||||
- Modify: `docs/administration/server-configuration.mdx`
|
||||
- Modify (generated): `lib/crates/fabro-spa/assets/`
|
||||
|
||||
**Approach:**
|
||||
- Update the "first run: web install wizard" section in `deploy-server.mdx` so it no longer says the wizard only configures LLMs, server URL, and GitHub.
|
||||
- Update the server-runtime secret documentation to include the optional AWS object-store keys and explain that they resolve with `process env -> server.env`.
|
||||
- Keep the wizard docs explicit that S3-compatible backends still require manual configuration.
|
||||
- Document that custom `endpoint` / `path_style` object-store settings remain a manual advanced-configuration path. The browser wizard neither prompts for them nor shows them on the review screen, even though the runtime still honors them for hand-edited configurations outside the wizard-managed flow.
|
||||
- Document a recommended minimum IAM policy for manual-credential mode (bucket-scoped, prefix-scoped to `artifacts/` and `slatedb/`, `s3:ListBucket` + `s3:GetObject`/`PutObject`/`DeleteObject` only) and recommend provisioning an IAM user dedicated to Fabro rather than reusing broad credentials. Call out that STS/session tokens are not supported in manual mode.
|
||||
- Add an operator recovery runbook entry for failed finish requests only: if `POST /install/finish` returns `leftover_env_keys` containing AWS key names, the managed object-store keys likely remain in `server.env`; the operator should retry the install or explicitly remove the managed object-store lines before abandoning the host. Rotation is not required solely because finish failed after an atomic `0600` write, but remains the operator's fallback if they no longer trust the host boundary. If the failure response returns `removed_env_keys` for AWS key names instead, treat it as informational: the previous manual-key path was already cleared and the operator should simply complete the retry before restart.
|
||||
- Regenerate the bundled SPA assets after the TypeScript change so the shipped binary stays in sync with the source.
|
||||
|
||||
**Test expectation:** none -- documentation and generated bundle refresh only. Behavioral verification comes from Units 3 and 4.
|
||||
|
||||
**Verification:**
|
||||
- User-facing docs mention the new object-store step and the AWS-only/non-STS constraints.
|
||||
- The committed SPA bundle matches the updated `apps/fabro-web` source.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** `GET /install/session` now returns one more redacted section. The browser wizard adds one more stateful step before LLMs. `POST /install/finish` now feeds object-store settings/env edits into `fabro-install`, and the same env-aware object-store builder is used by install-time validation, post-install artifact metadata writing, and normal server startup.
|
||||
- **Attack surface:** the new install endpoints stay within the existing install-token-protected router, but they handle AWS credential input. Secret values therefore need to stay out of session payloads, response bodies, and log messages across validation, save, and finish paths.
|
||||
- **Error propagation:** object-store validation failures should stay as `422` install-step errors that `readInstallError()` can display inline, with stable install-domain strings for missing fields, partial static credentials, access failures, permission failures, and timeouts. Finish-time persistence failures continue to return `500` plus env-mutation summaries for inserted vs removed AWS env keys.
|
||||
- **State lifecycle risks:** stale manual AWS keys are the main lifecycle hazard. The plan addresses that with explicit removal support for non-manual modes and by keeping finish failure reporting explicit when env merges have already happened.
|
||||
- **Persistence semantics:** install-finish remains partially non-atomic because `server.env` is not rolled back after later failures. This feature keeps that existing behavior, so the implementation needs explicit tests showing that both AWS-key insertion and AWS-key removal converge correctly on retry.
|
||||
- **API surface parity:** this change affects the browser install contract, the generated TypeScript client, and the user-visible wizard flow. The terminal install flow is intentionally unchanged in this pass.
|
||||
- **Integration coverage:** the critical cross-layer scenario is "manual AWS credentials entered in the wizard -> validated through the same lookup semantics runtime uses -> persisted to `server.env` -> artifact metadata write and later startup both use them." Unit tests on one side or the other are not enough by themselves.
|
||||
- **Unchanged invariants:** `server.storage.root` remains local disk, the wizard still exits the server on successful finish, GitHub and LLM install semantics are unchanged aside from step ordering, and non-AWS/S3-compatible options remain manual-only.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Manual AWS keys are persisted but not consumed by the runtime object-store builder | Refactor the builder path first and cover both startup and post-install metadata writing with the same env-aware helper |
|
||||
| Stale AWS keys in `server.env` silently override the chosen runtime-credential mode on a later boot | Add explicit env-key removal support and exercise it in finish-path tests |
|
||||
| Install-time validation accidentally mutates the bucket | Use non-writing prefix probes instead of metadata writes during the wizard step |
|
||||
| The monolithic `install-app.tsx` change set becomes brittle | Keep the feature local to the existing `StepPanel` pattern and add focused route/rehydration/review tests |
|
||||
| Generated contract drift between OpenAPI, TS client, and UI wrapper | Treat the regenerated `fabro-api-client` files as part of the unit, and keep `apps/fabro-web/app/install-api.ts` aligned with the new session/save shapes |
|
||||
| Validation relies on list permissions that some custom IAM policies may omit | Before selecting the probe shape, enumerate the exact S3 actions the runtime performs at steady state (SlateDB + artifact writers) and pick a probe that uses a strict subset of those permissions. If `s3:ListBucket` cannot be avoided, document it in the wizard error copy ("access to the configured bucket/prefix could not be verified — validation requires `s3:ListBucket`") and in the recommended IAM policy in Unit 5 |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- The operator docs should explicitly distinguish workflow-visible secrets (vault) from server runtime secrets (`server.env`), since this feature adds a new runtime-secret case.
|
||||
- The implementation should refresh the embedded SPA bundle after the TypeScript changes so the Rust binary ships the updated install UI.
|
||||
- If the feature ships before CLI parity, the docs should avoid implying that `fabro install` and the browser wizard offer the same object-store prompts.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin document:** [docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md](/Users/bhelmkamp/p/fabro-sh/fabro-4/docs/brainstorms/2026-04-22-web-install-object-store-choice-requirements.md:1)
|
||||
- Related code: [lib/crates/fabro-server/src/install.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-server/src/install.rs:1)
|
||||
- Related code: [lib/crates/fabro-server/src/serve.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-server/src/serve.rs:323)
|
||||
- Related code: [lib/crates/fabro-server/src/server_secrets.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-server/src/server_secrets.rs:1)
|
||||
- Related code: [lib/crates/fabro-server/src/security_headers.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-server/src/security_headers.rs:1)
|
||||
- Related code: [lib/crates/fabro-install/src/lib.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-install/src/lib.rs:123)
|
||||
- Related code: [lib/crates/fabro-store/src/artifact_store.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-store/src/artifact_store.rs:42)
|
||||
- Related code: [lib/crates/fabro-store/src/slate/mod.rs](/Users/bhelmkamp/p/fabro-sh/fabro-4/lib/crates/fabro-store/src/slate/mod.rs:53)
|
||||
- Related code: [apps/fabro-web/app/install-app.tsx](/Users/bhelmkamp/p/fabro-sh/fabro-4/apps/fabro-web/app/install-app.tsx:43)
|
||||
- Related code: [docs/administration/deploy-server.mdx](/Users/bhelmkamp/p/fabro-sh/fabro-4/docs/administration/deploy-server.mdx:30)
|
||||
- Related code: [docs/administration/server-configuration.mdx](/Users/bhelmkamp/p/fabro-sh/fabro-4/docs/administration/server-configuration.mdx:270)
|
||||
- External docs: https://docs.rs/object_store/latest/object_store/
|
||||
- External docs: https://docs.rs/object_store/latest/object_store/aws/struct.AmazonS3Builder.html
|
||||
|
|
@ -1,483 +0,0 @@
|
|||
---
|
||||
title: "refactor: Lock down server-level secrets handling"
|
||||
type: refactor
|
||||
status: active
|
||||
date: 2026-04-22
|
||||
deepened: 2026-04-23
|
||||
---
|
||||
|
||||
# Lock down server-level secrets handling
|
||||
|
||||
## Overview
|
||||
|
||||
Server-level secrets (SESSION_SECRET, FABRO_DEV_TOKEN, GitHub App credentials, JWT keypair) flow through three independent paths today:
|
||||
|
||||
- `ServerSecrets::get` reads process env *live* on every call, with on-disk envfile fallback.
|
||||
- `load_or_create_local_session_secret` reads env first, then envfile, then auto-generates if missing.
|
||||
- `execute_foreground` mutates parent process env via `std::env::set_var` so the in-process server's live env reads see the resolved value.
|
||||
|
||||
Worker subprocess scrubs `FABRO_DEV_TOKEN`; daemon spawn does not — accidental inconsistency.
|
||||
|
||||
This refactor:
|
||||
|
||||
- **Makes `ServerSecrets` snapshot-based.** Reads env and envfile *once* at construction, exposes the merged result. Both env and file remain valid sources (env wins on conflict — 12-factor convention). The bug was *live* env reads coupled with parent-process mutation, not env reads themselves.
|
||||
- **Eliminates parent-process env mutation.** With snapshot semantics, the foreground `set_var` becomes unnecessary; the daemon `cmd.env(SESSION_SECRET)` becomes redundant.
|
||||
- **CLI install and web install share a common orchestration path for `server.env` writes.** Coordinated install flows may update server-level secrets while a server is running, but they must also own restart/handoff (web install already does this via `/install/finish`).
|
||||
- **Worker and render-graph subprocesses use `env_clear` + strict fail-closed allowlists.** Worker is the trust boundary — it dispatches user-supplied workflow stages via `Sandbox`. Daemon child inherits parent env unchanged (12-factor pattern works).
|
||||
- **Foreground and daemon startup share one validation path.** Daemon preflight builds the same `ServerSecrets` snapshot and runs the same server-side auth/startup validation foreground does — no separate parent-CLI validator with drift risk.
|
||||
- **Legacy `FABRO_JWT_PRIVATE_KEY` / `FABRO_JWT_PUBLIC_KEY` drift is removed.** SESSION_SECRET remains the sole auth master (HKDF source for cookie key + JWT signing key per `2026-04-19-003-feat-cli-auth-login-plan.md`); install stops generating those keys and actively removes them from `server.env` on subsequent runs.
|
||||
- **`clippy::disallowed_methods` denies `std::env::set_var` / `remove_var`** workspace-wide *including tests*; narrow documented post-fork/pre-exec exceptions only.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
- **Live env reads + parent-process mutation is unsound.** `std::env::set_var` in `execute_foreground` mutates global process state inside an async runtime. Rust 2024 marks this `unsafe` because it races concurrent readers. Workspace is on 2021; moving to 2024 forces the issue. The set_var is load-bearing because `ServerSecrets::get` reads env *live*, not at construction.
|
||||
- **Worker subprocess env leakage.** Workers run user-supplied workflow stages (via `Sandbox`). Today they inherit the operator's full process env — any credential the operator exported leaks to user-controlled commands.
|
||||
- **`SESSION_SECRET` autogeneration is the real startup bypass.** `load_or_create_local_session_secret` mints a value and writes the envfile if missing — a server can boot with a freshly-minted secret that bypassed the install flow's full setup. Same precedent already removed for `FABRO_DEV_TOKEN` (commit `7cb6c65d5`); SESSION_SECRET is the leftover.
|
||||
- **`FABRO_JWT_*` is stale config drift.** The CLI auth migration (`2026-04-19-003-feat-cli-auth-login-plan.md`) consolidated cookie + JWT signing into a single HKDF chain rooted at SESSION_SECRET. The legacy `FABRO_JWT_PRIVATE_KEY` / `FABRO_JWT_PUBLIC_KEY` envfile entries no longer participate in the runtime auth model but install still generates them and diagnostics still inspects them — they obscure the actual auth model and risk operator confusion.
|
||||
- **CLI install and web install have drifted into separate persistence/restart behaviors.** They write to `server.env` via parallel code paths today; the bug-surface of "what does install actually persist" is twice as large as it should be. They should reconverge on a shared orchestration with consistent contracts.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. `ServerSecrets` reads env and envfile *once* at boot and exposes the merged snapshot. No live env reads from `ServerSecrets::get` or its callers on the resolution path. Env wins on conflict.
|
||||
- R2. `fabro server start` does not generate any server-level secret. Missing → fail fast pointing at the install flows (CLI or web) or direct env-set.
|
||||
- R3. `execute_foreground` does not mutate parent process env.
|
||||
- R4. `execute_daemon` does not pass server-level secrets via `cmd.env(...)` (no longer needed; daemon child reads env+file at its own boot).
|
||||
- R5. Worker and render-graph subprocesses use `env_clear` + strict fail-closed allowlists. New inherited env vars require demonstrated need plus tests. Authority-bearing values re-injected explicitly.
|
||||
- R6. Tests use construction-time env stubs (via a small `EnvSource` trait) or explicit child-process `Command::env`. No test mutates process-wide env.
|
||||
- R7. Foreground and daemon startup use one shared validation path; required secrets mirror current auth rules (SESSION_SECRET always; FABRO_DEV_TOKEN when dev-token auth enabled; GITHUB_APP_CLIENT_SECRET when GitHub auth enabled).
|
||||
- R8. CLI install and web install share orchestration for coordinated `server.env` writes and restart/handoff.
|
||||
- R9. `FABRO_JWT_PRIVATE_KEY` / `FABRO_JWT_PUBLIC_KEY` are removed from install output, diagnostics, docs, and existing `server.env` files during install flows.
|
||||
- R10. Behavior changes are documented in a strategy doc and enforced via workspace-wide `clippy::disallowed_methods` — including tests — with narrow documented exceptions only.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
**In scope, active** — server-level secrets read via `state.server_secret(...)`, sourced from process env or `<storage>/server.env`:
|
||||
|
||||
| Secret | Consumer | Sources |
|
||||
|---|---|---|
|
||||
| `SESSION_SECRET` | `AppState::session_key` (`server.rs:713`); HKDF source for cookie key + JWT signing key | env (12-factor) or `server.env` (install) |
|
||||
| `FABRO_DEV_TOKEN` | `worker_command` (`server.rs:3825`) | env or `server.env` |
|
||||
| `GITHUB_APP_PRIVATE_KEY` | `AppState::github_credentials` (`server.rs:726`) | env or `server.env` |
|
||||
| `GITHUB_APP_WEBHOOK_SECRET` | `github_webhook_routes` (`server.rs:983`) | env or `server.env` |
|
||||
| `GITHUB_APP_CLIENT_SECRET` | `web_auth.rs:536` | env or `server.env` |
|
||||
|
||||
Both install flows (CLI `fabro install` and web install via `/install/finish`) write the envfile; neither mutates process env. Operators on 12-factor PaaS set secrets in platform env; operators on local/server installs use one of the install flows.
|
||||
|
||||
**In scope, removal targets:**
|
||||
|
||||
- `FABRO_JWT_PRIVATE_KEY`, `FABRO_JWT_PUBLIC_KEY` — legacy entries that no longer participate in the runtime auth model. Install stops generating them; diagnostics stops inspecting them; existing entries are actively removed from `server.env` on subsequent install flows.
|
||||
|
||||
**Startup-critical subset:** SESSION_SECRET (always), FABRO_DEV_TOKEN (when dev-token auth is enabled), and GITHUB_APP_CLIENT_SECRET (when GitHub auth is enabled). The other in-scope active secrets (GITHUB_APP_PRIVATE_KEY, GITHUB_APP_WEBHOOK_SECRET) are not boot blockers — they continue to surface where they did before (conditional route mounts, per-request errors). The plan does not promote every server secret to a startup gate.
|
||||
|
||||
**Out of scope:**
|
||||
|
||||
- **Vault + `ProviderCredentials`** (`secrets.json`, REST-managed, runtime-mutable). Different lifecycle.
|
||||
- **Legacy vault-or-process-env helper for run-level credentials** (`GITHUB_TOKEN`, `DAYTONA_API_KEY`). Same env-as-source pattern, different track at the time of this plan.
|
||||
- **`{{ env.FOO }}` config interpolation.** Operator-supplied templating, different feature.
|
||||
- **Workflow-stage env (Sandbox).** Stages run inside `Sandbox` (local/Docker/Daytona); their env is configured by the workflow definition + Sandbox config. Anything a workflow stage needs to execute (e.g. `git push` requiring `GITHUB_TOKEN`) routes via Vault → Sandbox, not subprocess inheritance.
|
||||
- **`validate_api_key` `set_var` in `provider_auth.rs`.** Vault-side smell, deferred.
|
||||
- **Tailscale and `bun --watch-web` spawns.** Different surfaces.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant code
|
||||
|
||||
- `lib/crates/fabro-server/src/server_secrets.rs` — `ServerSecrets` definition; today's live `env_lookup` closure is the bug.
|
||||
- `lib/crates/fabro-server/src/server.rs:697-699` — `state.server_secret(name)` wrapper.
|
||||
- `lib/crates/fabro-server/src/server.rs:703,712-715` and `jwt_auth.rs:84-99` — `resolve_auth_mode_with_lookup`, currently routed through the live `env_lookup`.
|
||||
- `lib/crates/fabro-server/src/server.rs:3776-3834` (`worker_command`) — worker spawn site.
|
||||
- `lib/crates/fabro-server/src/server.rs:7232-7235` — `__render-graph` spawn site.
|
||||
- `lib/crates/fabro-cli/src/commands/server/start.rs:229-274` — `load_or_create_local_session_secret` and `execute_foreground` `set_var` block.
|
||||
- `lib/crates/fabro-cli/src/commands/server/start.rs:319-362` — `execute_daemon` spawn flow.
|
||||
- `lib/crates/fabro-cli/src/commands/install.rs:1816,1856,1864` — install SESSION_SECRET generation and persistence.
|
||||
- `lib/crates/fabro-config/src/envfile.rs:204-256` — `write_env_entries`, already atomic via tmp + fsync + rename.
|
||||
- `Cargo.toml:111` and `clippy.toml` — existing `disallowed_methods` mechanism.
|
||||
|
||||
### Institutional learnings
|
||||
|
||||
- `docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md` — architectural anchor: server is canonical, install provisions, request-time reads from store.
|
||||
- `docs/plans/2026-04-19-003-feat-cli-auth-login-plan.md` — `SESSION_SECRET` is now HKDF master for JWT signing + cookie key. Higher stakes.
|
||||
- `docs/plans/2026-04-18-001-feat-webhook-strategy-plan.md` — webhook secret already plumbed via `AppState` from the resolved store.
|
||||
- Commit `7cb6c65d5` — "Remove dev-token minting from server start." SESSION_SECRET autogenerate is the leftover.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **`ServerSecrets` is a snapshot, not a live reader.** A small `EnvSource` trait exists *only at construction time* and immediately materializes into an owned `HashMap<String, String>`. No trait object or callback survives into runtime lookup. `get(name)` returns from the merged (env ∪ file) snapshot; env wins on conflict (12-factor). Role: the *resolved-secrets API*; the source mix is the operator's choice.
|
||||
- **Production uses a real process-env `EnvSource`; tests use a map-backed stub.** No live env reads anywhere on the secret resolution path. No `EnvLookup` closure surviving into runtime.
|
||||
- **`resolve_auth_mode_with_lookup` migrates to read from `server_secrets`, not raw env.** Closure passed in delegates to `self.server_secrets.get(...)`. Without this, auth-mode resolution remains a live env reader.
|
||||
- **Worker and render-graph allowlists are strict fail-closed.** Worker is the trust boundary (dispatches user stages via `Sandbox`); render-graph is hygiene. New inherited env vars require demonstrated need (failing test) and intentional addition. Proxy/cert env vars are not auto-inherited.
|
||||
- Worker list: `PATH`, `HOME`, `TMPDIR`, `USER`, `RUST_LOG`, `RUST_BACKTRACE`, `FABRO_HOME`, `FABRO_STORAGE_ROOT`. Plus explicit `FABRO_DEV_TOKEN` re-injection when dev-token auth is enabled.
|
||||
- Render-graph list: `PATH`, `HOME`, `TMPDIR`. Plus explicit `FABRO_TELEMETRY=off`.
|
||||
- **Daemon child spawn inherits parent env unchanged** (modulo existing `cmd.env_remove("FABRO_JSON")` for output-format hygiene). The daemon is fabro's own server code, not a security boundary against itself. 12-factor env vars (SESSION_SECRET, AWS_*, RAILWAY_*) flow through naturally to the daemon child's snapshot.
|
||||
- **Daemon preflight reuses the same shared auth/startup validation as foreground startup.** Both modes construct the same `ServerSecrets` snapshot and call the same server-side validation logic (today's `jwt_auth::resolve_auth_mode_with_lookup` already encodes "what's required for this auth mode" — that's the shared path). No separate parent-CLI validator with drift risk. Required secrets remain exactly the current startup-critical set: SESSION_SECRET (always), FABRO_DEV_TOKEN (when dev-token auth enabled), GITHUB_APP_CLIENT_SECRET (when GitHub auth enabled). GITHUB_APP_PRIVATE_KEY and GITHUB_APP_WEBHOOK_SECRET remain in-scope server secrets but are not new universal boot blockers.
|
||||
- **Install coordination policy lives in shared install orchestration, not in low-level envfile helpers.** Coordinated install flows (CLI and web) may write to `server.env` while a server is running — but only when they also own restart/handoff. Web install already does this via `/install/finish`. CLI install joins the same orchestration. Manual edits to `server.env` outside the orchestration still require operator restart discipline.
|
||||
- **`pub(crate) server_secrets` field tightened to `pub(super)`.** No production code legitimately bypasses the wrapper.
|
||||
- **Workspace-wide clippy ban including tests.** Add `std::env::set_var`/`remove_var` to `clippy.toml` `disallowed-methods` — applies to production AND test code. Tests must use construction-time `EnvSource` stubs or explicit child-process `Command::env`. Narrow documented exceptions only (`fabro-telemetry/src/spawn.rs:73-76` post-fork pre-execvp).
|
||||
- **Legacy `FABRO_JWT_*` is removed, not preserved.** Install stops generating; diagnostics stops reading; existing envfile entries are actively cleaned up on subsequent install flows. SESSION_SECRET is the sole auth master.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved during planning
|
||||
|
||||
- **`ServerSecrets` reads env AND file, snapshots, env wins.** Process env is a legitimate source (12-factor). The bug was *live* env reads + parent mutation, not env-as-source.
|
||||
- **`EnvSource` exists only at construction time.** A small trait used to materialize an owned `HashMap` once; no callback or trait object survives into runtime lookup. Production uses a real process-env source; tests use a map-backed stub.
|
||||
- **Daemon child inherits parent env; only worker/render-graph scrub.** Daemon is fabro's own server code and must see whatever the operator/platform set in env. Worker is the trust boundary (dispatches user stages via `Sandbox`).
|
||||
- **No carve-out for AWS / cloud-platform credentials.** Daemon inherits parent env, so AWS env names reach the object-store layer naturally.
|
||||
- **Active scope is 5 server secrets plus 2 legacy removal targets.** SESSION_SECRET, FABRO_DEV_TOKEN, GITHUB_APP_PRIVATE_KEY, GITHUB_APP_WEBHOOK_SECRET, GITHUB_APP_CLIENT_SECRET are active. FABRO_JWT_PRIVATE_KEY and FABRO_JWT_PUBLIC_KEY are legacy — install stops generating them; diagnostics stops reading them; existing entries are actively removed.
|
||||
- **Workflow stage env is the Sandbox's job.** This plan does not address workflow `bash`/`git`/etc. stage env — that's per-workflow Sandbox config. Workflows requiring credentials route them through Vault.
|
||||
- **Web install keeps its existing restart-handoff contract.** `/install/finish` still returns the restart URL and the SPA still waits for the server to come back. No new `restart_required` flag, no manual-restart message proposal, no API surface change.
|
||||
- **CLI and web install share orchestration for coordinated writes while running.** Blanket "refuse-while-running" is out. The orchestration is responsible for restart/handoff; both flows call into it.
|
||||
- **Test migration shape:** full migration in Unit 1. `ServerSecrets::with_env_lookup` is deleted; tests use either `ServerSecrets::load(path, env_source)` with a map-backed `EnvSource` stub, or `provision_server_secrets(env_path, &[(name,value)])` helper (file-based injection). No `#[cfg(test)]` backdoor.
|
||||
- **Visibility tightening:** `pub(crate) server_secrets` at `server.rs:579` → `pub(super)` as part of Unit 1.
|
||||
- **Install lock window for interactive flows:** install orchestration's job; `gather inputs → persist + restart-handoff`. Serialization window is sub-second regardless of OAuth duration.
|
||||
- **Dev-loop friction:** no `--quick` flag. Contributors run `fabro install` or set secrets directly via env (`SESSION_SECRET=$(openssl rand -hex 32) cargo run -- server start` works under the env-as-source model).
|
||||
- **Compliance-driven rotation:** deferred. Captured as a known limitation in the strategy doc.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [ ] **Unit 1: `ServerSecrets` becomes a snapshot built from `EnvSource` (construction-time only)**
|
||||
|
||||
**Goal:** `ServerSecrets` reads env and envfile *once* at construction via a small `EnvSource` trait, materializes both into owned `HashMap`s, and exposes the merged snapshot. No trait object or closure survives into runtime lookup. Auth-mode resolution stops being a live env reader.
|
||||
|
||||
**Requirements:** R1, R6
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/server_secrets.rs` — replace `env_lookup` closure field with `env_entries: HashMap<String, String>` (owned). Introduce a small `EnvSource` trait used *only* at construction:
|
||||
- `pub trait EnvSource { fn snapshot(&self) -> HashMap<String, String>; }`
|
||||
- `pub struct ProcessEnv;` impls `snapshot` via `std::env::vars().collect()`.
|
||||
- `pub struct StubEnv(pub HashMap<String, String>);` impls `snapshot` by cloning. (cfg-test or cfg(any(test, feature = "test-support")) — implementer picks based on existing patterns.)
|
||||
- `pub fn load(path: PathBuf, env: &dyn EnvSource) -> Result<Self, Error>` — calls `env.snapshot()` once, stores the result, never references `env` again.
|
||||
- `get(name)` returns `self.env_entries.get(name).cloned().or_else(|| self.file_entries.get(name).cloned())`.
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` — `build_app_state` accepts pre-built `ServerSecrets` and `AuthMode` from the caller (no longer constructs `ServerSecrets` itself). The single production caller is `serve_command` (via `resolve_startup` from Unit 4); test helpers construct both in the same way. Tighten `pub(crate) server_secrets` field at `server.rs:579` to `pub(super)`. Migrate the `resolve_auth_mode_with_lookup` call (`server.rs:703`) to pass a closure delegating to `self.server_secrets.get(...)`.
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs:512` and `install.rs:910,965,2108` — minimal API migration: `ServerSecrets::load(path, &ProcessEnv)` instead of `with_env_lookup` at any *non-startup* construction sites (e.g. install-time inspection, install_object_store_lookup test helper). The startup construction sites at `serve.rs:594-607` are NOT modified by Unit 1 — Unit 4 collapses them into a single `resolve_startup(...)` call. To keep the workspace compiling between Unit 1 and Unit 4, Unit 1 may leave a temporary `ServerSecrets::load(path, &ProcessEnv)` call at `serve.rs:594` if needed; Unit 4 deletes it. Sequencing is documented in Unit 4's Dependencies.
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs:7864-7885` — replace `server_secrets_resolve_process_env_before_server_env` with a snapshot test using `StubEnv` (assert env-wins-on-conflict from the snapshot).
|
||||
- Modify: `lib/crates/fabro-server/tests/it/api/cli_auth_token.rs:34`, `routing.rs:21,35-36`, `tcp.rs:28,68,173-174`, `lib/crates/fabro-cli/tests/it/support/auth_harness.rs:39-86` — migrate from `env_lookup` injection (for *secret* values) to constructing the test's `ServerSecrets` with `&StubEnv(...)`, or writing to a temp `server.env` via the `provision_server_secrets(env_path, &[(name, value)])` helper. Tests that currently pass `env_lookup` only to feed secret values into `ServerSecrets` switch to the new mechanism.
|
||||
- Modify: test helpers like `create_app_state_with_env_lookup` (`server.rs:2488` and similar) — once `build_app_state` (`server.rs:2631`) requires precomputed `ServerSecrets` and `AuthMode`, the helpers must produce both internally and pass them through. The `env_lookup` parameter on these helpers is *retained* (still consumed downstream by `resolve_canonical_origin` at `server.rs:708` and slack `{{ env.FOO }}` interpolation at `server.rs:2676`, both out of scope). New shape: helper accepts an additional `&dyn EnvSource` parameter (or constructs a `StubEnv`/`ProcessEnv` based on the call site's intent), internally calls `resolve_startup(...)` (or directly constructs `ServerSecrets` + computes `AuthMode` if the helper bypasses settings — auditor's choice per call site), and passes the resulting `ServerSecrets` and `AuthMode` into `build_app_state`. Tests that set up specific auth modes (e.g. dev-token enabled) now thread settings + `EnvSource` through the helper rather than relying on a single closure to drive both secret resolution and auth-mode computation.
|
||||
- Test: existing files plus new snapshot-semantics tests in `server_secrets.rs`.
|
||||
|
||||
**Approach:**
|
||||
- `EnvSource::snapshot()` is called exactly once during `ServerSecrets::load`. The trait reference is dropped immediately after; only the materialized `HashMap` is retained. No risk of live env reads via trait object dispatch.
|
||||
- Object-store credential resolution at `serve.rs:340-401, 520-522, 540-542` uses `std::env::var(...)` directly (daemon child inherits parent env, so AWS names are present).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `ServerSecrets::load(path, &StubEnv([("SESSION_SECRET", "from-env")].into()))` returns "from-env" even when file has a different value.
|
||||
- Edge: env empty, file has the value → file wins (single fallback path).
|
||||
- Edge: neither env nor file has the value → `get` returns `None`.
|
||||
- Edge: env has it, file does too, different values → env wins (12-factor).
|
||||
- Edge: missing file path → empty `file_entries`, env-only resolution.
|
||||
- Snapshot semantics: after construction, mutating the source `EnvSource` (or process env, if production source) does not affect `get` returns. The snapshot is owned and immutable.
|
||||
- Auth-mode happy path: `resolve_auth_mode_with_lookup` resolves correctly when secrets come from env, file, or both.
|
||||
- Migration: `cli_auth_token`, `routing`, `tcp`, `auth_harness` tests pass after migration to `EnvSource` stubs.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server -p fabro-cli` passes.
|
||||
- `grep -rn 'std::env::var\|std::env::vars' lib/crates/fabro-server/src/ | grep -v 'serve.rs\|object_store\|spawn_env\|server_secrets.rs'` shows no live env reads on the server-secret resolution path (the only `std::env::vars()` is inside `ProcessEnv::snapshot`, called once at construction).
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 2: Drop foreground `set_var`; drop daemon `cmd.env(SESSION_SECRET)`**
|
||||
|
||||
**Goal:** Eliminate parent-process env mutation. Daemon parent stops passing SESSION_SECRET via `cmd.env`; daemon child reads env+file at its own boot.
|
||||
|
||||
**Requirements:** R3, R4
|
||||
|
||||
**Dependencies:** Unit 1.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/start.rs:265-274` — delete the `set_var`/scopeguard block in `execute_foreground`.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/start.rs:350,352` — `execute_daemon` removes `cmd.env("SESSION_SECRET", ...)`. Keep existing `cmd.env_remove("FABRO_JSON")` (output-format hygiene).
|
||||
- Modify: `lib/crates/fabro-test/src/lib.rs:931` — drop `cmd.env("SESSION_SECRET", ...)` for spawned test servers; tests provision via `server.env` or by setting env on the spawned `Command` explicitly when the test simulates a 12-factor PaaS scenario.
|
||||
- Test: existing `cmd/server_start.rs` tests cover both modes.
|
||||
|
||||
**Approach:**
|
||||
- Unit 1's snapshot semantics make both `set_var` and `cmd.env(SESSION_SECRET)` unnecessary. The in-process foreground server's `ServerSecrets::load(path, &ProcessEnv)` snapshots whatever env the parent CLI had. The daemon child inherits parent env (today's behavior — unchanged) and snapshots it at its own boot.
|
||||
- A `SESSION_SECRET` exported in the operator's parent shell does flow through to both modes — that's the 12-factor design intent.
|
||||
|
||||
**Test scenarios:**
|
||||
|
||||
Tests proving env behavior must use construction-time `EnvSource` stubs or explicit child-process `Command::env` — *not* `std::env::set_var`. Any old test using process-env mutation is migrated as part of this unit (or Unit 7's clippy enforcement will fail it).
|
||||
|
||||
- Happy path (foreground, env source): in-process server constructed with `&StubEnv([("SESSION_SECRET", "from-env")].into())`; running server uses that value.
|
||||
- Happy path (foreground, file source): empty `EnvSource`, value in `server.env`; running server uses the file value.
|
||||
- Happy path (foreground, env-wins): env and file have different values; env wins.
|
||||
- Happy path (daemon, env source): test passes `SESSION_SECRET` to spawned daemon via explicit `Command::env`; daemon child inherits and snapshots it. NOT via `std::env::set_var` in the test process.
|
||||
- Happy path (daemon, file source): no env on the spawned `Command`, value in `server.env`; daemon child uses the file value.
|
||||
|
||||
**Verification:**
|
||||
- `grep -rn 'std::env::set_var\|remove_var' lib/crates/fabro-cli/src/` returns no hits in production code.
|
||||
- `grep -rn 'cmd\.env."SESSION_SECRET"' lib/crates/fabro-cli/src/` returns no hits in production code (test code may still use `Command::env` for daemon spawn simulation; that's fine — it's setting child env, not parent env).
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 3: Worker and render-graph spawns use `env_clear` + strict fail-closed allowlists**
|
||||
|
||||
**Goal:** Worker and render-graph subprocesses inherit only an explicit allowlist. The lists are strict fail-closed — new env vars require demonstrated need (a failing test that proves a workflow execution path needs them) plus intentional addition. Authority-bearing values re-injected explicitly. Daemon child spawn is unchanged (inherits parent env per 12-factor).
|
||||
|
||||
Proxy and TLS env vars (`HTTPS_PROXY`, `SSL_CERT_FILE`, etc.) are *not* inherited unless usage-proven by a failing test and intentionally added — they were never part of the worker's documented contract.
|
||||
|
||||
**Requirements:** R5
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/spawn_env.rs` — defines two helpers:
|
||||
- `apply_worker_env(&mut tokio::process::Command)` — `env_clear` + worker list.
|
||||
- `apply_render_graph_env(&mut tokio::process::Command)` — `env_clear` + render-graph list.
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs:3776-3834` — `worker_command` calls `apply_worker_env(&mut cmd)` first, then existing `cmd.env("FABRO_DEV_TOKEN", token)` re-injection. Remove existing `env_remove("FABRO_JSON")` and `env_remove("FABRO_DEV_TOKEN")` (covered by `env_clear`).
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs:7232-7235` — `__render-graph` spawn calls `apply_render_graph_env(&mut cmd)`. Keep explicit `cmd.env("FABRO_TELEMETRY", "off")`.
|
||||
- Test: new tests in `spawn_env.rs`.
|
||||
|
||||
**Approach:**
|
||||
|
||||
```text
|
||||
WORKER list (each entry has // reason: ... in the source):
|
||||
PATH, HOME, TMPDIR, USER // process essentials
|
||||
RUST_LOG, RUST_BACKTRACE // diagnostics
|
||||
FABRO_HOME, FABRO_STORAGE_ROOT // worker reads its own state
|
||||
+ explicit cmd.env("FABRO_DEV_TOKEN", token) when dev-token auth enabled
|
||||
|
||||
RENDER_GRAPH list:
|
||||
PATH, HOME, TMPDIR
|
||||
+ explicit cmd.env("FABRO_TELEMETRY", "off")
|
||||
|
||||
DAEMON spawn: no helper. Inherits parent env. Keeps existing cmd.env_remove("FABRO_JSON").
|
||||
```
|
||||
|
||||
The lists are constants in `spawn_env.rs`. Each entry is one named env var with a one-line `//` comment. A worker that needs a new env var must be amended in source — that's the entire mechanism.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path (worker): with allowlisted names in parent env, all reach the worker. Random names (`MY_API_KEY`, `NEW_RELIC_LICENSE_KEY`, `DATABASE_URL`, `SESSION_SECRET=leak`) do not.
|
||||
- Happy path (worker, dev-token enabled): `FABRO_DEV_TOKEN` is set to the install-provisioned value via explicit re-injection.
|
||||
- Negative (worker): parent's `FABRO_DEV_TOKEN=garbage` does not reach the worker; explicit re-injection sets the correct value.
|
||||
- Happy path (render-graph): `PATH` and `HOME` reach the child; arbitrary parent vars do not.
|
||||
- Integration (render-graph): with `FABRO_TELEMETRY=on` in parent env, child sees `off` (explicit override after `env_clear`).
|
||||
- Integration: real worker subprocess executes a workflow end-to-end with leak probes (`MY_API_TOKEN=leak`, `NEW_RELIC_LICENSE_KEY=leak`) exported in parent env. Workflow completes; leak probes do not appear in worker logs or in stage env (Sandbox-configured).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-server` passes.
|
||||
- A test asserts the worker spawn sees *only* names in the allowlist plus the explicit `FABRO_DEV_TOKEN` — i.e. "no ambient inheritance except allowlisted names." Same for render-graph. The check operates by enumerating the child's actual env, not by greping `env_remove` calls.
|
||||
- `grep -rn 'env_remove' lib/crates/fabro-server/src/` returns no hits for the worker (`server.rs:3776-3834`) or render-graph (`server.rs:7232-7235`) spawn sites — both routes are now via `env_clear` + the helpers.
|
||||
- `grep -rn 'env_remove' lib/crates/fabro-cli/src/commands/server/start.rs` returns the single intentional `cmd.env_remove("FABRO_JSON")` on the daemon-spawn path (output-format hygiene; daemon child unchanged per Unit 2). No other `env_remove` calls in CLI server code.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 4: Shared startup validation via snapshot-backed `ServerSecrets`**
|
||||
|
||||
**Goal:** Server start no longer auto-generates. Daemon preflight constructs the same `ServerSecrets` snapshot foreground startup uses and runs the *same* server-side auth/startup validation logic. No separate parent-CLI validator that could drift from the server-side rules.
|
||||
|
||||
**Requirements:** R1, R2, R7
|
||||
|
||||
**Dependencies:** Units 1-3.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/startup.rs` (or extend an existing module) — define the shared validation logic. Two entry points around it: a public preflight wrapper (CLI calls this; never sees `ServerSecrets`), and a crate-internal full-resolution function (`serve_command` calls this; consumes the snapshot directly). Both share a single internal implementation so there is no possibility of drift.
|
||||
|
||||
```text
|
||||
// Crate-internal: returns full state for in-process consumption.
|
||||
pub(crate) struct StartupResolution {
|
||||
pub(crate) auth_mode: AuthMode,
|
||||
pub(crate) server_secrets: ServerSecrets,
|
||||
}
|
||||
|
||||
pub(crate) fn resolve_startup(
|
||||
env_path: &Path,
|
||||
env: &dyn EnvSource,
|
||||
settings: &ResolvedServerSettings,
|
||||
) -> Result<StartupResolution, StartupValidationError>
|
||||
|
||||
// Public: thin wrapper for CLI preflight. Calls resolve_startup, drops the
|
||||
// StartupResolution after validating, returns just the success/failure.
|
||||
pub fn validate_startup(
|
||||
env_path: &Path,
|
||||
env: &dyn EnvSource,
|
||||
settings: &ResolvedServerSettings,
|
||||
) -> Result<(), StartupValidationError>
|
||||
```
|
||||
|
||||
Internally `resolve_startup` constructs `ServerSecrets::load(env_path, env)`, then runs the existing `jwt_auth::resolve_auth_mode_with_lookup` against a closure delegating to that snapshot, then returns both. `validate_startup` is `resolve_startup(...).map(|_| ())` — the literal sharing of code makes drift impossible.
|
||||
|
||||
Function takes `&ResolvedServerSettings` (not just `&ServerAuthSettings`) because validation already depends on `server.web.enabled` and `server.integrations.github.client_id` (`jwt_auth.rs:63`) — narrowing would silently weaken the validation surface.
|
||||
|
||||
`StartupValidationError` *wraps or re-uses the existing error type* returned by `jwt_auth::resolve_auth_mode_with_lookup` plus the secret-loading errors from `ServerSecrets::load`. It must cover the full surface that path rejects today: missing required secret (`SESSION_SECRET`, `FABRO_DEV_TOKEN` when dev-token auth enabled, `GITHUB_APP_CLIENT_SECRET` when GitHub auth enabled), invalid secret value (e.g., malformed `FABRO_DEV_TOKEN`), empty auth methods, GitHub auth configured with `server.web.enabled = false`, missing `server.integrations.github.client_id`. Implementer audits `jwt_auth.rs:67` to enumerate the full variant set; the plan does not invent a narrow new one.
|
||||
|
||||
CLI never sees `ServerSecrets`. `ServerSecrets` and `resolve_startup` stay `pub(crate)`. Only `validate_startup` + `EnvSource` + `ProcessEnv` + `StartupValidationError` cross the crate boundary.
|
||||
- Modify: `lib/crates/fabro-server/src/lib.rs` — re-export `startup::{validate_startup, EnvSource, ProcessEnv, StartupValidationError}` from the crate root. **Not** `resolve_startup` or `StartupResolution`.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/start.rs:229-250` — delete `load_or_create_local_session_secret`. Daemon preflight calls `fabro_server::validate_startup(runtime_directory.env_path(), &fabro_server::ProcessEnv, &resolved_settings)`. On `Err`: surface the error to stderr exactly as returned (text comes from the shared error type's `Display`).
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/start.rs:264` — `execute_foreground` does not run a separate validator. The in-process server's `serve_command` calls `resolve_startup` internally and threads the returned `(ServerSecrets, AuthMode)` into `build_app_state` (replacing today's separate `ServerSecrets::with_env_lookup` + `resolve_auth_mode_with_lookup` calls at `serve.rs:594-607`). Single source of truth: foreground's resolution and daemon's preflight share the same internal `resolve_startup`; only the calling surface differs.
|
||||
- Modify: `lib/crates/fabro-server/src/serve.rs:594-607` — replace today's ad-hoc two-step construction with a single `resolve_startup(...)` call. The returned `ServerSecrets` and `AuthMode` are passed into `build_app_state` (per Unit 1's revised signature).
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/server/start.rs:350` — `execute_daemon` runs `validate_startup` before spawning the child.
|
||||
- Test: `tests/it/cmd/server_start.rs` adds missing-secret tests for each required secret across both modes, plus tests demonstrating env-source success, file-source success, and each non-missing-key rejection (empty auth methods, web-disabled with GitHub auth, missing client_id, invalid dev token). A unit test in `fabro-server` asserts `validate_startup` and `resolve_startup` return identical accept/reject decisions for the same inputs.
|
||||
|
||||
**Approach:**
|
||||
- Required secrets remain *exactly* the current startup-critical set, encoded once in the shared validation: SESSION_SECRET (always), FABRO_DEV_TOKEN (when dev-token auth is enabled), GITHUB_APP_CLIENT_SECRET (when GitHub auth is enabled). GITHUB_APP_PRIVATE_KEY and GITHUB_APP_WEBHOOK_SECRET remain in-scope server secrets but are NOT new universal boot blockers — they continue to surface where they did before (conditional route mounts, per-request errors).
|
||||
- Daemon preflight and foreground startup run the same validation function with the same `ServerSecrets` snapshot type; "drift" is impossible by construction.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: required secrets in env → boots (both modes).
|
||||
- Happy path: required secrets in file → boots (both modes).
|
||||
- Happy path: env wins when both present.
|
||||
- Error path (each required secret): missing in both → fail fast naming the secret and both sources (both modes get identical error text because they call the same function).
|
||||
- Negative regression: post-Unit-1 snapshot is built once; mutating env after boot doesn't change the resolved value.
|
||||
|
||||
**Verification:**
|
||||
- `fabro server start` against an empty env and uninstalled storage exits non-zero with the same error message in both `--foreground` and daemon modes.
|
||||
- `fabro server start` with secrets in env (12-factor simulation) boots without any install flow having run.
|
||||
- `grep -rn 'generate_session_secret' lib/crates/fabro-cli/src/commands/server/` returns no hits.
|
||||
- `grep -rn 'ServerSecrets\|server_secrets::\|resolve_startup\|StartupResolution' lib/crates/fabro-cli/` returns no hits — CLI never sees `ServerSecrets` or the internal resolution. Only `validate_startup` is reachable from outside `fabro-server`.
|
||||
- The public secret-related surface from `fabro-server`'s crate root is exactly: `validate_startup`, `EnvSource`, `ProcessEnv`, `StartupValidationError`. Nothing else.
|
||||
- Foreground startup at `serve.rs:594-607` makes exactly one call to compute `(ServerSecrets, AuthMode)` — `resolve_startup(...)` — not a separate `ServerSecrets::with_env_lookup` followed by `resolve_auth_mode_with_lookup`. Both values are passed into `build_app_state`.
|
||||
- `build_app_state` no longer constructs `ServerSecrets`; it accepts pre-built `ServerSecrets` and `AuthMode` from the caller. Verified by reading the signature.
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 5: Shared install orchestration for coordinated `server.env` writes and restart handoff**
|
||||
|
||||
**Goal:** CLI install and web install share a single orchestration layer for `server.env` persistence. Both flows take the same path through generation, persistence, removal of legacy entries, and restart handoff. Web install keeps its existing `/install/finish` restart-handoff contract; CLI install joins the same orchestration. No blanket refuse-while-running policy.
|
||||
|
||||
**Requirements:** R8
|
||||
|
||||
**Dependencies:** Pairs naturally with Unit 6 (legacy `FABRO_JWT_*` removal hooks into the same orchestration). Either order works.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-install/src/lib.rs` — establish the shared orchestration entry points. Both CLI install and web install call into these. Orchestration owns:
|
||||
- input gathering (no `server.env` write, no serialization)
|
||||
- persistence (atomic `server.env` write via existing `envfile::merge_env_file` at `envfile.rs:204-256`)
|
||||
- legacy entry removal (Unit 6 hook for `FABRO_JWT_*`)
|
||||
- restart/handoff (web install via `/install/finish`'s existing restart URL contract; CLI install determines its own handoff — for the in-process case, exit cleanly; for daemon mode, respect today's `fabro server stop` + restart pattern)
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/install.rs:1864, 1213` — route `server.env` writes through the shared orchestration in `fabro-install`. CLI-specific UX (prompts, progress display) remains in `commands/install.rs`; persistence does not.
|
||||
- Modify: `lib/crates/fabro-server/src/install.rs:1313, 1343-1353, 1380` — server-side `/install/finish` handlers route through the same orchestration. The existing `/install/finish` API contract (returns restart URL; SPA polls until server returns) is preserved exactly — no `restart_required` flag, no API surface change.
|
||||
- Test: parity tests in `lib/crates/fabro-install/tests/` prove CLI install and web install take the same persistence/removal path with the same outputs given the same inputs.
|
||||
|
||||
**Approach:**
|
||||
- The shared orchestration in `fabro-install` is the single chokepoint for `server.env` writes from install flows. Manual edits to `server.env` outside the orchestration still require operator restart discipline (documented).
|
||||
- Coordinated install flows MAY write while a server is running — they own restart/handoff. Web install already has the handoff via `/install/finish`; CLI install gets the same primitives.
|
||||
- Two-phase shape: `gather inputs (no serialization)` → `persist + restart-handoff (atomic)`. Serialization window is sub-second regardless of OAuth duration.
|
||||
- No PID-comparison logic, no refuse-while-running predicate, no new chokepoint helper in `fabro-config`. The earlier `write_server_env_serialized` proposal is dropped.
|
||||
|
||||
**Test scenarios:**
|
||||
- Parity: identical install inputs produce identical `server.env` contents and identical removed entries via CLI and web paths.
|
||||
- Happy path (CLI): install on stopped server succeeds; `server.env` updated atomically.
|
||||
- Happy path (web): install on running server completes via `/install/finish`; restart URL returned; SPA reconnects after restart.
|
||||
- Legacy removal: install (CLI or web) on a `server.env` containing `FABRO_JWT_*` entries leaves the file without them (Unit 6 hook).
|
||||
- Negative regression: install-then-start works in the common single-shell CLI sequence.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-install -p fabro-cli` passes including parity tests.
|
||||
- `grep -rn 'envfile::write_env_entries\|envfile::merge_env_file' lib/crates/fabro-cli/src lib/crates/fabro-server/src` shows `server.env` writes routed through `fabro-install` orchestration; no direct calls outside it.
|
||||
- `/install/finish` API contract unchanged (existing OpenAPI schema and SPA reconnect tests pass without modification).
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 6: Remove legacy `FABRO_JWT_*` drift**
|
||||
|
||||
**Goal:** Stop generating `FABRO_JWT_PRIVATE_KEY` / `FABRO_JWT_PUBLIC_KEY`, stop reading them in diagnostics, remove operator/docs references that describe them as auth inputs, and actively remove existing entries from `server.env` during install flows. SESSION_SECRET is the sole auth master.
|
||||
|
||||
**Requirements:** R9
|
||||
|
||||
**Dependencies:** None for code shape; the active-removal hook plugs into Unit 5's shared install orchestration.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/install.rs:1853-1855` — delete `generate_jwt_keypair()` call and the corresponding `("FABRO_JWT_PRIVATE_KEY", ...)` / `("FABRO_JWT_PUBLIC_KEY", ...)` entries from `generated_server_env_pairs`.
|
||||
- Modify: `lib/crates/fabro-server/src/install.rs` (whichever lines mirror the CLI side, surfaced in research) — same deletion on the web install side.
|
||||
- Modify: `lib/crates/fabro-install/src/lib.rs` (Unit 5's shared orchestration) — add `FABRO_JWT_PRIVATE_KEY` and `FABRO_JWT_PUBLIC_KEY` to a `legacy_keys_to_remove` set; the persistence step writes these as removals on every install run.
|
||||
- Modify: `lib/crates/fabro-server/src/diagnostics.rs:540, 552` — remove the `state.server_secret("FABRO_JWT_PUBLIC_KEY")` and `state.server_secret("FABRO_JWT_PRIVATE_KEY")` checks. Adjust diagnostics output and tests accordingly.
|
||||
- Modify: **all** operator-facing references to `FABRO_JWT_PRIVATE_KEY` / `FABRO_JWT_PUBLIC_KEY` across `docs/`, `apps/marketing/`, README, and any in-repo runbook. The criterion is "any mention," not "mention as auth input." Concrete known-stale targets:
|
||||
- `docs/administration/server-configuration.mdx:297` — remove the "future CLI login flows" reference and any surrounding prose treating these as install/runtime secrets.
|
||||
- `docs/administration/server-configuration.mdx:331` — remove the row(s) from the "Server authentication" table.
|
||||
- Implementer must also `grep -rn 'FABRO_JWT_PRIVATE_KEY\|FABRO_JWT_PUBLIC_KEY' docs/ apps/ README*` and either delete or rewrite every hit. Surviving mentions should appear only in (a) the new strategy doc's "removed" section or (b) historical plans under `docs/plans/`.
|
||||
- Modify: install snapshot tests, server.env fixture files, and any insta snapshots that assert on `FABRO_JWT_*` lines — regenerate.
|
||||
- Test: install run against a `server.env` pre-seeded with `FABRO_JWT_*` entries — assert they are absent after install completes.
|
||||
|
||||
**Approach:**
|
||||
- Deletion is the entire change. No deprecation period; no compatibility shim. The keys haven't participated in runtime auth since the CLI auth login migration (`2026-04-19-003`).
|
||||
- Operators upgrading run install once; legacy entries are silently cleaned up. The strategy doc records the cleanup for any operator who notices.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: install on a fresh storage dir produces a `server.env` with no `FABRO_JWT_*` entries.
|
||||
- Happy path (cleanup): install on a `server.env` containing `FABRO_JWT_PRIVATE_KEY=...` and `FABRO_JWT_PUBLIC_KEY=...` produces an updated `server.env` without those keys, with other entries preserved.
|
||||
- Diagnostics: `fabro doctor` (or whichever command surfaces diagnostics) does not mention `FABRO_JWT_*`.
|
||||
|
||||
**Verification:**
|
||||
- `grep -rn 'FABRO_JWT_PRIVATE_KEY\|FABRO_JWT_PUBLIC_KEY\|generate_jwt_keypair' lib/crates apps/ docs/ README*` returns hits *only* in (a) the new strategy doc's "removed" section, (b) historical plan files under `docs/plans/`. No hits in operator-facing docs (`docs/administration/`, `docs/quickstart/`, marketing) or production crate code.
|
||||
- `cargo nextest run -p fabro-cli -p fabro-server` passes with regenerated snapshots.
|
||||
- Mintlify docs build succeeds with the removed entries (no broken anchors/links from other pages that referenced the JWT-key sections).
|
||||
|
||||
---
|
||||
|
||||
- [ ] **Unit 7: Strategy doc + workspace-wide clippy enforcement**
|
||||
|
||||
**Goal:** Document the design and encode the rules as compile-time enforcement applied to *all* code including tests.
|
||||
|
||||
**Requirements:** R10
|
||||
|
||||
**Dependencies:** Units 1-6.
|
||||
|
||||
**Files:**
|
||||
- Create: `docs-internal/server-secrets-strategy.md`.
|
||||
- Modify: `clippy.toml` — add `std::env::set_var` and `std::env::remove_var` to `disallowed-methods` with reason text pointing at the strategy doc. The ban is workspace-wide and applies to tests as well as production code.
|
||||
- Modify: `lib/crates/fabro-telemetry/src/spawn.rs:73-76` — add `#[expect(clippy::disallowed_methods, reason = "post-fork pre-execvp env mutation; safe because grandchild is single-threaded and about to be replaced via exec")]`.
|
||||
- Modify: any other production caller surfaced during implementation (the count is small per Unit 1's grep) — same `#[expect]` pattern with documented reason.
|
||||
- Modify: `CLAUDE.md` (and `AGENTS.md` if separate) — add "Strategy docs" entry pointing at the new doc.
|
||||
|
||||
**Approach:**
|
||||
|
||||
Strategy doc covers:
|
||||
- **`ServerSecrets` is the resolved-secrets API.** Sources are process env (12-factor) and `<storage>/server.env` (install/local convenience). Snapshotted at boot via `EnvSource` trait that materializes immediately into owned `HashMap`. Env wins on conflict.
|
||||
- **The five active server-level secrets** and their consumers (table from this plan). `FABRO_JWT_*` is removed (Unit 6); SESSION_SECRET is the sole auth master via HKDF.
|
||||
- **Provisioning paths:** CLI install, web install (shared orchestration in `fabro-install`), or platform env. Server start does not auto-generate.
|
||||
- **Tests must not mutate process env.** Enforced workspace-wide by clippy. Tests inject via construction-time `EnvSource` stubs (e.g. `StubEnv`) for in-process resolution, or via explicit child-process `Command::env` for subprocess simulation.
|
||||
- **Worker and render-graph env:** `env_clear` + strict fail-closed allowlist. Daemon child inherits parent env (12-factor pattern). New worker env entries require demonstrated need + intentional addition.
|
||||
- **Install while running:** allowed only through the shared install orchestration which owns restart/handoff. Manual `server.env` edits still require restart discipline.
|
||||
- **Rotation:** restart required. Live rotation intentionally not supported. Compliance-driven N+1 rotation (overlap windows) is a known limitation tracked as follow-up.
|
||||
- **Out of scope (with reasons):** Vault + `ProviderCredentials`, the legacy vault-or-process-env helper for run-level credentials (different track at the time), `{{ env.FOO }}` config interpolation, workflow-stage env (Sandbox's job), `validate_api_key` `set_var` smell, Tailscale spawns, `bun --watch-web`.
|
||||
- **Adding a new server-level secret:** (1) provision via the install orchestration or platform env; (2) consume via `state.server_secret(...)`; (3) do not touch env in any other layer; (4) decide if it joins the startup-critical set (most don't).
|
||||
- **Adding a new worker env var:** add to the worker list in `spawn_env.rs` with a one-line reason and a failing-without test that proves need.
|
||||
|
||||
**Verification:**
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` passes.
|
||||
- Adding a new `std::env::set_var(...)` in any production OR test file produces a clippy denial that names the strategy doc.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** all active server-level secrets (the five remaining after Unit 6) converge through `state.server_secret(name)` after Unit 1, which returns from the env+file snapshot. `resolve_auth_mode_with_lookup` migrates in the same unit. Legacy `FABRO_JWT_*` is removed across install, diagnostics, and docs (Unit 6).
|
||||
- **Error propagation:** daemon preflight (`validate_startup`) and foreground startup (`resolve_startup`, called from `serve_command`) both delegate to the same shared validation logic introduced in Unit 4 — the public preflight wrapper is literally `resolve_startup(...).map(|_| ())`, so error messages and accept/reject decisions are identical by construction. Unit 1 provides only the snapshot machinery (`ServerSecrets` + `EnvSource`) that Unit 4's validation consumes. Object-store credential failures still surface from the AWS SDK / object_store crate (unchanged — daemon inherits AWS env).
|
||||
- **State lifecycle:** `ServerSecrets` snapshot built once at boot from env+file; both immutable for process lifetime. Rotating any in-scope secret requires restart. Install flows MAY update `server.env` while a server is running when they own restart/handoff via the shared install orchestration (Unit 5).
|
||||
- **Subprocess env:** workers and render-graph processes inherit only an explicit fail-closed allowlist. Daemon child inherits parent env — that's how 12-factor SESSION_SECRET reaches the daemon.
|
||||
- **API surface:** no public API change. `state.server_secret(...)` signature unchanged. `ServerSecrets::with_env_lookup` removed; replaced by `load(path, &dyn EnvSource)`. `/install/finish` API contract unchanged (no `restart_required` flag, no new fields).
|
||||
- **Unchanged invariants at the time:** `ProviderCredentials`, Vault REST API, the legacy vault-or-process-env helper for run-level credentials, `{{ env.FOO }}` interpolation, workflow stages (configured by `Sandbox`) all behaved exactly as before. Later secrets-rationalization work moved optional server integration secrets to vault-only lookup.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| Snapshot semantics surprise: operator changes env after boot, expects the running server to pick it up | Documented behavior. Live rotation is intentionally not supported; restart required. Strategy doc is explicit. |
|
||||
| Worker list is missing something a workflow stage runner inside Sandbox needs | Worker process itself only does HTTP callbacks — Sandbox handles stage env. Real workflow integration test in Unit 3 verification catches false negatives. |
|
||||
| Existing deployments without `server.env` AND without env-set secrets fail to start | Intended behavior; error message names both sources. Per repo policy, accept the breakage. |
|
||||
| Test migration: replacing `std::env::set_var` calls with `EnvSource` stubs touches many files | `EnvSource` + `StubEnv` pattern is mechanical; one helper per pattern. Unit 7's clippy enforcement catches stragglers at compile time so nothing slips through. |
|
||||
| Shared install orchestration regression breaks CLI/web parity | Parity tests in Unit 5 explicitly assert identical persistence behavior across CLI and web paths. Both flows route through the same `fabro-install` entry points. |
|
||||
| Automatic `FABRO_JWT_*` removal surprises operators who believed those keys were authoritative | Strategy doc names the cleanup explicitly. Keys haven't participated in runtime auth since `2026-04-19-003`; cleanup is overdue, not novel. Operators upgrading run install once and the cleanup happens silently. |
|
||||
| Rust 2024 edition migration is a separate effort | Removing `set_var` is a prerequisite; this work doesn't gate on the edition migration. Workspace-wide clippy enforcement (Unit 7) prevents reintroduction including in tests. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- **Operator-facing change:** `fabro server start` against an empty env AND uninstalled storage now fails fast naming both sources. Document in install/quickstart.
|
||||
- **12-factor PaaS deployments (Railway, Heroku, Fly):** unchanged ergonomics — set secrets in platform env, run `fabro server start`. Works without `fabro install` having run on the platform.
|
||||
- **Container/k8s deployments:** if secrets are mounted as files (e.g. via projected volume into `<storage>/server.env`) or set as env vars (k8s Secret → env), both work.
|
||||
- **Cloud object-store (S3 / IRSA / ECS):** unchanged — daemon inherits AWS env from parent, object-store layer reads ambient credentials.
|
||||
- **Install while server running:** install flows may update `server.env` on a running server only when they coordinate restart/handoff via the shared install orchestration (CLI install or web install via `/install/finish`). Manual edits to `server.env` outside the orchestration still require restart discipline.
|
||||
- **`FABRO_JWT_*` removal:** `FABRO_JWT_PRIVATE_KEY` / `FABRO_JWT_PUBLIC_KEY` are removed from the runtime auth model; SESSION_SECRET is the sole auth master for cookie and JWT derivation. Existing legacy entries are cleaned up automatically on subsequent install flows.
|
||||
- **Rotation:** edit env (and restart) or edit `server.env` (and restart). Live rotation not supported.
|
||||
- **Logging:** the fail-fast error appears in operator log aggregators. Pair human-readable message with a structured error code (e.g., `error_code=missing_session_secret`) so log searches match without depending on the exact string.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- Related plans:
|
||||
- `docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md` — architectural anchor
|
||||
- `docs/plans/2026-04-19-003-feat-cli-auth-login-plan.md` — SESSION_SECRET as HKDF master
|
||||
- `docs/plans/2026-04-18-001-feat-webhook-strategy-plan.md` — webhook secret precedent
|
||||
- `docs/plans/2026-04-02-001-feat-server-daemon-management-plan.md` — origin of daemon/foreground split
|
||||
- Related commits:
|
||||
- `7cb6c65d5` — "Remove dev-token minting from server start" (precedent for Unit 4)
|
||||
- Strategy doc precedent: `docs-internal/logging-strategy.md`, `docs-internal/events-strategy.md`
|
||||
|
|
@ -1,570 +0,0 @@
|
|||
---
|
||||
title: "refactor: Server-issued per-run JWT for worker subprocess auth"
|
||||
type: refactor
|
||||
status: completed
|
||||
date: 2026-04-22
|
||||
deepened: 2026-04-22
|
||||
---
|
||||
|
||||
# refactor: Server-issued per-run JWT for worker subprocess auth
|
||||
|
||||
## Overview
|
||||
|
||||
Server mints one per-run JWT (HS256, 72h, claims include `run_id`) at every worker subprocess spawn, injects it into the worker env as `FABRO_WORKER_TOKEN`, and worker-touched run-scoped routes accept it. Worker stops reading `~/.fabro/auth.json`. The artifact-upload-token mechanism is deleted entirely (greenfield — no external consumers, no shim required). End-user auth (dev-token / github) is now strictly orthogonal to worker auth.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Workers POST back to the server (events, state, blobs, stage artifacts). Today the worker only authenticates because it inherits the CLI user's OAuth session from `~/.fabro/auth.json` (`fabro-cli/src/server_client.rs:312` → `AuthStore::default()` at `fabro-client/src/auth_store.rs:107`). Side effects:
|
||||
|
||||
- (a) worker authenticates *as the user* — events emitted by the worker get user identity, not "system";
|
||||
- (b) any deployment where the worker doesn't share a home dir with an authenticated CLI user (containerized server, `fabro` system user, remote worker, multi-tenant) silently fails;
|
||||
- (c) worker auth is implicitly coupled to end-user auth strategy when conceptually independent.
|
||||
|
||||
GitHub-only install (`auth.methods = ["github"]`) writes no `FABRO_DEV_TOKEN` and `worker_command` (`server.rs:3740-3750`) injects nothing — the worker has no documented credential at all. Only the home-dir steal makes it work.
|
||||
|
||||
The artifact-upload-token mechanism (`server.rs:752`, `server.rs:846`) already proves the right pattern for one route. Generalize it to every worker-touched route.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Worker subprocess authenticates to server with a credential the server explicitly issued, not one stolen from the user's home directory.
|
||||
- R2. Credential is per-run (claim `run_id` must match path `run_id`); cross-run reuse rejected.
|
||||
- R3. Credential survives server restart up to its natural 72h expiry (no operational events shortening the ceiling).
|
||||
- R4. Both `start` and `resume` spawn paths re-mint a fresh 72h credential.
|
||||
- R5. Worker auth works in any deployment topology, including GitHub-only installs with no `~/.fabro/auth.json` on the worker host.
|
||||
- R6. Worker-emitted events stamped as a system principal (`system:worker`); originator user identity remains discoverable on the run record.
|
||||
- R7. Worker-touched run-scoped routes still accept end-user JWTs for non-worker callers (CLI, web UI) — fall-through, not replacement.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- **Greenfield context:** no shipped deployments; no need to preserve in-flight workers across the change. Atomic swap. No backwards-compat shim. No deprecation cycle.
|
||||
- Out: refresh tokens for workers (decided: hard 72h ceiling per spawn, fresh mint on resume).
|
||||
- Out: in-memory or persisted revocation list. Per-run binding + 72h `exp` is the entire blast-radius bound.
|
||||
- Out: multi-host / remote worker spawning (this plan makes it *possible*, doesn't deliver it).
|
||||
- Out: changes to end-user auth methods (`ServerAuthMethod::DevToken | Github`).
|
||||
- Out: any new `RunAuthMethod` variant — worker token bypasses `AuthenticatedSubject` entirely.
|
||||
- Out: extending `RunSummary` with provenance — originator already on `RunSpec.provenance.subject` and that's enough.
|
||||
- Out: SSE attach routes (`/runs/{id}/attach`, `/attach`). Worker is a producer, not a consumer; never calls them. Stay user-JWT-only.
|
||||
- Out: lifecycle/admin/user-action routes (`/runs/{id}/cancel`, `/pause`, `/unpause`, `/archive`, `/unarchive`, `DELETE /runs/{id}`, `submit_answer`, `start_run`, `create_run`, list endpoints). Worker token explicitly rejected on these — they remain user-JWT-only.
|
||||
- Out: any `Display` impl on `Credential::Worker` payload. Plan keeps redacted `Debug` only; do not add `Display`.
|
||||
- Out: distinct exit codes for auth failure. Worker bails clearly at startup if env is missing; server 401/403 mid-run flows through normal client error handling.
|
||||
- Out: blanket env scrubbing of trusted internal subprocesses (`gh auth token`, MCP servers, git). These may legitimately need credentials. Scrubbing scope: workflow/sandbox stage-execution chokepoint (`LocalSandbox::execute`) AND host-mode hooks (defense-in-depth; shell commands have no business reading the worker token).
|
||||
|
||||
## Threat Model
|
||||
|
||||
State the assumptions explicitly so reviewers and operators can challenge them.
|
||||
|
||||
- **Trust boundary:** the server process and any worker subprocess running under the same OS user are mutually trusted. Same-UID attackers (or a workflow stage that compromises the worker process) can read `FABRO_WORKER_TOKEN` from `/proc/<pid>/environ` on Linux. Multi-tenant deployments must isolate per-tenant via separate UIDs / containers / namespaces. Cross-run isolation between same-UID workers is NOT a property of this design.
|
||||
- **`SESSION_SECRET` is the master key.** It signs both user JWTs and worker JWTs (via distinct HKDF context labels). Any leak vector — backup including `server.env`, env dump in logs, ECS task definition exposure, accidental commit, breadcrumb capture — gives the attacker the ability to mint tokens of either kind for any user / any run. Operational guidance: store `SESSION_SECRET` in a secrets manager, exclude from logs/Sentry, document a rotation procedure (rotation invalidates ALL outstanding worker tokens AND ALL user sessions — accept as the cost of compromise response).
|
||||
- **Worker token compromise:** an attacker who exfiltrates a single worker token gains read/write on that one run's events/blobs/state for up to 72h. Run-id binding limits cross-run damage. There is no in-product revocation; rotating `SESSION_SECRET` is the only mechanism to invalidate outstanding worker tokens.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-server/src/server.rs:287-289, 752-812, 813-854` — artifact-upload-token: claims struct, key generation (`OsRng` per boot), mint, "service token first, else user JWT" check (`authorize_artifact_upload`). Generalize the shape to all worker-touched routes; replace this mechanism wholesale.
|
||||
- `lib/crates/fabro-server/src/server.rs:3701-3755` — `worker_command`: single spawn site for both `start` and `resume`. Already passes `--artifact-upload-token` via argv (deleted in Unit 3) and calls `apply_worker_env` at `server.rs:3739`. Add `cmd.env("FABRO_WORKER_TOKEN", token)`.
|
||||
- `lib/crates/fabro-server/src/server.rs:4666` — `execute_run_subprocess` calls `worker_command` once per spawn; `RunExecutionMode` flows from `start_run` (`server.rs:4181`) and `create_run` (`server.rs:4011`). Single mint site covers both modes.
|
||||
- `lib/crates/fabro-server/src/spawn_env.rs:18` — existing `apply_worker_env` does `env_clear` + 8-name allowlist (PATH, HOME, TMPDIR, USER, RUST_LOG, RUST_BACKTRACE, FABRO_HOME, FABRO_STORAGE_ROOT). `SESSION_SECRET`, `FABRO_JWT_*`, `GITHUB_APP_*` are all already excluded. Existing `worker_allowlist_is_fail_closed` test (`spawn_env.rs:64-99`) asserts `SESSION_SECRET` is stripped.
|
||||
- `lib/crates/fabro-server/src/auth/keys.rs:41` — existing HKDF helper `derive_jwt_key` for the user-JWT key. Mirror for worker JWT with distinct context label `b"fabro-worker-jwt-v1"` so worker keys survive server restarts (R3).
|
||||
- `lib/crates/fabro-cli/src/commands/run/runner.rs:55-127` — `__run-worker` entry, `HttpRunStore`, `HttpArtifactUploader`. Only seven server endpoints touched (catalogued below).
|
||||
- `lib/crates/fabro-cli/src/server_client.rs:51-58, 133, 312` — `connect_server_target_direct` → `connect_target_api_client_bundle` → `resolve_target_credential` → `AuthStore::default()`. Sole worker caller is `runner.rs:67`. Replaced for the worker only via a sibling constructor.
|
||||
- `lib/crates/fabro-client/src/credential.rs:6-30` — `Credential` enum. Add `Worker(String)` variant; `bearer_token()` returns the string.
|
||||
- `lib/crates/fabro-types/src/run_event/mod.rs:29-81` — `ActorRef`/`ActorKind { User | Agent | System }`. No new variant needed — stamp worker events with `ActorKind::System`.
|
||||
- `lib/crates/fabro-types/src/run.rs:34-49` — `RunProvenance`/`RunSubjectProvenance` already on `RunSpec`. Originator preserved at run-creation time; no schema change.
|
||||
- `lib/crates/fabro-sandbox/src/local.rs:43-66, 221` — `LocalSandbox::execute` does `env_clear` + `should_filter_env_var` heuristic for stage commands. The `_token` suffix filter incidentally catches `FABRO_WORKER_TOKEN`; make it explicit (denylist entry).
|
||||
|
||||
### Worker → server endpoint surface
|
||||
|
||||
These are the **only** routes that gain worker-token acceptance. Lifecycle/admin/list endpoints stay user-JWT-only (see Scope Boundaries).
|
||||
|
||||
| Worker call | HTTP | Path | Server handler | Auth today |
|
||||
|---|---|---|---|---|
|
||||
| `client.get_run_state` | GET | `/runs/{id}/state` | `get_run_state` (`server.rs:5076`) | `AuthenticatedService` |
|
||||
| `client.list_run_events` | GET | `/runs/{id}/events` | `list_run_events` (`server.rs:5146`) | `AuthenticatedService` |
|
||||
| `client.append_run_event` | POST | `/runs/{id}/events` | `append_run_event` (`server.rs:5096`) | `AuthenticatedService` |
|
||||
| `client.write_run_blob` | POST | `/runs/{id}/blobs` | `write_run_blob` (`server.rs:5352`) | `AuthenticatedService` |
|
||||
| `client.read_run_blob` | GET | `/runs/{id}/blobs/{blobId}` | `read_run_blob` (`server.rs:5379`) | `AuthenticatedService` |
|
||||
| `client.upload_stage_artifact_file` | POST | `/runs/{id}/stages/{stageId}/artifacts` (octet-stream) | `put_stage_artifact` (`server.rs:5838`) | `authorize_artifact_upload` |
|
||||
| `client.upload_stage_artifact_batch` | POST | same path (multipart) | same handler | same |
|
||||
|
||||
### Coordination with concurrent plans
|
||||
|
||||
- `docs/plans/2026-04-22-003-refactor-lock-down-server-secrets-plan.md` partially landed: `apply_worker_env` exists at `lib/crates/fabro-server/src/spawn_env.rs:18` and is invoked from `worker_command` at `server.rs:3739`. The allowlist excludes server-only secrets, structurally preventing the worker from inheriting `SESSION_SECRET`. This plan adds the `FABRO_WORKER_TOKEN` re-injection alongside the existing `FABRO_DEV_TOKEN` re-injection (and ultimately replaces the latter).
|
||||
- `docs/plans/2026-04-19-003-feat-cli-auth-login-plan.md` Unit 8 created `lib/crates/fabro-server/src/auth/jwt.rs` (`Claims`, `issue`, `verify`, `JwtError`) and `auth/keys.rs::derive_jwt_key`. Reuse the HKDF derivation pattern (distinct context label) and the `jsonwebtoken` primitives directly — do not route worker-token claims through user-`JwtSubject`.
|
||||
- `docs/plans/2026-04-20-001-fix-cli-server-same-host-assumptions-plan.md` deliberately closed the "trust local files because same host" pattern. This plan preserves that closure — no new same-host exceptions; the worker uses an explicitly-passed token.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
- No `docs/solutions/` directory exists. Prior decisions live in `docs/plans/`.
|
||||
- Artifact-upload-token TTL precedent is 24h. New worker-token TTL is 72h — justified because worker tokens must survive long human-in-the-loop pauses with no in-process refresh.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
| Decision | Rationale |
|
||||
|---|---|
|
||||
| Replace artifact-upload-token entirely; one JWT per run covers all worker-touched run-scoped routes | Two parallel per-run JWTs is bookkeeping. Run-id binding gives the same blast-radius constraint without a separate scope. Greenfield → atomic delete, no shim. |
|
||||
| Pass JWT to worker via env var `FABRO_WORKER_TOKEN`. **Env-only — never argv.** | Symmetric with existing `FABRO_DEV_TOKEN` re-injection model. Plays naturally with `env_clear` + explicit re-injection in `apply_worker_env`. Avoids token strings in `ps` output. |
|
||||
| HS256, key derived from `SESSION_SECRET` via HKDF (context `b"fabro-worker-jwt-v1"`) | Workers must survive server restarts up to natural 72h expiry (R3). `OsRng`-per-boot defeats the long TTL. Distinct context label keeps it isolated from the user-JWT key. Operator rotation of `SESSION_SECRET` invalidates outstanding worker tokens — accepted (and is the only revocation mechanism). |
|
||||
| 72h TTL, no refresh, no revocation list | Long-paused runs need a generous outer ceiling. Resume re-mints. Workers running > 72h continuously fail loudly — acceptable outer bound. Adding revocation requires persistent state and creates restart-window contradictions; not worth the complexity for the current threat model. |
|
||||
| Per-run `run_id` claim, path-vs-claim check | Mirrors `maybe_authorize_artifact_upload_token`. Cross-run reuse → 403. |
|
||||
| Add `Credential::Worker(String)` variant (not reuse `DevToken`) | Debug printing stays accurate. No `Display` impl — compile-time hardening prevents accidental `format!`-leaks. |
|
||||
| New worker-only client constructor `connect_server_target_with_bearer(target, token)`, bypasses `AuthStore`/`OAuthSession` entirely | Worker should never read user OAuth. Surgical to fix at the worker callsite (one caller, `runner.rs:67`) rather than gating `resolve_target_credential` with a "are you a worker" flag. |
|
||||
| Stamp `system:worker` actor in a worker-side sink wrapper inside `RunEventSink::fanout`, NOT in `to_run_event_at` | `to_run_event_at` and `stored_event_fields` are shared with the server (server flushes lifecycle events through `workflow_event::to_run_event` at `server.rs:6702`). Default-filling there mis-stamps server-emitted events. The wrapper is worker-local. |
|
||||
| Route API is a set of typed `FromRequestParts` extractors (`AuthorizeRunScoped`, `AuthorizeRunBlob`, `AuthorizeStageArtifact`), NOT a bare helper function | Composes with existing `Json<...>` / `Bytes` body extractors (a `Parts`-taking helper would force full-`Request` extraction everywhere and break body handling). Each extractor returns the already-parsed run-id (and secondary path params) so handlers drop their own `Path<String>` + `parse_*` dance. Replaces `_auth: AuthenticatedService` and the existing `authorize_artifact_upload` inline call. One fall-through behavior (worker token first, else user JWT) shared across all three. `authorize_worker_token` remains a `pub(crate)` internal helper used by the extractors. |
|
||||
| Env scrubbing at two sites: `LocalSandbox::execute` (stage execution) and host-mode hooks | Stage commands run user-supplied code → MUST NOT see `FABRO_WORKER_TOKEN`. `LocalSandbox::execute` filters both inherited env AND the explicit `env_vars` extras path (today's code appends extras AFTER the filter — defense-in-depth gap this plan closes). Host-mode hooks get a targeted `env_remove("FABRO_WORKER_TOKEN")` (shell commands have no business reading the worker token, even when operator-configured). Trusted internal subprocesses (`gh auth token`, MCP server stdio, git) are NOT scrubbed — they may legitimately need credentials, and they aren't user-attack surfaces. |
|
||||
| `authorize_worker_token` lives in `worker_token.rs` and takes `&WorkerTokenKeys` directly (NOT `&AppState`) | Sibling modules can't access private `AppState` fields. Mirroring `maybe_authorize_artifact_upload_token`'s signature (which already takes the typed keys) keeps the helper testable without a fixture `AppState`. The thin `authorize_run_scoped(parts, state, run_id)` adapter lives where it can see `AppState` and pulls `&state.worker_tokens` into the call. |
|
||||
| Missing/invalid `FABRO_WORKER_TOKEN` → worker errors at startup with a clear message; mid-run 401/403 flow through normal client error handling | No special exit codes. Distinct operational telemetry isn't worth the machinery for the current scale. |
|
||||
|
||||
### Worker-token vs artifact-upload-token (delta)
|
||||
|
||||
| Property | Artifact-upload-token (today) | Worker-token (new) |
|
||||
|---|---|---|
|
||||
| Coverage | One route (`/runs/{id}/stages/{stageId}/artifacts`) | All 7 worker-touched run-scoped routes |
|
||||
| TTL | 24h | 72h |
|
||||
| Signing key | `OsRng` at server boot, in-memory only | HKDF from `SESSION_SECRET`, context `b"fabro-worker-jwt-v1"` |
|
||||
| Survives server restart | No | Yes (up to natural expiry) |
|
||||
| Issuer string | `"fabro-server-artifact-upload"` | `"fabro-server-worker"` |
|
||||
| Scope claim | `"stage_artifacts:upload"` | `"run:worker"` |
|
||||
| Passed to worker | `--artifact-upload-token` argv | `FABRO_WORKER_TOKEN` env var |
|
||||
| Worker uses it as | Per-call method arg on the client | Client's bearer for every server call |
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- TTL: 72h. Refresh: none in-process; fresh mint at every spawn (start AND resume).
|
||||
- Key derivation: HKDF from `SESSION_SECRET` with context `b"fabro-worker-jwt-v1"`.
|
||||
- Replace artifact-upload-token entirely vs. keep both: replace.
|
||||
- Token transport: env var (`FABRO_WORKER_TOKEN`), not argv.
|
||||
- Revocation: none. Per-run binding + 72h `exp` is the entire blast-radius bound.
|
||||
- New `RunAuthMethod::Worker` variant: no — worker token bypasses `AuthenticatedSubject` entirely.
|
||||
- Stamp worker events server-side vs. worker-side: worker-side, in a dedicated sink wrapper inside the worker's `RunEventSink::fanout` chain.
|
||||
- Multi-token-per-run on rapid pause/resume: accept and document. Each prior token remains valid up to 72h `exp`. Bounded by run-id; out-of-scope to fix here.
|
||||
- Env scrubbing scope: workflow stage-execution chokepoint at `LocalSandbox::execute` (inherited env + explicit `env_vars` extras) AND host-mode hooks at `fabro-hooks/src/executor.rs`. Trusted internal subprocesses (`gh auth token`, MCP stdio, git) are not scrubbed.
|
||||
- Auth-failure exit codes: no — generic error handling.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- Exact module name for new server-side worker-token machinery — likely `fabro-server/src/worker_token.rs`.
|
||||
- Mechanism for the compile-time "no `Display` for `Credential::Worker`" guard — `static_assertions::assert_not_impl_any!` is the natural fit; choose at implementation time.
|
||||
- Whether to enforce "worker module never imports `AuthStore`" structurally (clippy `disallowed_types` on the `commands::run` module). Nice-to-have; defer.
|
||||
- Core dump disable (`setrlimit(RLIMIT_CORE, 0)`) on the worker process. Same-UID attacker assumption holds today; defer.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant Op as Operator
|
||||
participant Srv as fabro-server
|
||||
participant W as worker subprocess
|
||||
participant Child as sandbox stage child
|
||||
|
||||
Op->>Srv: start (SESSION_SECRET in env)
|
||||
Note over Srv: HKDF-derive WorkerTokenKeys<br/>context "fabro-worker-jwt-v1"
|
||||
Srv->>Srv: spawn scheduled (start or resume)
|
||||
Note over Srv: issue_worker_token(run_id)<br/>HS256 + claims{run_id, scope, 72h}
|
||||
Srv->>W: spawn with apply_worker_env (env_clear + allowlist)<br/>+ FABRO_WORKER_TOKEN injected
|
||||
W->>W: read FABRO_WORKER_TOKEN from env<br/>build Client with Credential::Worker(token)<br/>(no AuthStore, no OAuthSession)
|
||||
W->>Srv: POST /runs/{id}/events (Bearer ...)
|
||||
Srv->>Srv: authorize_run_scoped:<br/>1) try worker token (run_id match + exp check)<br/>2) else fall through to user-JWT extractor
|
||||
Srv-->>W: 200 OK
|
||||
W->>Child: spawn stage command via LocalSandbox::execute<br/>(env_clear + safelist; FABRO_WORKER_TOKEN excluded)
|
||||
Child-->>W: result (no token in env)
|
||||
Note over W,Srv: ... run completes ...
|
||||
Note over Srv: server restart: HKDF re-derives same key,<br/>outstanding tokens still verify (up to natural exp)
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Worker JWT primitives (claims, keys, mint)**
|
||||
|
||||
**Goal:** Server can mint a per-run worker JWT signed with a key derived from `SESSION_SECRET`. No callers yet.
|
||||
|
||||
**Requirements:** R2, R3.
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-server/src/worker_token.rs`
|
||||
- Modify: `lib/crates/fabro-server/src/auth/keys.rs` (add `derive_worker_jwt_key`)
|
||||
- Modify: `lib/crates/fabro-server/src/lib.rs` (module declaration)
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` (`AppState` field for `WorkerTokenKeys`, construction in `build_app_state`)
|
||||
- Test: `lib/crates/fabro-server/src/worker_token.rs` (unit tests inline)
|
||||
|
||||
**Approach:**
|
||||
- Constants: `WORKER_TOKEN_ISSUER = "fabro-server-worker"`, `WORKER_TOKEN_SCOPE = "run:worker"`, `WORKER_TOKEN_TTL_SECS = 72 * 60 * 60`.
|
||||
- `WorkerTokenClaims { iss, iat, exp, run_id, scope, jti }` — `jti` (random 128-bit hex) enables audit correlation in logs without exposing the token.
|
||||
- `WorkerTokenKeys { encoding, decoding, validation }` — built from a 32-byte HKDF output keyed by `SESSION_SECRET`, context `b"fabro-worker-jwt-v1"`.
|
||||
- `pub fn issue_worker_token(keys: &WorkerTokenKeys, run_id: &RunId) -> Result<String, ApiError>` — `jsonwebtoken::encode` with HS256.
|
||||
- `pub(crate) fn derive_worker_jwt_key(secret: &[u8]) -> Result<[u8; 32], KeyDeriveError>` in `auth/keys.rs` — same HKDF construction as `derive_jwt_key`, distinct `info` parameter (`b"fabro-worker-jwt-v1"`). Mirrors the existing helper's error shape so the `KeyDeriveError` cases (empty / too-short secret) propagate identically.
|
||||
- **App-state construction wires it explicitly**: `build_app_state` resolves `SESSION_SECRET` (already required for the user-JWT key today), calls `derive_worker_jwt_key`, and bails with a clear startup error if it fails. Failure modes: missing `SESSION_SECRET`, secret too short. Add `worker_tokens: WorkerTokenKeys` field on `AppState` next to `artifact_upload_tokens` (the artifact field is deleted in Unit 3).
|
||||
- **Test app-state builders** (`worker_command_test_state` at `server.rs:7868` and any other test fixture that constructs `AppState`) must supply a fixture `SESSION_SECRET`. The existing test secret used by user-JWT tests can be reused.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `server.rs:287-289, 319-326, 752-773, 798-812` (artifact-upload-token, end-to-end).
|
||||
- `auth/keys.rs:41` (`derive_jwt_key` HKDF construction).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `issue_worker_token` produces a token; `jsonwebtoken::decode` with the same `WorkerTokenKeys` returns the expected `WorkerTokenClaims` (iss, scope, run_id, jti).
|
||||
- Edge case: token issued with `WorkerTokenKeys` derived from secret S verifies under a *fresh* `WorkerTokenKeys` derived from the same S — proves restart survival (R3).
|
||||
- Edge case: token issued under secret S1 fails to verify under keys derived from secret S2 (rotation invalidation).
|
||||
- Edge case: derivation context label `b"fabro-worker-jwt-v1"` produces a key materially different from `derive_jwt_key(secret)` (no accidental cross-acceptance with user JWTs).
|
||||
- Error path: `derive_worker_jwt_key(b"")` returns `Err(KeyDeriveError::Empty)`. Mirrors existing `derive_jwt_key` error shape.
|
||||
- Error path: `derive_worker_jwt_key(short_secret)` returns `Err(KeyDeriveError::TooShort { .. })` for secrets below the minimum length.
|
||||
- Startup: `build_app_state` with no `SESSION_SECRET` in env returns a startup error matching the existing user-JWT-key startup-error wording.
|
||||
|
||||
**Verification:**
|
||||
- All worker-token unit tests pass.
|
||||
- `cargo build -p fabro-server` succeeds.
|
||||
- No production callers of new symbols yet — Unit 1 is purely additive infrastructure.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2: Server `AuthorizeRunScoped` extractor family + client `Credential::Worker` variant**
|
||||
|
||||
**Goal:** Three typed `FromRequestParts` extractors (`AuthorizeRunScoped`, `AuthorizeRunBlob`, `AuthorizeStageArtifact`) accept worker token (run-id-bound) OR fall back to user JWT. Client crate gains a typed worker credential with no `Display` and redacted `Debug`.
|
||||
|
||||
**Requirements:** R2, R7.
|
||||
|
||||
**Dependencies:** Unit 1.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/worker_token.rs` (add `pub(crate) fn authorize_worker_token` internal helper; add the three public extractors `AuthorizeRunScoped`, `AuthorizeRunBlob`, `AuthorizeStageArtifact` with `FromRequestParts` impls)
|
||||
- Modify: `lib/crates/fabro-server/src/lib.rs` (re-export the three extractors if needed by handler modules)
|
||||
- Modify: `lib/crates/fabro-client/src/credential.rs` (add `Worker(String)` variant — no `Display`)
|
||||
- Test: `lib/crates/fabro-server/src/worker_token.rs` (authorize helper tests inline)
|
||||
- Test: `lib/crates/fabro-client/src/credential.rs` (Debug + bearer_token tests inline)
|
||||
|
||||
**Approach:**
|
||||
- **Module placement & visibility**: `worker_token.rs` is a sibling module to `server.rs`; sibling modules cannot read private `AppState` fields. Two options: (a) keep the helper inside `impl AppState` in `server.rs` like `issue_artifact_upload_token` does today, or (b) put the helper in `worker_token.rs` and pass `&WorkerTokenKeys` directly (NOT `&AppState`). **Choose (b)** — keeps `AppState` internals private, makes the helper trivially testable without an `AppState` fixture, mirrors how `maybe_authorize_artifact_upload_token` already takes `&ArtifactUploadTokenKeys` not `&AppState`. The thin glue in `authorize_run_scoped` then takes `&AppState` and pulls `&state.worker_tokens` into the call.
|
||||
- `pub(crate) fn authorize_worker_token(parts: &Parts, run_id: &RunId, keys: &WorkerTokenKeys) -> Result<bool, ApiError>` — mirror `maybe_authorize_artifact_upload_token` (`server.rs:813-844`). Verification-first rule (no unverified claim peeking — `jsonwebtoken::decode` only returns claims after signature + expiry validation):
|
||||
- Bearer absent → `Ok(false)` silently.
|
||||
- `jsonwebtoken::decode` with `WorkerTokenKeys` returns `Err(_)` (any reason — bad signature, expired, malformed, alg mismatch) → `Ok(false)` silently. Could be a user JWT in fall-through, an expired worker token, or anything else; we don't know without verifying, and we don't peek at unverified payload bytes.
|
||||
- `decode` returns `Ok(claims)` AND `claims.scope != WORKER_TOKEN_SCOPE` → `Err(ApiError::forbidden())` + `tracing::warn!`. A token signed by us with a wrong scope is a misuse.
|
||||
- `decode` returns `Ok(claims)` AND `claims.run_id != run_id` → `Err(ApiError::forbidden())` + `tracing::warn!`. Cross-run reuse.
|
||||
- `decode` returns `Ok(claims)` AND scope + run_id match → `Ok(true)` + `tracing::info!`.
|
||||
- **Extractor body (shared logic)**: each `FromRequestParts` impl runs its path-parse step, then calls a shared `pub(crate)` helper that mirrors `authorize_artifact_upload` (`server.rs:846-854`): try `authorize_worker_token(parts, run_id, &state.worker_tokens)?`; if `Ok(false)`, fall through to `authenticate_service_parts(parts)`. `worker_tokens` stays `pub(crate)` on `AppState` so the helper in the same crate can read it.
|
||||
- `Credential::Worker(String)` — `bearer_token() -> &str` returns the string; `Debug` prints `Credential::Worker(<redacted>)`. **Do NOT implement `Display` on the `Credential` enum.** Compile-time hardening: assert `Credential: !Display` (variant-level assertions don't exist in Rust — the trait impl lives on the type).
|
||||
- **Audit logging at authorize time** (driven entirely by the verified-only rule above — no log if `decode` itself fails):
|
||||
- On successful worker-token auth: `tracing::info!(target = "worker_auth", run_id = %run_id, jti = %claims.jti, "worker token accepted")`.
|
||||
- On `Ok(claims)` with scope or run_id mismatch: `tracing::warn!(target = "worker_auth", reason = ..., jti = %claims.jti, "worker token rejected")`.
|
||||
- On `Err(_)` from `decode` (no claims available): silent. The bearer might be a user JWT in fall-through, an expired worker token, or garbage — we can't tell without verifying, and we don't try.
|
||||
- Never log the token string itself — only `jti`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `server.rs:813-854` (artifact-upload-token authorize pattern).
|
||||
- `fabro-client/src/credential.rs:6-40` (existing `DevToken`/`OAuth` variants).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path (server, unit): valid worker token for path run_id → `AuthorizeRunScoped` extractor succeeds; handler receives the parsed `RunId`.
|
||||
- Error path (server): worker token with `claims.run_id != path.run_id` → 403 + `worker_auth` warn with `jti`.
|
||||
- Error path (server): worker token signed with worker key but wrong scope → 403 + `worker_auth` warn.
|
||||
- Error path (server): expired worker token → `decode` returns `Err` → silent fall-through → user-JWT extractor rejects → 401. No `worker_auth` log.
|
||||
- Error path (server): bad signature (e.g. token signed with different key) → `decode` returns `Err` → silent fall-through → 401. No `worker_auth` log.
|
||||
- Error path (server): `alg=none` JWT → `decode` returns `Err` (validation requires HS256) → silent fall-through → 401.
|
||||
- Integration (server): no `Authorization` header → falls through to user-JWT extractor → 401 (no implicit acceptance).
|
||||
- Integration (server): valid user JWT, no worker token → user-JWT path accepts (R7).
|
||||
- Audit (precision): successful worker-token auth emits `target = "worker_auth"` info span with `run_id` and `jti`. Decode-success-but-claims-mismatch emits `warn` with `reason` and `jti`. Decode failure (any reason) emits NO `worker_auth` log — verify by counting log events on a user-JWT request and on an expired worker token; both must produce zero `worker_auth` lines.
|
||||
- Happy path (client): `Credential::Worker(s).bearer_token()` returns `s`.
|
||||
- Edge case (client): `Debug` impl prints `Credential::Worker(<redacted>)` — token string never appears in debug output.
|
||||
- Compile-time guard (client): assert `Credential: !Display` at the type level (e.g. via `static_assertions::assert_not_impl_any!(Credential: std::fmt::Display)`). Variants are not types; the trait impl lives on the enum.
|
||||
|
||||
**Verification:**
|
||||
- All extractor + helper tests pass with both branches exercised.
|
||||
- `cargo nextest run -p fabro-server -p fabro-client` succeeds.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 3: Wire worker-touched routes through the `AuthorizeRunScoped` extractor family; replace artifact-upload-token at the spawn**
|
||||
|
||||
**Goal:** Each of the 7 worker-touched routes accepts the worker token. Server spawn injects `FABRO_WORKER_TOKEN` env var. Old artifact-upload-token machinery deleted atomically. Lifecycle/admin/SSE routes are NOT touched and continue to require user JWT.
|
||||
|
||||
**Requirements:** R1, R2, R4, R7.
|
||||
|
||||
**Dependencies:** Unit 1, Unit 2.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs`
|
||||
- `get_run_state` (5076), `list_run_events` (5146), `append_run_event` (5096), `write_run_blob` (5352): replace `_auth: AuthenticatedService, Path(id): Path<String>` with `AuthorizeRunScoped(id): AuthorizeRunScoped`. Body extractors stay unchanged.
|
||||
- `read_run_blob` (5379): replace `_auth: AuthenticatedService, Path((id, blob_id)): Path<(String, String)>` with `AuthorizeRunBlob(id, blob_id): AuthorizeRunBlob`.
|
||||
- `put_stage_artifact` (5838): replace `Path::<(String, String)>` + inline `authorize_artifact_upload(&parts, ...)` with `AuthorizeStageArtifact(id, stage_id): AuthorizeStageArtifact`. Keep `request: Request` for body extraction; continue to call `request.into_parts()` inside the handler for the header/body split.
|
||||
- `worker_command` (3701-3755): replace `state.issue_artifact_upload_token` → `state.issue_worker_token`. Drop the `--artifact-upload-token <jwt>` arg entirely. Set `cmd.env("FABRO_WORKER_TOKEN", token)` unconditionally (always, regardless of auth method). Also `cmd.env_remove("FABRO_WORKER_TOKEN")` before re-injection (defense against parent-env leakage). Delete the conditional `cmd.env("FABRO_DEV_TOKEN", token)` block (3740-3750) — `FABRO_WORKER_TOKEN` replaces it as the only authority-bearing re-injection.
|
||||
- **Lifecycle/admin/SSE routes left alone**: `cancel_run`, `pause_run`, `unpause_run`, `archive_run`, `unarchive_run`, `delete_run`, `submit_answer`, `start_run`, `create_run`, `attach_run_events` (`/runs/{id}/attach`), `attach_events` (`/attach`), and any list endpoint. Keep `_auth: AuthenticatedSubject` / `AuthenticatedService` directly. Add a one-line code comment at each of the 9 worker-rejecting handlers: `// Worker token intentionally not accepted; this is a user/admin action.`
|
||||
- Delete: `ARTIFACT_UPLOAD_TOKEN_*` constants (287-289), `ArtifactUploadClaims` (319-326), `ArtifactUploadTokenKeys` (313-317), `artifact_upload_token_keys` (798-812), `AppState::issue_artifact_upload_token` (752-773), `AppState::artifact_upload_tokens` field (565), `maybe_authorize_artifact_upload_token` (813-844), `authorize_artifact_upload` (846-854).
|
||||
- Test: existing tests in `lib/crates/fabro-server/src/server.rs` test module (rename / replace `worker_command_injects_dev_token_only_when_enabled` at 7836).
|
||||
|
||||
**Approach:**
|
||||
- The shape change is NOT trivially mechanical for JSON/body handlers like `append_run_event` (`Json<...>` body) or `write_run_blob` (`Bytes` body). Switching them to `Request::into_parts()` would require manually re-parsing the body. Instead, introduce a custom `FromRequestParts` extractor that composes naturally with body extractors.
|
||||
- **Route API is the extractor, not the helper.** Route handlers should use the new extractor types as their route-facing auth contract. `authorize_worker_token` and the inner decode/fall-through logic remain `pub(crate)` helpers used only by the extractors.
|
||||
- **Three extractor variants** (one per path shape the worker actually uses) in `worker_token.rs`:
|
||||
- `AuthorizeRunScoped(pub RunId)` — for `/runs/{id}/...` with a single run-id path param. Used by: `get_run_state`, `list_run_events`, `append_run_event`, `write_run_blob`.
|
||||
- `AuthorizeRunBlob(pub RunId, pub RunBlobId)` — for `/runs/{id}/blobs/{blobId}`. Used by: `read_run_blob`.
|
||||
- `AuthorizeStageArtifact(pub RunId, pub StageId)` — for `/runs/{id}/stages/{stageId}/artifacts`. Used by: `put_stage_artifact` (and `list_stage_artifacts`, `get_stage_artifact` if they ever join the worker-touched set; not today).
|
||||
- Each `impl FromRequestParts` internally:
|
||||
- Extracts `Path::<(String, ...)>::from_request_parts` with the right tuple shape (1, 2, or 2 segments).
|
||||
- Parses each segment via the existing `parse_run_id_path`, `parse_run_blob_id_path`, `parse_stage_id_path` helpers.
|
||||
- Reads `AuthMode` from `parts.extensions` and `&AppState.worker_tokens` from axum state.
|
||||
- Calls `authorize_worker_token(parts, &run_id, &keys)?`; on `Ok(false)` falls through to `authenticate_service_parts(parts)`.
|
||||
- Returns the typed path params so handlers skip their own `Path<String>` + `parse_*` dance.
|
||||
- Handlers change:
|
||||
- `get_run_state`, `list_run_events`, `append_run_event`, `write_run_blob`: `_auth: AuthenticatedService, Path(id): Path<String>` → `AuthorizeRunScoped(id): AuthorizeRunScoped`. Body extractors (`Json<...>`, `Bytes`) stay intact.
|
||||
- `read_run_blob`: `_auth: AuthenticatedService, Path((id, blob_id)): Path<(String, String)>` → `AuthorizeRunBlob(id, blob_id): AuthorizeRunBlob`.
|
||||
- `put_stage_artifact`: currently takes `Request` + `Path::<(String, String)>`. Swap to `AuthorizeStageArtifact(id, stage_id): AuthorizeStageArtifact` + `request: Request` (body extraction stays manual via `request.into_parts()`).
|
||||
- Atomic swap, no transition period — cargo + tests catch any missed callsite.
|
||||
- **Pre-implementation audit:** grep all `client.*` and `api.*` callsites under `lib/crates/fabro-cli/src/commands/run/` (and any helpers it transitively uses) to confirm each resolves to one of the 7 endpoints in the table. If any newly-discovered handler exists, add a row and wire it through `AuthorizeRunScoped`.
|
||||
- **Structural rule:** `AuthorizeRunScoped` is used ONLY in handlers whose path contains `{id}` (`RunId`). Verify by grep: every usage must correspond to a `{id}` path segment.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `put_stage_artifact` handler (`server.rs:5838`) is the existing model: takes `parts: Parts`, calls `authorize_artifact_upload(&parts, &state, &id)?`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: each of the 5 newly-wired routes accepts a worker token whose `claims.run_id` matches the path `id` → expected response.
|
||||
- Error path: each route with worker token whose `claims.run_id` ≠ path `id` → 403.
|
||||
- Integration: each route with valid user JWT and no worker token → still works (R7 fall-through).
|
||||
- Replacement test for `worker_command_injects_dev_token_only_when_enabled`: rename to `worker_command_always_sets_worker_token_env`. Build `worker_command` for both `methods=["github"]` and `methods=["dev-token"]` settings; assert `FABRO_WORKER_TOKEN` env is set to a valid token in BOTH cases. Assert `FABRO_DEV_TOKEN` env is NOT set in either case. Assert no `--artifact-upload-token` or `--worker-token` arg appears in argv (env-only).
|
||||
- **Negative path (user-only route table):** for every route in the table below, assert presenting a valid worker token (with claims matching the run_id where applicable) is rejected. Tests MUST run under `AuthMode::Enabled` with a valid user-JWT key configured — under `AuthMode::Disabled`, `AuthenticatedService` accepts everything before any validation (`jwt_auth.rs:279`-style), so a "reject" assertion proves nothing. Model after the existing `jwt_auth.rs` tests that use `AuthMode::Enabled` with test secrets.
|
||||
|
||||
| Route | Handler | Expected status with worker token |
|
||||
|---|---|---|
|
||||
| `GET /runs` | `list_runs` | 401/403 |
|
||||
| `POST /runs` | `create_run` | 401/403 |
|
||||
| `GET /runs/resolve` | `resolve_run` | 401/403 |
|
||||
| `POST /preflight` | `run_preflight` | 401/403 |
|
||||
| `POST /graph/render` | `render_graph_from_manifest` | 401/403 |
|
||||
| `GET /attach` | `attach_events` | 401/403 |
|
||||
| `GET /boards/runs` | `list_board_runs` | 401/403 |
|
||||
| `GET /runs/{id}` | `get_run_status` | 401/403 |
|
||||
| `DELETE /runs/{id}` | `delete_run` | 401/403 |
|
||||
| `GET /runs/{id}/questions` | `get_questions` | 401/403 |
|
||||
| `POST /runs/{id}/questions/{qid}/answer` | `submit_answer` | 401/403 |
|
||||
| `GET /runs/{id}/attach` | `attach_run_events` | 401/403 |
|
||||
| `GET /runs/{id}/checkpoint` | `get_checkpoint` | 401/403 |
|
||||
| `POST /runs/{id}/cancel` | `cancel_run` | 401/403 |
|
||||
| `POST /runs/{id}/start` | `start_run` | 401/403 |
|
||||
| `POST /runs/{id}/pause` | `pause_run` | 401/403 |
|
||||
| `POST /runs/{id}/unpause` | `unpause_run` | 401/403 |
|
||||
| `POST /runs/{id}/archive` | `archive_run` | 401/403 |
|
||||
| `POST /runs/{id}/unarchive` | `unarchive_run` | 401/403 |
|
||||
| `GET /runs/{id}/graph` | `get_graph` | 401/403 |
|
||||
| `GET /runs/{id}/stages` | `list_run_stages` | 401/403 |
|
||||
| `GET /runs/{id}/artifacts` | `list_run_artifacts` | 401/403 |
|
||||
| `GET /runs/{id}/files` | `list_run_files` | 401/403 |
|
||||
| `GET /runs/{id}/stages/{stageId}/artifacts` | `list_stage_artifacts` | 401/403 |
|
||||
| `GET /runs/{id}/stages/{stageId}/artifacts/download` | `get_stage_artifact` | 401/403 |
|
||||
| `GET /runs/{id}/billing` | `get_run_billing` | 401/403 |
|
||||
| `GET /runs/{id}/settings` | `get_run_settings` | 401/403 |
|
||||
| `POST /runs/{id}/preview` | `generate_preview_url` | 401/403 |
|
||||
| `POST /runs/{id}/ssh` | `create_ssh_access` | 401/403 |
|
||||
| `GET /runs/{id}/sandbox/files` | `list_sandbox_files` | 401/403 |
|
||||
| `GET /runs/{id}/sandbox/file`, `PUT /runs/{id}/sandbox/file` | `get_sandbox_file`, `put_sandbox_file` | 401/403 |
|
||||
|
||||
Every route in the real-routes router (`server.rs:1162-1230`) except the 7 worker-touched routes is user-only. The acceptance criterion is a single test helper that iterates this explicit table and asserts rejection for each under `AuthMode::Enabled`. Routes that return `not_implemented` (turns, workflows, insights) are not included — they'll stay user-only automatically if ever implemented; flag in a follow-up if needed.
|
||||
- **Positive path for `put_stage_artifact`** (auth semantics changed — the only worker-touched route that previously had its own auth helper): explicit tests for the artifact upload route.
|
||||
- Valid worker token with matching `run_id` → 200 (octet-stream variant; multipart variant if cheap to set up).
|
||||
- Worker token with `claims.run_id != path.run_id` → 403.
|
||||
- Valid user JWT (no worker token) → 200 (R7 fall-through preserved on this route).
|
||||
- No bearer at all → 401.
|
||||
- Regression (env scrubbing): extend the existing `worker_allowlist_is_fail_closed` test (`spawn_env.rs:64-99`) to assert `FABRO_JWT_PRIVATE_KEY`, `FABRO_JWT_PUBLIC_KEY`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_CLIENT_SECRET`, `GITHUB_APP_WEBHOOK_SECRET` don't leak (alongside the existing `SESSION_SECRET` assertion).
|
||||
- Edge case: assert deleted symbols (`ArtifactUploadClaims`, `authorize_artifact_upload`, etc.) no longer exist — covered implicitly by `cargo build`.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds (no references to deleted artifact-upload-token symbols).
|
||||
- `cargo nextest run -p fabro-server` passes.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 4: Worker (CLI) — use injected worker token from env, stop reading `AuthStore`**
|
||||
|
||||
**Goal:** Worker subprocess reads its credential from `FABRO_WORKER_TOKEN` env at startup, uses it as its sole bearer for every server call, and never constructs `AuthStore::default()`. The artifact uploader holds the same token string in a per-call bearer field (the client's upload methods require a per-call bearer argument today).
|
||||
|
||||
**Requirements:** R1, R5.
|
||||
|
||||
**Dependencies:** Unit 2 (`Credential::Worker` variant), Unit 3 (server sets `FABRO_WORKER_TOKEN` env on the worker subprocess).
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/args.rs:808` — DELETE the `artifact_upload_token: Option<String>` field on `RunWorkerArgs`. Do NOT add a replacement clap arg — the worker reads from env directly.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/mod.rs:74-90` — drop the `artifact_upload_token` plumbing on the dispatch path.
|
||||
- Modify: `lib/crates/fabro-cli/src/server_client.rs` — add `pub(crate) async fn connect_server_target_with_bearer(target: &ServerTarget, bearer: &str) -> Result<Client>`. Builds `Client` with `.credential(Credential::Worker(bearer.to_owned()))`, no `oauth_session`, no `resolve_target_credential` call, no `AuthStore` access.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/runner.rs`
|
||||
- At top of `execute`: read `FABRO_WORKER_TOKEN` from env via `std::env::var`. Validate non-empty; bail with a clear error mentioning `FABRO_WORKER_TOKEN` if missing or empty (this is a server-bug indicator, not a user error). Drop `artifact_upload_token` from `execute`'s signature.
|
||||
- Line 67: replace `connect_server_target_direct(&server)` with `connect_server_target_with_bearer(&target, &worker_token)`.
|
||||
- Delete `MissingArtifactUploadTokenUploader` (300-317) and the `match artifact_upload_token { Some/None }` fork (~244-251); always construct `HttpArtifactUploader`.
|
||||
- `HttpArtifactUploader`: **keep** the per-call bearer field, rename `bearer_token: String` → `worker_token: String`. The client methods `upload_stage_artifact_file` and `upload_stage_artifact_batch` still require a per-call bearer parameter (no `Client::credential()` accessor exists today — see next bullet), so the uploader must hold the token and pass it per call. The token is the same string stored at client construction in `Credential::Worker`.
|
||||
- Keep `lib/crates/fabro-client/src/client.rs:1043, 1081` — `upload_stage_artifact_*` continue to take a `bearer_token` parameter. There is no `Client::credential()` accessor today (`credential` at `client.rs:176` is a builder setter, not a getter), so threading the token per-call is the path of least resistance. The worker-side caller passes the same `FABRO_WORKER_TOKEN` string it built the client with. (If a `Client::credential()` accessor is added later as a separate concern, the per-call parameter can be dropped then.)
|
||||
|
||||
**Stage-execution env scrubbing (narrow scope):**
|
||||
|
||||
The spawn site that runs user-supplied workflow stage commands must NOT see `FABRO_WORKER_TOKEN`: `LocalSandbox::execute` (`lib/crates/fabro-sandbox/src/local.rs:221`). It already does `env_clear` + safelist (`local.rs:43-66`) with a `_token` suffix denylist that incidentally catches `FABRO_WORKER_TOKEN`.
|
||||
|
||||
- Modify: `lib/crates/fabro-sandbox/src/local.rs:43-66` — add `"FABRO_WORKER_TOKEN"` (and `SESSION_SECRET`, `FABRO_JWT_PRIVATE_KEY`, `FABRO_JWT_PUBLIC_KEY`, `GITHUB_APP_PRIVATE_KEY`, `GITHUB_APP_CLIENT_SECRET`, `GITHUB_APP_WEBHOOK_SECRET`) to an explicit denylist alongside the suffix heuristic. Comment why: future rename like `FABRO_WORKER_AUTH` would silently leak under the suffix heuristic alone.
|
||||
- **Critical: filter both inherited env AND explicit `env_vars` extras.** `LocalSandbox::execute` (`local.rs:224`) appends caller-supplied `env_vars` after the inherited-env filter, so a stage config with `env_vars` containing `FABRO_WORKER_TOKEN` would still leak. Apply the same denylist to the `env_vars` extras path: drop any key in the denylist before calling `cmd.env(key, value)` on each extra.
|
||||
|
||||
**Hooks (host mode) — surgical scrub:**
|
||||
|
||||
`fabro-hooks/src/executor.rs:186` runs `sh -c <hook command>` for non-sandbox hooks and inherits the worker process env. Even though hooks are operator-configured (not random user input), they are still shell commands that have no business reading `FABRO_WORKER_TOKEN`.
|
||||
|
||||
- Modify: `lib/crates/fabro-hooks/src/executor.rs:186` — `cmd.env_remove("FABRO_WORKER_TOKEN")` (and the same six server-secret names listed above) on host-mode hook spawns. Targeted, defense-in-depth. Hooks remain operator-trusted; this just keeps the worker token out of their env.
|
||||
|
||||
**Out of scope for env scrubbing:** trusted internal subprocesses that run server-controlled code and may legitimately need credentials in their env: `gh auth token` (`fabro-github/src/lib.rs:129`), MCP server stdio (`fabro-mcp/src/client.rs:47`), git (`fabro-workflow/src/git.rs:35`). These are not user-attack surfaces. Do NOT scrub them.
|
||||
|
||||
**Approach:**
|
||||
- `connect_server_target_with_bearer` is the smallest possible surface: it skips the `AuthStore`/`OAuthSession` machinery entirely. The user-facing `connect_server_target` and `connect_server_with_settings` are unchanged.
|
||||
- The new constructor is the *only* path the worker takes; verify by grep that `commands::run::runner` is the only module importing it.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `server_client.rs:80-110` (`connect_managed_unix_socket_api_client_bundle`) for the client-builder shape; new constructor is a stripped-down version.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `connect_server_target_with_bearer` builds a `Client` whose outgoing requests carry `Authorization: Bearer <worker-token>`.
|
||||
- Edge case: `connect_server_target_with_bearer` does NOT call `AuthStore::default()` — verify by injecting a `FABRO_AUTH_FILE=/nonexistent` env override and confirming construction succeeds (the helper must not even attempt to read the file).
|
||||
- Edge case: `connect_server_target_with_bearer` does NOT install an `OAuthSession` (no refresh attempts on 401).
|
||||
- Integration: `runner::execute` with `FABRO_WORKER_TOKEN=<jwt>` set in env POSTs an event using only the injected token; no fallback to `auth.json`.
|
||||
- Error path: `runner::execute` invoked without `FABRO_WORKER_TOKEN` in env returns a clear error mentioning the variable name; does NOT silently fall back to user OAuth.
|
||||
- Edge case: `RunWorkerArgs` no longer has `artifact_upload_token` field — `cargo build` confirms.
|
||||
- Integration (env hygiene, sandbox path, **inherited**): worker env has `FABRO_WORKER_TOKEN=<jwt>` set; a workflow stage Bash command `env | grep -E "FABRO_WORKER_TOKEN|SESSION_SECRET|FABRO_JWT_PRIVATE_KEY"` prints empty output. Covers `LocalSandbox::execute` denylist correctness for inherited env.
|
||||
- Integration (env hygiene, sandbox path, **explicit env_vars**): a workflow stage configured with `env_vars: { FABRO_WORKER_TOKEN: "leaked", MY_VAR: "ok" }` produces a child env where `FABRO_WORKER_TOKEN` is absent but `MY_VAR=ok` is present. Covers the explicit-extras filter path. **Without this test, the explicit-env_vars bypass is undetected.**
|
||||
- Integration (env hygiene, hooks): a host-mode hook (`fabro-hooks/src/executor.rs:186`) spawned with `FABRO_WORKER_TOKEN` in the worker's env produces a child where `env | grep FABRO_WORKER_TOKEN` is empty.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` succeeds.
|
||||
- `cargo nextest run -p fabro-cli` passes.
|
||||
- grep for `AuthStore` from `commands/run/` returns no hits.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 5: Stamp `system:worker` actor on worker-emitted events (worker-side sink wrapper)**
|
||||
|
||||
**Goal:** Events the worker emits without a typed actor get a `system:worker` stamp at the *worker-side sink layer*. User identity stays on the run record (`RunSpec.provenance.subject`), where it already lives.
|
||||
|
||||
**Requirements:** R6.
|
||||
|
||||
**Dependencies:** Should land WITH the auth changes (Units 1-4), not in isolation. Landing alone produces a wire-visible behavior change (worker events flip from `actor: None` to `actor: System(worker)`) without the auth context that justifies it.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/event.rs` — add `RunEventSink::Map { transform, inner }` variant that applies `transform` to each event before forwarding to `inner`. Wire it into the existing dispatch logic so all events reach the inner sink already transformed.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/runner.rs` — at the `RunEventSink::fanout([...])` construction site (`runner.rs:100`), wrap the fanout in `RunEventSink::Map { transform: stamp_system_worker, inner: ... }` so the stamp applies to all downstream sinks (backend HTTP, local callback, future).
|
||||
- Test: `lib/crates/fabro-workflow/src/event.rs` (test the `Map` variant in isolation).
|
||||
- Test: `lib/crates/fabro-cli/src/commands/run/runner.rs` (test the worker-local stamp wrapper end-to-end).
|
||||
|
||||
**Approach:**
|
||||
- **Critical: do NOT modify `lib/crates/fabro-workflow/src/event.rs::to_run_event_at` or `stored_event_fields`.** Those helpers are shared with the server (e.g. `server.rs:6702` flushes lifecycle events through `workflow_event::to_run_event`). Default-filling there mis-stamps server-emitted events.
|
||||
- Helper function (not `const` — `ActorRef::id`/`display` are `Option<String>`, heap-allocated): `fn system_worker_actor() -> ActorRef { ActorRef { kind: ActorKind::System, id: Some("worker".to_string()), display: Some("system:worker".to_string()) } }` lives in `runner.rs` (worker-local).
|
||||
- **Stamping must apply to the whole fanout, not just one sink variant.** `RunEventSink` is an enum (`Backend | Callback | Composite | …`) in `fabro-workflow/src/event.rs`. Wrapping only the `Backend` variant means the local callback (today: `update_worker_title_from_event`) and any future sink see unstamped events.
|
||||
- **Design: add `RunEventSink::Map { transform: Arc<dyn Fn(RunEvent) -> RunEvent + Send + Sync>, inner: Box<RunEventSink> }`** variant. Worker constructs `RunEventSink::Map { transform: stamp_system_worker, inner: Box::new(RunEventSink::fanout([backend, callback])) }`; stamp applies before the fanout splits.
|
||||
- **Dispatch: non-recursive, iterative, owned per branch.** The existing `write_run_event` at `event.rs:2698` uses an iterative stack with a single shared `&RunEvent`. Naively translating `Map => inner.write_run_event(&mapped).await` would introduce recursive async (doesn't compile cleanly without boxing each recursive call, and obscures the shape).
|
||||
- Redesign the traversal to carry **`(sink, owned_event)` pairs** on the stack instead of `(&sink, &event)`. Each node owns the `RunEvent` value for its subtree.
|
||||
- `Map { transform, inner }`: apply `transform` to the owned event → push `(*inner, transformed_event)` onto the stack. The branch downstream sees the new event; the original is dropped when this stack frame unwinds.
|
||||
- `Composite { sinks }`: for each child sink, push `(child, event.clone())`. Each branch gets its own owned event. (Cloning `RunEvent` is cheap — it's a struct of owned data already serialized once; no deep-copy of large payloads.)
|
||||
- `Backend { ... }` / `Callback { ... }`: terminal — invoke with the owned event, no recursion.
|
||||
- Keep the existing async-loop shape; only the stack element type changes.
|
||||
- The transform applies the value-based rule: **if `event.actor.is_none()`, fill with `system_worker_actor()`**. Agent events (`AssistantMessage`) keep `ActorKind::Agent` because `actor.is_some()`. Worker self-cancel events (`Event::RunCancelRequested { actor: None }`) correctly get the system actor.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `RunEventSink::fanout` composition (`fabro-workflow/src/event.rs` sink layer).
|
||||
- Existing actor-stamping for lifecycle events at the server endpoints (`actor_from_subject` at `server.rs:6175`) — server-side stamping for user actions; worker-side wrapper for worker events.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path (`Map` variant): a `RunEventSink::Map { transform: |e| e.with_actor(ActorRef::user("alice")), inner: backend }` applied to an event with any actor → forwarded event has actor = `ActorRef::user("alice")` regardless. Confirms the variant works.
|
||||
- Happy path (worker stamp): a stage-execution `RunEvent { actor: None, ... }` enters the wrapped fanout → BOTH the backend sink AND the local callback see `actor: Some(ActorRef { kind: System, id: Some("worker"), display: Some("system:worker") })`.
|
||||
- Edge case: `RunEvent { actor: Some(user_actor), ... }` → both sinks retain the user actor (`actor.is_some()` → no-op).
|
||||
- Edge case: agent message `RunEvent { actor: Some(ActorKind::Agent), ... }` → both sinks retain `ActorKind::Agent`.
|
||||
- Edge case: worker self-cancel `RunEvent { actor: None, body: RunCancelRequested { ... } }` → both sinks get `system:worker`.
|
||||
- Per-sink uniformity assertion: construct the worker's actual fanout (Backend + Callback), feed an `actor: None` event in, capture what each sink receives, assert both have `system:worker`. Without this test, only stamping the Backend variant could regress without detection.
|
||||
- Regression: server-side event flush via `workflow_event::to_run_event` (`server.rs:6702`) is unchanged — `to_run_event_at` retains its passthrough semantics.
|
||||
- Regression: `create_hydrates_provenance_into_store_state` (`fabro-workflow/src/operations/create.rs`) still passes — originator user identity still on `RunSpec.provenance.subject`.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli` passes.
|
||||
- New tests for the default-fill and the override-protections both pass.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 6: End-to-end regression — github-only worker run with no `~/.fabro/auth.json`**
|
||||
|
||||
**Goal:** Lock in the bug fix: a github-only deployment can spawn a worker that completes a run, with no user OAuth artifact present on the worker host. Worker authenticates using only `FABRO_WORKER_TOKEN`.
|
||||
|
||||
**Requirements:** R1, R5.
|
||||
|
||||
**Dependencies:** Units 1-5.
|
||||
|
||||
**Files:**
|
||||
- Create: an integration test under `lib/crates/fabro-cli/tests/it/cmd/` (existing test scaffolding) — file name per local convention (e.g. `worker_auth.rs`).
|
||||
|
||||
**Approach:**
|
||||
- **Test fixture:**
|
||||
- Server configured with `auth.methods = ["github"]` only; no `FABRO_DEV_TOKEN` in `server.env`.
|
||||
- `FABRO_HOME` redirected to a fresh tempdir on the *worker* side (no `auth.json`, no `dev-token` file).
|
||||
- Submitter path uses an authenticated test user JWT (minted directly via `auth/jwt.rs::issue` with the test `SESSION_SECRET`) to call `POST /runs` and start the run. **Do not** confuse this with the worker's auth — the user JWT is what authorizes run creation; the worker JWT (server-issued in response) is what the worker subprocess uses.
|
||||
- Run a tiny workflow end-to-end via the daemon → worker spawn path.
|
||||
- Assert the worker successfully POSTs at least one `RunEvent` and the run reaches a terminal status.
|
||||
- Assert `~/.fabro/auth.json` is not touched (non-existence at the redirected `FABRO_HOME`).
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing integration tests in `lib/crates/fabro-cli/tests/it/cmd/` (per `support.rs` helpers like `daemon.bind.to_target()`).
|
||||
- CLAUDE.md note: tests must use `.no_proxy()` HTTP clients.
|
||||
|
||||
**Test scenarios:**
|
||||
- Integration: github-only server + no `auth.json` on worker host + minimal workflow → run completes successfully; events visible via `GET /runs/{id}/events`.
|
||||
- Integration: same setup but worker spawned with a deliberately-bogus `FABRO_WORKER_TOKEN` (e.g. valid HS256 but wrong `run_id` claim) → worker fails fast on first server call.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-cli --test it` passes the new test.
|
||||
- Test fails on `main` (pre-Units 1-5) — confirms it covers the regression.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** Worker subprocess no longer reads `~/.fabro/auth.json`. CLI user-facing commands (`fabro run`, `fabro ps`, `fabro auth`, etc.) unchanged — they still go through `connect_server_target` / `connect_server_with_settings`. SSE attach endpoints unchanged: worker is a producer, not a consumer; user-JWT-only auth on those routes preserved.
|
||||
- **Error propagation:** Worker token expiry mid-run → next server call returns 401, worker exits with a generic error, server marks run failed via existing pump-worker exit handling at `server.rs:4786`. No new error class.
|
||||
- **State lifecycle:** Server restart with HKDF-derived key: outstanding worker tokens remain valid up to natural expiry. Server restart with `SESSION_SECRET` rotated: outstanding workers fail at next call (acceptable; matches user-session invalidation). No revocation set.
|
||||
- **Event sink uniformity:** the worker wraps its `RunEventSink::fanout([Store(http), Callback])` (`runner.rs:100`) in `RunEventSink::Map { transform: stamp_system_worker, inner: fanout }`, so the stamp applies once *before* the fanout splits — both the HTTP backend and the local callback observe identical actor metadata. The shared `to_run_event_at` converter remains pure (passthrough). A test asserts per-sink uniformity directly.
|
||||
- **API surface parity:** `RunEvent.actor` shape unchanged (`ActorRef` already has `ActorKind::System`); worker-emitted events newly carry `system:worker` instead of `None`. Web UI audit (`apps/fabro-web/app/`) found ZERO references to `actor` or `author` today — nothing to break.
|
||||
- **Worker-process trust degradation:** A workflow stage that compromises the worker process (malicious shell, code injection) gains read access to `FABRO_WORKER_TOKEN` for the worker's lifetime + up to 72h until natural expiry. Blast radius bounded by run-id claim: only the compromised run's blobs/events/state are accessible. Not cross-run. `SESSION_SECRET` is NOT in the worker's env (`apply_worker_env` allowlist) so the worker cannot mint cross-run tokens.
|
||||
- **Integration coverage:** Unit 6 covers github-only-no-auth-store regression; existing CLI integration tests cover dev-token deployments.
|
||||
- **Unchanged invariants:** End-user auth (dev-token / github) unchanged. `RunAuthMethod` enum unchanged. `RunSpec.provenance` shape unchanged. Webhook auth unchanged. Lifecycle/admin/SSE/list endpoints continue to require user auth — worker token explicitly rejected on all of them. `OpenAPI` / `fabro-api-client` (TypeScript) DTOs unchanged.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Worker process inherits `SESSION_SECRET` → can mint tokens for any run, defeating per-run binding | **Already structurally mitigated**: `apply_worker_env` at `spawn_env.rs:18` does `env_clear` + 8-name allowlist that excludes `SESSION_SECRET`. Existing `worker_allowlist_is_fail_closed` test asserts this. Unit 3 extends the test to also cover `FABRO_JWT_*` and `GITHUB_APP_*`. |
|
||||
| Token leaks via `format!`/`Display`/`tracing` of `Credential::Worker` payload | `Credential::Worker` has redacted `Debug`, no `Display`. Compile-time guard test in Unit 2 asserts `!impl Display`. Audit logging in Unit 2 logs `jti` only, never the token. |
|
||||
| Sentry / panic capture serializes the worker's env or backtrace locals | Sentry panic hook (`fabro-telemetry/src/panic.rs`) captures only panic message + stacktrace, not env or frame variables. Code review responsibility to keep token out of panic format strings. |
|
||||
| 72h token compromised mid-run, attacker uses it from any host on network | Run-id binding limits blast radius to one run. No revocation; rotating `SESSION_SECRET` is the only invalidation mechanism (also invalidates user sessions). Acceptable for current threat model. |
|
||||
| `FABRO_WORKER_TOKEN` readable via `/proc/<pid>/environ` to same-UID processes on Linux | Documented in Threat Model: env-var transport does not protect against same-UID reads. Multi-tenant deployments must isolate per-tenant via separate UIDs / containers. NOT a property of this design. |
|
||||
| Workflow stage child processes (sandbox-executed Bash) inherit `FABRO_WORKER_TOKEN` via env or via explicitly-supplied `env_vars` extras | `LocalSandbox::execute` filters BOTH the inherited env (existing safelist + denylist) AND the `env_vars` extras path (new in Unit 4). Two regression tests prove both paths. |
|
||||
| Host-mode hook commands inherit `FABRO_WORKER_TOKEN` | `fabro-hooks/src/executor.rs` does targeted `cmd.env_remove("FABRO_WORKER_TOKEN")` (and the same six server-secret names) on host-mode hook spawns. Hooks remain operator-trusted; this is defense-in-depth — shell commands have no business reading the worker token. |
|
||||
| Trusted internal subprocesses (`gh`, MCP, git) inherit env including `FABRO_WORKER_TOKEN` | NOT scrubbed by design — these run server-controlled code, may legitimately need credentials, and are not user-attack surfaces. Documented in Unit 4. |
|
||||
| `client.upload_stage_artifact_*` API requires a per-call bearer parameter | Per Unit 4: `HttpArtifactUploader` holds the token in a `worker_token: String` field (same string read from `FABRO_WORKER_TOKEN`) and threads it per call. No `Client::credential()` accessor today; per-call threading is the path of least churn. |
|
||||
| Same-run concurrent worker spawn (scheduler race) → two valid tokens for one `run_id` racing on event/state appends | Scheduler's at-most-one-worker-per-run guarantee is assumed but not verified by this plan. If a race exists today, follow-up plan adds a server-side spawn lock or a per-spawn nonce. Out of scope here. |
|
||||
| Rapid pause/resume cycles leave multiple valid tokens per run | Each prior worker token remains valid up to its 72h `exp`. Multiplicative compromise window bounded by run-id. Accepted; out of scope to fix here. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- `docs-internal/` — if any internal doc describes worker auth (search before landing), update to reflect: "worker → server auth uses a server-issued per-run JWT, independent of end-user auth method."
|
||||
- No external user-facing doc impact (no public API change; CLI args on `__run-worker` are internal-only, hidden via `#[command(hide = true)]`).
|
||||
|
||||
### Deploy story (greenfield, atomic swap)
|
||||
|
||||
No shipped deployments to preserve. Atomic swap:
|
||||
1. Deploy new binary; server restarts.
|
||||
2. New runs spawn workers with `FABRO_WORKER_TOKEN` in env; worker uses it via `Credential::Worker`.
|
||||
3. Old artifact-upload-token mechanism is gone from the codebase entirely.
|
||||
|
||||
No drain, no shim, no checklist beyond verifying `SESSION_SECRET` is set (HKDF key derives from it).
|
||||
|
||||
## Sources & References
|
||||
|
||||
- Worker auth surface inventory: `lib/crates/fabro-cli/src/commands/run/runner.rs:55-127`
|
||||
- Artifact-upload-token model to replace: `lib/crates/fabro-server/src/server.rs:287-289, 752-854`
|
||||
- Worker spawn site: `lib/crates/fabro-server/src/server.rs:3701-3755`
|
||||
- Existing HKDF key derivation: `lib/crates/fabro-server/src/auth/keys.rs:41`
|
||||
- Existing worker env allowlist: `lib/crates/fabro-server/src/spawn_env.rs:18`
|
||||
- `Credential` variants: `lib/crates/fabro-client/src/credential.rs:6-30`
|
||||
- `ActorRef` / `ActorKind`: `lib/crates/fabro-types/src/run_event/mod.rs:29-81`
|
||||
- `RunProvenance`: `lib/crates/fabro-types/src/run.rs:34-49`
|
||||
- Stage-execution chokepoint: `lib/crates/fabro-sandbox/src/local.rs:221, 43-66`
|
||||
- Coordinated plans: `docs/plans/2026-04-22-003-refactor-lock-down-server-secrets-plan.md`, `docs/plans/2026-04-19-003-feat-cli-auth-login-plan.md`, `docs/plans/2026-04-20-001-fix-cli-server-same-host-assumptions-plan.md`
|
||||
- Origin of artifact-upload-token pattern: `docs/plans/2026-04-06-object-backed-artifact-uploads.md:42-45`
|
||||
- Worker subprocess history: `docs/plans/2026-04-06-subprocess-run-workers-signal-control-plan.md`, `docs/plans/2026-04-07-worker-http-only-run-store-migration-plan.md`
|
||||
|
|
@ -1,306 +0,0 @@
|
|||
---
|
||||
title: "refactor: collapse settings resolve indirection layer"
|
||||
type: refactor
|
||||
status: completed
|
||||
date: 2026-04-23
|
||||
---
|
||||
|
||||
# refactor: collapse settings resolve indirection layer
|
||||
|
||||
## Overview
|
||||
|
||||
Delete `fabro_config::Resolver`, the per-`*Settings` `*_into(&mut errors)` methods, the private `ResolvedSettingsTree` in `fabro-workflow`, and the `resolve_settings_tree` free fn. Add a `WorkflowSettings` sibling to `ServerSettings`/`UserSettings` so workflow ops have one entrypoint. Standalone `resolve_*_from_file` helpers stay (single-namespace consumers depend on them) but get rewritten to not go through `Resolver`.
|
||||
|
||||
`WorkflowSettings` is **workflow-only**: `{ project, workflow, run }`. It does NOT hold `server` or `features` — even though the per-request layer DOES carry `features` and a subset of `server` (storage, scheduler, artifacts, web, api) per `materialize_settings_layer`. Excluding them is an **ownership choice**: we want the live `ServerSettings` (resolved at server boot) to remain the single authority for deployment-level config, and we don't want a workflow-side parallel copy that can quietly drift. `ServerSettings` and `UserSettings` keep `features` because they're constructed from a complete owned settings layer at boot — they ARE the authority.
|
||||
|
||||
Today's lifted `server_storage_root` field on `ResolvedSettingsTree` was an asymmetric workaround for "create_run needs one server-ops field but has no access to live `ServerSettings`." The fix: `create_run` gains a `storage_root: PathBuf` parameter so the caller (which owns the live `ServerSettings`) supplies it. No more lifted server fields anywhere.
|
||||
|
||||
PR 2 (Combine trait + derive, uv pattern) is a separate, larger refactor — instructions in `docs/plans/2026-04-23-002-refactor-combine-trait-uv-pattern-plan.md`.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Today three layers sit between `SettingsLayer` and consumer code:
|
||||
|
||||
1. `Resolver` (introduced in 52d24531d) — caches `apply_builtin_defaults` across multiple per-namespace resolves.
|
||||
2. `*_into(&mut errors)` methods on `Resolver` — let `ServerSettings::from_layer` and `UserSettings::from_layer` accumulate errors across two namespaces.
|
||||
3. `resolve_settings_tree` + `ResolvedSettingsTree` in `fabro-workflow/src/operations/create.rs` — bundles four namespaces for `create_run`.
|
||||
|
||||
`Resolver` exists only because `create_run` was running 4× `apply_builtin_defaults(file.clone())` per request. It's a perf micro-fix dressed up as an API primitive. `ResolvedSettingsTree` is the missing `WorkflowSettings` sibling of `ServerSettings`/`UserSettings` — wrong crate, wrong name, asymmetric shape (lifts `storage_root: InterpString` instead of holding a full `ServerNamespace`).
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- R1. Single entrypoint per consumer (Server/User/Workflow), each with `from_layer(&SettingsLayer) -> Result<...>`.
|
||||
- R2. Multi-namespace error accumulation preserved — `*Settings::from_layer` must surface errors from ALL its namespaces, not first-only.
|
||||
- R3. Standalone `resolve_*_from_file` helpers continue to work for single-namespace consumers (dozens of callers across the workspace).
|
||||
- R4. **`WorkflowSettings` holds workflow-owned namespaces only** (`project`, `workflow`, `run`). `server` and `features` are excluded as an ownership choice — the live `ServerSettings` is the single authority for deployment-level config, even though `materialize_settings_layer` does flow `features` and a subset of `server.*` (storage, scheduler, artifacts, web, api) through into the per-request layer. `ServerSettings` and `UserSettings` are constructed at boot from a complete owned settings layer and hold every namespace their consumer reads. Server-ops fields needed by `create_run` (today: just `storage.root`) come from the caller as parameters, not from the bundle.
|
||||
- R5. No change to resolved-settings semantics or to persisted `Event::RunCreated.settings` shape. **`record.run_dir` is now derived from the new `storage_root` parameter, not from `request.settings.server.storage.root` as today.** For the production HTTP caller (which passes the same resolved `server.storage.root` it would have read from the live `ServerSettings`), `record.run_dir` matches today's value. For direct `create()` callers (test helpers, future API consumers) that pass a different path, `record.run_dir` will reflect the parameter — that is the new invariant. The other consumer-visible changes are: (a) `create_run`'s signature gains one parameter (R7); (b) the storage-root interpolation-failure error path moves from workflow-side to transport-side with different error text — see Risks.
|
||||
- R6. **Workflow-settings resolution errors preserve `render_resolve_errors` formatting** (today: `; `-joined). `WorkflowSettings::from_layer` returns `Result<Self, Vec<ResolveError>>` (matching the `resolve_*_from_file` convention) so `create_run` keeps formatting via `render_resolve_errors`. R6 covers ONLY the `resolve_*` failure path inside `from_layer` — not the storage-root interpolation failure, which moves out of `create_run` per R5.
|
||||
- R7. `create_run`'s signature gains a `storage_root: PathBuf` parameter. Callers supply it from the live deployment context: `fabro-server` reads it from its boot-time `ServerSettings`; tests pass a fixture path.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Out of scope: the Combine refactor (PR 2).
|
||||
- Out of scope: migrating every `resolve_*_from_file` caller to a bundle. Standalone helpers stay; only `create_run` gets the bundle treatment.
|
||||
- Out of scope: removing `render_resolve_errors` (used by 4+ callers; orthogonal).
|
||||
- Out of scope: changing the `*Layer` / `*Namespace` types in `fabro-types`.
|
||||
- Out of scope: changing `apply_builtin_defaults`, `defaults.toml`, or any per-namespace `resolve_*(layer, &mut errors)` function body.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-config/src/context.rs` — current `ServerSettings` and `UserSettings` (use `Resolver`).
|
||||
- `lib/crates/fabro-config/src/resolve/resolver.rs` — entire file deletes.
|
||||
- `lib/crates/fabro-config/src/resolve/mod.rs` — `resolve_storage_root` + 6× `resolve_*_from_file` helpers (today: thin wrappers over `Resolver`; rewrite to inline `apply_builtin_defaults` + per-namespace resolve).
|
||||
- `lib/crates/fabro-config/src/resolve/{cli,server,project,features,run,workflow}.rs` — per-namespace `resolve_*` fns; bodies unchanged. Visibility stays `pub` (callers in tests + helper crates).
|
||||
- `lib/crates/fabro-config/src/defaults.rs` — `apply_builtin_defaults(layer: SettingsLayer) -> SettingsLayer`. One clone per call.
|
||||
- `lib/crates/fabro-workflow/src/operations/create.rs:63-68` — `ResolvedSettingsTree`; `:116` use site; `:166` `combined_labels` call; `:287-297` `resolve_settings_tree`; `:299-304` `combined_labels` fn.
|
||||
- `lib/crates/fabro-config/src/resolve/server.rs:68-75` — `resolve_storage` already substitutes `default_storage_dir()` when `server.storage.root` is missing. `Resolver::storage_root()` was duplicating this. With `server` excluded from `WorkflowSettings`, the duplication moves: the single authority for storage_root is now whatever `ServerSettings::server.storage.root` resolves to at server boot (used by the existing `state.server_storage_dir()` helper).
|
||||
- `lib/crates/fabro-server/src/server.rs:577,643,659` — `AppState.settings` is a raw `Arc<RwLock<SettingsLayer>>`; `AppState.server_settings` is a separate `RwLock<Arc<ServerSettings>>` accessed via `state.server_settings()` (line 643). There IS a `state.server_storage_dir() -> PathBuf` helper (line 659), **but it panics on interpolation failure** (`.expect("server storage root should be resolved at startup")`). Today's `create()` returns `Error::Precondition` on the same failure (`create.rs:118-126`). Unit 3 must NOT use `server_storage_dir()` — the HTTP handler has to do its own `resolve_interp_string` and map errors to `ApiError`. See Unit 3 Approach.
|
||||
- `lib/crates/fabro-config/src/effective_settings.rs:55-64` — documents that `server_settings.features` AND a small subset of `server_settings.server` (storage, scheduler, artifacts, web, api) ARE applied authoritatively into the per-request layer. Server-ops fields (auth, listen, ip_allowlist, slatedb, logging, integrations) are stripped. So the per-request layer DOES carry storage and features — `WorkflowSettings` excludes them by **ownership choice** (we want the live `ServerSettings` to be the single authority for deployment-level config), not by capability constraint.
|
||||
|
||||
### Call Site Audit (verified)
|
||||
|
||||
`resolve_*_from_file` standalones — KEEP (dozens of callers):
|
||||
- `resolve_run_from_file`: 20+ callers across fabro-cli, fabro-server, fabro-workflow, tests
|
||||
- `resolve_server_from_file`: 12+ callers across fabro-cli, fabro-server, fabro-install, tests
|
||||
- `resolve_features_from_file`: `fabro-server/src/server.rs:1364`
|
||||
- `resolve_project_from_file` / `resolve_workflow_from_file` / `resolve_cli_from_file`: callers in `fabro-config/src/project.rs`, fabro-cli, tests
|
||||
- `resolve_storage_root`: 1 external caller (`fabro-cli/src/local_server.rs:15`) + tests
|
||||
|
||||
`Resolver` — DELETE (1 caller):
|
||||
- `lib/crates/fabro-workflow/src/operations/create.rs:288` (in `resolve_settings_tree`)
|
||||
|
||||
`ResolvedSettingsTree` / `resolve_settings_tree` / `combined_labels` (free fn) — DELETE (private to `create.rs`, all uses local).
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
None directly applicable. The original `Resolver` commit (52d24531d) explicitly framed itself as a perf optimization, not an API improvement — its rationale evaporates once the per-consumer bundles each do their own apply-defaults.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Principle: `WorkflowSettings` holds workflow-owned namespaces only.** `{ project, workflow, run }` — the namespaces whose authority belongs to the workflow consumer. `server` and `features` are excluded as an *ownership choice* (live `ServerSettings` is the single authority for deployment-level config), even though `materialize_settings_layer` makes them available in the per-request layer. `ServerSettings` and `UserSettings` are constructed from a complete owned layer at boot and hold every namespace their consumer reads.
|
||||
- **`create_run` gains `storage_root: PathBuf` parameter.** Storage root is deployment-level config — it belongs to whoever booted the server. Lifting it through a per-request bundle (today's `ResolvedSettingsTree.server_storage_root`) was an asymmetric workaround. Pushing it to a parameter eliminates the asymmetry and makes the data-flow honest. The caller resolves env-var interpolation before passing and maps any resolution error to the appropriate transport-level response.
|
||||
- **Persisted settings layer is the request-derived/materialized artifact; do NOT overwrite it.** What lands in `Event::RunCreated.settings` is not the raw submitted layer — `create()` runs `materialize_run(settings, ...)` first (`create.rs:407`) which normalizes and applies graph-time materialization. Treat the persisted field as "the materialized request artifact." `Event::RunCreated` carries two separate fields (`create.rs:234-265`): `settings: <JSON of materialized SettingsLayer>` and `run_dir: String` (where the run actually went). They serve different purposes and should remain separately recorded. The `storage_root` parameter is the runtime authority for `create_run`; `record.run_dir` is the persisted authority for "where is this run?" downstream. `record.settings.server.storage.root` is whatever the materialized layer carries — possibly an env-template that resolved differently at runtime than what `record.run_dir` records. Future code that needs the path should read `run_dir`, not re-resolve the layer. Audit (one grep) confirmed no current `fabro-workflow` consumer reads `settings.server.storage.root` from a persisted record beyond the line being removed.
|
||||
- **Keep standalone `resolve_*_from_file` helpers; rewrite without `Resolver`.** Each becomes `apply_builtin_defaults(file.clone())` + `resolve_<ns>(&layer.<ns>.unwrap_or_default(), &mut errors)`. Rationale: dozens of single-namespace callers (e.g. "is this a dry run?" → `resolve_run_from_file(...)?.execution.mode`); forcing them through a bundle would pay full validation cost for one field.
|
||||
- **`WorkflowSettings::from_layer` returns `Result<Self, Vec<ResolveError>>`.** Asymmetric with `ServerSettings::from_layer` and `UserSettings::from_layer` (which return `fabro_config::Result<Self>` wrapping `Error::Resolve`), but symmetric with `resolve_*_from_file`. Reason: preserves `create_run`'s existing user-visible error format (`; `-joined via `render_resolve_errors`); changing it would be an unowned scope expansion (R6). Existing `Server`/`UserSettings` callers undisturbed.
|
||||
- **`combined_labels` becomes a method on `WorkflowSettings`.** Free fn was only callable in one place.
|
||||
- **Each `*Settings::from_layer` calls `apply_builtin_defaults(layer.clone())` independently.** Acceptable — `create_run` is human-paced, not per-request.
|
||||
- **Visibility of per-namespace `resolve_*` fns stays `pub`.** Called by `*_from_file` standalones and tests.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Should `WorkflowSettings` hold `ServerNamespace` and/or `FeaturesNamespace`?** Neither. Per R4, `WorkflowSettings` holds workflow-owned namespaces only. Server-ops and features ARE available in the per-request layer (via `materialize_settings_layer`), but excluded from the bundle as an ownership choice — live `ServerSettings` is the single authority for deployment-level config.
|
||||
- **Where does `create_run` get `storage.root` if not from the bundle?** From a `storage_root: PathBuf` parameter. Caller (fabro-server, tests) supplies it. See R7.
|
||||
- **Should we migrate every `resolve_*_from_file` caller to a bundle?** No. Standalones stay; bundles are for multi-namespace consumers only.
|
||||
- **Does `combined_labels` belong as a method or free fn?** Method on `WorkflowSettings`.
|
||||
- **What error type does `WorkflowSettings::from_layer` return?** `Result<Self, Vec<ResolveError>>` (matches `resolve_*_from_file`, preserves `create_run`'s existing error message format via `render_resolve_errors`). `Server`/`UserSettings` keep their existing `fabro_config::Result<Self>` shape.
|
||||
- **Should `resolve_storage_root` standalone keep its separate identity?** Yes, keep it (rewrite inline). It's used by `fabro-cli/src/local_server.rs:15` to compute a runtime path without resolving full server settings; that use case remains. Don't migrate that caller in this PR.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Test layout for `WorkflowSettings`.** Either add to `lib/crates/fabro-config/tests/resolve_root.rs` (existing multi-namespace tests live there) or new file `tests/workflow_settings.rs`. Pick during implementation based on what reads better.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Add `WorkflowSettings` to `fabro-config::context`**
|
||||
|
||||
**Goal:** New consumer bundle for workflow ops, sibling to `ServerSettings`/`UserSettings`. Workflow-only namespaces.
|
||||
|
||||
**Requirements:** R1, R2, R6
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-config/src/context.rs`
|
||||
- Modify: `lib/crates/fabro-config/src/lib.rs` (export `WorkflowSettings`)
|
||||
- Test: `lib/crates/fabro-config/tests/resolve_root.rs` OR new `tests/workflow_settings.rs`
|
||||
|
||||
**Approach:**
|
||||
- Add a `pub struct WorkflowSettings` with all fields `pub`:
|
||||
- `pub project: ProjectNamespace`
|
||||
- `pub workflow: WorkflowNamespace`
|
||||
- `pub run: RunNamespace`
|
||||
Every field is `pub` so cross-crate field access from `fabro-workflow` works.
|
||||
- Add `WorkflowSettings::from_layer(layer: &SettingsLayer) -> Result<Self, Vec<ResolveError>>`. Returns `Vec<ResolveError>` (NOT wrapped in `fabro_config::Error::Resolve`) so callers can format via existing `render_resolve_errors`. Body: `apply_builtin_defaults(layer.clone())`, then call `resolve_project`, `resolve_workflow`, `resolve_run` into a shared `Vec<ResolveError>`. Return `Ok(Self { ... })` if `errors.is_empty()`, else `Err(errors)`.
|
||||
- Add `WorkflowSettings::combined_labels(&self) -> HashMap<String, String>` — extend `project.metadata`, then `workflow.metadata`, then `run.metadata` (later wins on key conflict). Match today's `combined_labels` free fn ordering exactly.
|
||||
- Do NOT yet delete `*_into` methods or `Resolver`. This unit is purely additive.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `resolve_*_from_file` helpers in `lib/crates/fabro-config/src/resolve/mod.rs` for the `Result<_, Vec<ResolveError>>` return shape and the per-namespace inline pattern.
|
||||
- For the `combined_labels` ordering, today's free fn in `lib/crates/fabro-workflow/src/operations/create.rs:299-304`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `SettingsLayer::default()` resolves successfully. (Unlike `resolve_server` — which requires explicit `server.auth.methods` per `tests/resolve_root.rs:8` — the workflow-only namespaces have all required defaults in `defaults.toml`.)
|
||||
- Happy path: layer with `project.metadata`, `workflow.metadata`, `run.metadata` produces `combined_labels` containing the union, with later sections winning on key conflict.
|
||||
- Error path: layer with invalid `run.sandbox.provider` (e.g. `"not-a-provider"`) returns `Err(errors)` containing a `ResolveError` for `run.sandbox.provider`. (See existing fixture in `tests/resolve_root.rs:38`.)
|
||||
- Error path: layer with multiple invalid fields *within* `run` (e.g. invalid `sandbox.provider` PLUS another resolve_run-emitting error — pick from existing run-resolve test fixtures during implementation) returns ALL of them in one `Err`. Proves R2 — the shared `errors` vec is being threaded through all `resolve_*` calls in `from_layer`. (Note: `resolve_project` and `resolve_workflow` cannot emit errors today — `lib/crates/fabro-config/src/resolve/{project,workflow}.rs` both ignore the `errors` vec — so a "two namespaces both error" test isn't constructible. The within-`run` test is the closest structural proof we can write.)
|
||||
|
||||
**Verification:**
|
||||
- New tests pass.
|
||||
- `WorkflowSettings` is exported from `fabro_config` and constructable from any test fixture.
|
||||
- All three fields publicly accessible from outside `fabro_config` (smoke-test by reading `wf.run.execution.mode` from a test file).
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2: Delete `Resolver`; rewrite `*Settings::from_layer` and `resolve_*_from_file` to not depend on it**
|
||||
|
||||
**Goal:** Remove the `Resolver` indirection. Each consumer-bundle constructor and each standalone helper inlines `apply_builtin_defaults` + the per-namespace resolve.
|
||||
|
||||
**Requirements:** R2, R3, R5
|
||||
|
||||
**Dependencies:** Unit 1 (so `WorkflowSettings` exists; not strictly required for this unit, but Unit 3 depends on both and ordering is cleaner).
|
||||
|
||||
**Files:**
|
||||
- Delete: `lib/crates/fabro-config/src/resolve/resolver.rs`
|
||||
- Modify: `lib/crates/fabro-config/src/resolve/mod.rs` (remove `mod resolver;` and `pub use resolver::Resolver;`; rewrite the 6 `resolve_*_from_file` helpers + `resolve_storage_root` to inline)
|
||||
- Modify: `lib/crates/fabro-config/src/context.rs` (rewrite `ServerSettings::from_layer` and `UserSettings::from_layer` without `Resolver`)
|
||||
- Modify: `lib/crates/fabro-config/src/lib.rs` (remove `Resolver` from re-exports)
|
||||
|
||||
**Approach:**
|
||||
- Each `resolve_*_from_file(file)` becomes:
|
||||
```
|
||||
let layer = apply_builtin_defaults(file.clone());
|
||||
let mut errors = Vec::new();
|
||||
let value = resolve_<ns>(&layer.<ns>.clone().unwrap_or_default(), &mut errors);
|
||||
if errors.is_empty() { Ok(value) } else { Err(errors) }
|
||||
```
|
||||
- `resolve_storage_root(file)` becomes a thin extraction from a defaulted layer (same logic as today's `Resolver::storage_root()`).
|
||||
- `ServerSettings::from_layer` and `UserSettings::from_layer` build a defaulted layer once, accumulate errors from both their namespaces into one `Vec<ResolveError>`. Preserves today's "errors from BOTH namespaces" behavior — verify with existing tests in `tests/resolve_server.rs` and `tests/resolve_cli.rs`.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Today's `Resolver::server_into(&mut errors)` body shows the inline shape per namespace.
|
||||
- Today's `ServerSettings::from_layer` shows the dual-namespace error accumulation pattern.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: existing `tests/resolve_server.rs`, `tests/resolve_cli.rs`, `tests/resolve_run.rs`, `tests/resolve_workflow.rs`, `tests/resolve_project.rs`, `tests/resolve_features.rs`, `tests/defaults.rs`, `tests/resolve_root.rs` all pass without modification (proves no behavior change for any consumer).
|
||||
- Edge case: `ServerSettings::from_layer` with multiple errors *within* `server` (e.g. invalid `listen.address` AND invalid `ip_allowlist` CIDR — see existing fixture pattern in `tests/resolve_root.rs:22`) returns ALL errors in one `Err`. Proves the shared `errors` vec is threaded through. (`resolve_features` cannot emit errors per `lib/crates/fabro-config/src/resolve/features.rs:5`, so the "errors from both namespaces" pairing isn't constructible — within-namespace multi-error is the closest structural proof.)
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-config` clean.
|
||||
- `cargo nextest run -p fabro-config` green with no test changes.
|
||||
- `cargo nextest run -p fabro-config-tests` (if separate) or whatever test target covers `tests/` — green.
|
||||
- `grep -rn "Resolver\b" lib/crates/fabro-config/src` returns no hits except in deleted file.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 3: Migrate `create_run` to `WorkflowSettings`; add `storage_root` parameter; delete `ResolvedSettingsTree` + `resolve_settings_tree` + `combined_labels` free fn**
|
||||
|
||||
**Goal:** `create_run` consumes `WorkflowSettings` for workflow-owned config and `storage_root` from the caller for deployment-owned config. `WorkflowSettings::from_layer` failures keep today's `; `-joined `render_resolve_errors` format (R6). Storage-root interpolation failures move out to the HTTP handler with new error attribution (R5).
|
||||
|
||||
**Requirements:** R1, R5, R6, R7
|
||||
|
||||
**Dependencies:** Unit 1 (needs `WorkflowSettings`), Unit 2 (needs `Resolver` gone — though Unit 3 could technically land before Unit 2).
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/create.rs`
|
||||
- Add `storage_root: PathBuf` parameter to `pub async fn create(...)`.
|
||||
- Delete `struct ResolvedSettingsTree` (lines 63-68).
|
||||
- Delete `fn resolve_settings_tree` (lines 287-297).
|
||||
- Delete `fn combined_labels` (lines 299-304).
|
||||
- Replace `let resolved_settings = resolve_settings_tree(&settings)?;` (line 116) with `WorkflowSettings::from_layer(&settings).map_err(|errors| Error::Precondition(render_resolve_errors(&errors)))?`.
|
||||
- Replace lines 118-127 (today's storage_root resolution + Storage::new call): use the `storage_root` parameter directly. No more `InterpString::resolve(env)` here — caller did it.
|
||||
- Pass `settings` (unmodified) into `PersistCreateOptions`. **Do NOT overwrite `settings.server.storage.root`** — see Key Technical Decisions: persisted layer is the request-derived/materialized artifact (post-`materialize_run`); `record.run_dir` is the path-of-truth.
|
||||
- Replace `combined_labels(&resolved_settings)` (line 166) with `resolved_settings.combined_labels()`.
|
||||
- Imports: remove `Resolver` if directly imported; remove `HashMap` import if no longer used; add `PathBuf` if not already imported.
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs:4019` — production caller. Resolve `storage_root` from the live `ServerSettings` and map any interpolation failure to a transport error. **Do NOT use `state.server_storage_dir()`** — that helper panics on resolution failure (`server.rs:659`), which would replace today's `Error::Precondition` graceful-failure path with a process abort. The handler must do its own `resolve_interp_string` (or equivalent) and map errors to an `ApiError` shape used elsewhere in the file.
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/start.rs:1008,1190` — test helpers (`persisted_workflow` and the bundled-workflow test). Pass a temp dir or fixture path.
|
||||
- Audit and modify: any other callers of `fabro_workflow::operations::create::create()` in workspace tests. Run `grep -rn "operations::create(\|workflow::operations::create" lib/crates/fabro-workflow/tests/ lib/crates/fabro-server/tests/` during implementation.
|
||||
|
||||
**Approach:**
|
||||
- Production caller pattern (sketched — verify error constructor and locking shape during implementation):
|
||||
```
|
||||
// Read the live ServerSettings (Arc<ServerSettings>) and resolve env-var template
|
||||
let storage_root = match resolve_interp_string(&state.server_settings().server.storage.root) {
|
||||
Ok(s) => PathBuf::from(s),
|
||||
Err(e) => return ApiError::<chosen-shape>(format!("storage root: {e}")).into_response(),
|
||||
};
|
||||
let created = match Box::pin(operations::create(state.store.as_ref(), create_input, storage_root)).await { ... };
|
||||
```
|
||||
This preserves today's "interpolation failure becomes a graceful HTTP error" semantics. The exact `ApiError` constructor (e.g. `bad_request`, `internal`, or a new variant) is implementer's choice — pick whatever matches today's error shape for similar request-time validation failures in this file. `resolve_interp_string` already exists in the same module (used by `server_storage_dir`).
|
||||
- Test helpers can use `tempfile::tempdir()` or a hardcoded path; pass `tmp.path().to_path_buf()` (or similar) as the third argument.
|
||||
- `validate_sandbox_provider` at line 306 still uses `fabro_config::resolve_run_from_file(&resolved.settings)` — leave it. Different code path, same as today.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Today's `to_error` closure in `create.rs:289-290` for the `render_resolve_errors` mapping shape.
|
||||
- `Error::Precondition` is the established envelope for create-time settings failures.
|
||||
|
||||
**Behavior change in scope (limited to R7 signature change):**
|
||||
- `pub async fn create()` gains a `storage_root: PathBuf` parameter. Three production/test caller sites + workspace test audit.
|
||||
- **No new resolve-time validation surfaces.** The bundle now resolves only `project`/`workflow`/`run`, exactly as today's `ResolvedSettingsTree` did. Server-ops fields (`auth`, `listen`, `ip_allowlist`, `integrations`) are NOT touched by this PR; they remain owned by the live `ServerSettings`.
|
||||
- The InterpString env-var resolution that today happens inside `create()` (lines 119-126) moves to the caller. fabro-server today already has plenty of `InterpString::resolve` patterns to mirror.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: existing `create_run` tests (in `create.rs`'s `mod tests`, in `lib/crates/fabro-workflow/tests/`, in `lib/crates/fabro-server/tests/`) pass after caller updates.
|
||||
- Happy path: `combined_labels()` method produces the same map as today's free fn for the same fixture (proves ordering preservation).
|
||||
- Error path: `SettingsLayer` with malformed `run.sandbox.provider` causes `create_run` to fail with the expected `; `-joined message (proves R6 format preservation).
|
||||
- Edge case: caller passes a non-existent `storage_root` — `create_run` either creates the dir (matches today's behavior via `Storage::new`) or fails with the same error today's `Storage::new` would produce. Verify behavior is identical to today.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build -p fabro-workflow` clean.
|
||||
- `cargo build -p fabro-server` clean.
|
||||
- `cargo nextest run -p fabro-workflow` green.
|
||||
- `cargo nextest run -p fabro-server` green (HTTP handler still works end-to-end).
|
||||
- `grep -rn "ResolvedSettingsTree\|resolve_settings_tree" lib/` returns no hits.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 4: Workspace build + lint sweep**
|
||||
|
||||
**Goal:** Confirm no caller across the workspace still references deleted symbols.
|
||||
|
||||
**Requirements:** R5
|
||||
|
||||
**Dependencies:** Units 1-3.
|
||||
|
||||
**Files:** None modified directly; this unit is verification only.
|
||||
|
||||
**Approach:**
|
||||
- `cargo build --workspace` from repo root.
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` (per CLAUDE.md).
|
||||
- `cargo nextest run --workspace`.
|
||||
- `grep -rn "fabro_config::Resolver\|ResolvedSettingsTree\|resolve_settings_tree" lib/ apps/` returns no hits.
|
||||
- `cargo +nightly-2026-04-14 fmt --check --all`.
|
||||
|
||||
**Test expectation:** none — pure verification unit. No new test scenarios; existing tests must pass unchanged.
|
||||
|
||||
**Verification:**
|
||||
- All commands green.
|
||||
- No grep hits for deleted symbols.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** `create_run`'s signature gains a `storage_root: PathBuf` parameter. ~3 production/test callers updated to pass it. No new resolve-time validation runs anywhere — the bundle resolves the same namespaces today's `ResolvedSettingsTree` did.
|
||||
- **Error propagation:** `Server`/`UserSettings` error envelopes unchanged. `WorkflowSettings::from_layer` returns `Result<Self, Vec<ResolveError>>` (a new shape, asymmetric with the other two bundles); `create_run` formats it via `render_resolve_errors` to keep its user-visible error message format identical to today (`; `-joined). See R6. The InterpString-resolution error path that today lives inside `create_run` moves up to the caller — same error class, different attribution.
|
||||
- **State lifecycle risks:** None — pure refactor, no persistent state touched.
|
||||
- **API surface parity:** `fabro_config` public API loses `Resolver` (and the `*_into` methods accessible through it). Gains `pub struct WorkflowSettings`. All other re-exports unchanged. `render_resolve_errors` stays public (used by `create_run` and others). `fabro_workflow::operations::create::create()` signature changes (one new parameter).
|
||||
- **Integration coverage:** Existing tests in `lib/crates/fabro-config/tests/` exercise both single-namespace (`resolve_*_from_file`) and multi-namespace (`*Settings::from_layer`) paths; they cover the integration shape.
|
||||
- **Server-ops authority preserved:** No part of this PR re-resolves server-ops fields (`auth`, `listen`, `ip_allowlist`, `integrations`, `slatedb`, `logging`) per-request. The live `ServerSettings` (owned by `fabro-server` at boot) remains the single authority. `WorkflowSettings` doesn't pretend to hold them.
|
||||
- **Unchanged invariants:** `*Layer` and `*Namespace` types in `fabro-types` — untouched. `apply_builtin_defaults` + `defaults.toml` — untouched. Per-namespace `resolve_*` function bodies — untouched. Consumer field-access patterns (`ctx.user_settings().cli.output.verbosity`) — untouched. `Server`/`UserSettings::from_layer` signatures — untouched.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| `create_run` signature change misses a workspace test caller; build break | Audit step listed in Unit 3 Files (`grep -rn "operations::create("`). Compiler will catch all production paths. |
|
||||
| fabro-server's storage_root resolution call site fails with a new error class (env var missing, parse error) where today the failure happened inside `create_run` | Same error semantics; just attributed to the caller. Mention in PR description so reviewers don't read it as a regression. |
|
||||
| One extra `apply_builtin_defaults(layer.clone())` per bundle on the create path vs. shared-via-Resolver | Acceptable — `create_run` is human-paced. Not in any hot path. |
|
||||
| `combined_labels` method ordering subtly differs from free fn (both extend project → workflow → run) | Match today's free-fn ordering exactly. Existing tests will catch label-ordering regressions. |
|
||||
| Asymmetric `from_layer` return type (`Result<Self, Vec<ResolveError>>` for `Workflow`; `fabro_config::Result<Self>` for `Server`/`User`) reads as inconsistency | Documented as a Key Technical Decision; reason is preserving `create_run`'s error-message format. Future PR could converge all three when the format change is intentional. |
|
||||
| `record.settings.server.storage.root` (the request-derived/materialized artifact) and `record.run_dir` (where the run actually lives) can disagree — e.g. user submitted env-template `"{{ env.X }}"` that resolved at runtime to a different path than the parameter | Documented design (see Key Technical Decisions): persisted settings = request-derived/materialized artifact; `run_dir` = path-of-truth. Audit grep verifies no current consumer reads `settings.server.storage.root` from a persisted record beyond the line being removed. Future readers must use `run_dir` for paths. |
|
||||
| HTTP handler's storage-root resolution failure path differs from today's `Error::Precondition` text | Documented behavior change — moves from a workflow-side `Error::Precondition` to a transport-side `ApiError`. Same failure class (graceful HTTP error), different attribution and error-message text. Mention in PR description. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- No user-facing docs to update (internal refactor).
|
||||
- No migration scripts, feature flags, or rollout concerns.
|
||||
- One signature change: `fabro_workflow::operations::create::create()` gains `storage_root: PathBuf`. Three caller sites + workspace test audit. No resolved-settings semantics change.
|
||||
- Net code: ~150 lines deleted, ~50 added (smaller WorkflowSettings = smaller diff).
|
||||
|
||||
## Sources & References
|
||||
|
||||
- Origin: design conversation in this session.
|
||||
- Related code: `lib/crates/fabro-config/src/resolve/resolver.rs` (introduced commit 52d24531d).
|
||||
- Follow-up plan: `docs/plans/2026-04-23-002-refactor-combine-trait-uv-pattern-plan.md` (PR 2 — Combine trait + derive).
|
||||
|
|
@ -1,835 +0,0 @@
|
|||
---
|
||||
title: "refactor: CommandContext alignment at CLI command boundaries"
|
||||
type: refactor
|
||||
status: completed
|
||||
date: 2026-04-23
|
||||
deepened: 2026-04-23
|
||||
---
|
||||
|
||||
# CommandContext Alignment At CLI Command Boundaries
|
||||
|
||||
## Overview
|
||||
|
||||
Finish the partially landed `CommandContext` refactor in `fabro-cli` by
|
||||
making `CommandContext` the shared command-boundary abstraction for
|
||||
invocation plumbing in the CLI command families that already depend on
|
||||
it or immediately reconstruct it. The goal is to stop threading
|
||||
`&CliNamespace`, `&CliLayer`, `Printer`, and `process_local_json`
|
||||
through command entrypoints when that data is already part of the same
|
||||
invocation context.
|
||||
|
||||
This is a follow-on plan to the earlier server-access refactor. The
|
||||
current codebase already centralizes `cwd`, merged settings, and server
|
||||
access in `CommandContext`, but command entrypoints still receive raw
|
||||
plumbing and then rebuild a context locally. This plan aligns the
|
||||
surface area around the existing struct instead of introducing a second
|
||||
context or service wrapper.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
`CommandContext` exists today in
|
||||
`lib/crates/fabro-cli/src/command_context.rs`, and many commands
|
||||
already depend on it for `cwd`, `machine_settings`, `user_settings`, and
|
||||
`server()` access. The refactor is only half-finished:
|
||||
|
||||
- the `printer` field and `printer()` accessor are both marked
|
||||
`#[allow(dead_code, reason = "...still being wired through")]`
|
||||
- `main.rs` still passes raw plumbing into most command families
|
||||
- many command entrypoints still accept some combination of
|
||||
`&CliNamespace`, `&CliLayer`, `Printer`, and `process_local_json`
|
||||
- those same commands often construct `CommandContext` immediately
|
||||
inside the handler
|
||||
|
||||
That leaves the CLI with two overlapping models:
|
||||
|
||||
- `CommandContext` as the intended abstraction for shared invocation
|
||||
state
|
||||
- raw parameter threading as the de facto command API
|
||||
|
||||
The result is more churn on command signatures, more repeated output
|
||||
format and JSON-gating branches, and a dead-code-marked `printer` field
|
||||
that signals the abstraction boundary is unfinished.
|
||||
|
||||
The refactor needs to finish in a way that preserves current CLI
|
||||
behavior and avoids turning `CommandContext` into a new god object.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- **R1.** In-scope CLI command entrypoints use `CommandContext` as the
|
||||
shared invocation-plumbing abstraction instead of separately receiving
|
||||
`&CliNamespace`, `&CliLayer`, `Printer`, and `process_local_json`.
|
||||
- **R2.** `CommandContext` remains narrow: it carries invocation-scoped
|
||||
plumbing and shared derived state, not command-specific args, styles,
|
||||
or workflow-specific data.
|
||||
- **R3.** JSON output, verbosity behavior, printer routing, and global
|
||||
`--json` restrictions remain behaviorally unchanged for existing
|
||||
commands, including `auth status` remaining explicit-global-`--json`
|
||||
only rather than switching to persisted `cli.output.format = "json"`.
|
||||
- **R4.** Target-based and storage-dir-based server resolution semantics
|
||||
remain unchanged, including `CommandContext::server()` behavior and
|
||||
`ServerSummaryLookup::from_client(...)` usage.
|
||||
- **R5.** `main.rs` keeps its current pre-tracing bootstrap ordering for
|
||||
logging and upgrade checks; `CommandContext` begins after that phase.
|
||||
- **R6.** The current dead-code allowance on the `printer` field/accessor
|
||||
is removed by making printer access a real part of the abstraction, or
|
||||
by deleting redundant surface area if a narrower accessor is better.
|
||||
- **R7.** Representative unit and integration coverage exists for the
|
||||
context API, JSON/text output behavior, global `--json` gating, and
|
||||
target/connection-based command families touched by the refactor.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- **In scope:** command families in `fabro-cli` that already use
|
||||
`CommandContext` directly or immediately construct one from raw
|
||||
plumbing:
|
||||
`run`, `runs`, `artifact`, `store dump`, `preflight`, `validate`,
|
||||
`graph`, `model`, `secret`, `pr`, `repo`, `auth`, `provider`,
|
||||
`config`, `version`, `doctor`, `system`, and the public
|
||||
`sandbox preview` / `sandbox ssh` command boundary that currently
|
||||
forwards into `commands/run/*` leaf modules.
|
||||
- **In scope:** top-level dispatch cleanup in
|
||||
`lib/crates/fabro-cli/src/main.rs` and family dispatch modules where
|
||||
the only reason raw CLI plumbing is still passed down is command
|
||||
signature inertia.
|
||||
- **Out of scope:** `exec`, `server`, `install`, `upgrade`, `workflow`,
|
||||
`parse`, `render_graph`, hidden analytics/panic upload commands,
|
||||
hidden `run worker`, and `sandbox cp`, except for thin compile-only
|
||||
adapters if needed.
|
||||
- **Out of scope:** changing CLI text, response payloads, exit-code
|
||||
semantics, or server connection behavior beyond what is required to
|
||||
move the plumbing boundary.
|
||||
- **Out of scope:** moving `Styles` ownership into `CommandContext` or
|
||||
making low-level pure rendering helpers context-aware when explicit
|
||||
`Printer` or `Styles` parameters remain clearer.
|
||||
- **Out of scope:** redesigning `server_client.rs` connection semantics.
|
||||
This plan consumes the current `CommandContext::server()` model rather
|
||||
than reopening the earlier server-access design.
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code and Patterns
|
||||
|
||||
- `lib/crates/fabro-cli/src/command_context.rs` — current
|
||||
`CommandContext`, constructors, `user_settings()` / `machine_settings()`
|
||||
accessors, and dead-code-marked printer storage.
|
||||
- `lib/crates/fabro-cli/src/main.rs` — top-level command dispatch still
|
||||
passing raw plumbing into most families after bootstrap.
|
||||
- `lib/crates/fabro-cli/src/server_client.rs` — current target and
|
||||
storage-dir connection behavior that must stay unchanged.
|
||||
- `lib/crates/fabro-cli/src/commands/run/create.rs` — existing example
|
||||
of a helper that already takes `&CommandContext`.
|
||||
- `lib/crates/fabro-cli/src/commands/run/mod.rs` — current mixed model:
|
||||
some subcommands build a `CommandContext`, some still read raw
|
||||
`cli.output.format`, and `process_local_json` is already vestigial at
|
||||
this boundary.
|
||||
- `lib/crates/fabro-cli/src/commands/secret/mod.rs` — good family-level
|
||||
pattern where a single derived server/client can be shared across
|
||||
subcommands.
|
||||
- `lib/crates/fabro-cli/src/commands/pr/mod.rs` — representative mixed
|
||||
local/server family using both `CommandContext::base(...)` and
|
||||
`CommandContext::for_target(...)`.
|
||||
- `lib/crates/fabro-cli/src/commands/auth/mod.rs` and
|
||||
`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.
|
||||
- `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
|
||||
boundary for preview/ssh command dispatch; leaf implementation lives in
|
||||
`commands/run/preview.rs` and `commands/run/ssh.rs`, but the command
|
||||
family boundary is `sandbox`.
|
||||
- `lib/crates/fabro-cli/tests/it/cmd/sandbox_preview.rs` and
|
||||
`lib/crates/fabro-cli/tests/it/cmd/sandbox_ssh.rs` — existing
|
||||
command-owned coverage for those public entrypoints.
|
||||
|
||||
### Current-State Inventory
|
||||
|
||||
- `CommandContext::{base, for_target, for_connection}` currently has
|
||||
**42** call sites across **37** command files under
|
||||
`lib/crates/fabro-cli/src/commands`.
|
||||
- The command tree contains **one** existing helper that already accepts
|
||||
`&CommandContext` directly:
|
||||
`lib/crates/fabro-cli/src/commands/run/create.rs`.
|
||||
- The `printer()` accessor currently has no call sites, which is why the
|
||||
dead-code allowance still exists.
|
||||
- For in-scope command files, the dominant remaining use of raw
|
||||
`&CliNamespace` is reading `cli.output.format` or
|
||||
`cli.output.verbosity`; that is a signal that the data belongs on the
|
||||
shared invocation context rather than each command signature.
|
||||
- `process_local_json` is now concentrated in `auth`, `provider`,
|
||||
`graph`, `sandbox preview`, and `sandbox ssh`. That makes it a good
|
||||
candidate for a dedicated invocation-context field/helper instead of
|
||||
continued parameter threading.
|
||||
|
||||
### Related Context
|
||||
|
||||
- `docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md`
|
||||
— earlier plan that introduced the current `CommandContext` and server
|
||||
access model. This plan finishes the command-boundary alignment that
|
||||
document did not fully land.
|
||||
- `docs/plans/2026-04-22-001-refactor-settings-api-entrypoints-plan.md`
|
||||
— recent owner-first context plan that reinforces the repo preference
|
||||
for dense, owner-scoped context objects instead of repeated free-form
|
||||
plumbing.
|
||||
- `git log -- lib/crates/fabro-cli/src/command_context.rs` shows recent
|
||||
follow-on commits including `simplify: drop duplicate settings plumbing
|
||||
from cli/server refactor`, which is consistent with the current goal of
|
||||
collapsing overlapping command-boundary APIs.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
- No relevant `docs/solutions/` entries currently cover this seam.
|
||||
|
||||
### External References
|
||||
|
||||
- No external research used. The repo already has sufficient local
|
||||
context, existing partial implementation, and tests for this refactor.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
- **Use `CommandContext` as the command-boundary API for in-scope
|
||||
commands.**
|
||||
The abstraction already owns the hard parts: working directory,
|
||||
merged settings, and server access. The remaining refactor should move
|
||||
entrypoint APIs onto that abstraction instead of continuing to thread
|
||||
raw plumbing beside it.
|
||||
|
||||
- **Keep `CommandContext` narrow and invocation-scoped, not god-shaped.**
|
||||
It should own:
|
||||
`printer`, merged CLI-derived settings (`machine_settings`,
|
||||
`user_settings`), `cwd`, config-path context, server-derivation state,
|
||||
and the invocation-only global `--json` flag.
|
||||
It should not own command args, `Styles`, render-only helpers, or
|
||||
workflow/build-specific state.
|
||||
|
||||
- **Do not store or expose the full `CliNamespace` publicly.**
|
||||
Commands in scope only need a small subset of CLI plumbing:
|
||||
output format, output verbosity, and global `--json` restrictions.
|
||||
Output format and verbosity should come from
|
||||
`ctx.user_settings().cli.output`, which already reflects CLI override
|
||||
precedence through merged settings. The only truly extra invocation
|
||||
field is the global `--json` switch, which is not part of persisted
|
||||
settings and therefore belongs on the context explicitly.
|
||||
|
||||
- **Preserve the current error-timing split.**
|
||||
`CommandContext` construction should keep doing what it does today:
|
||||
capture cwd, load local settings, and build merged invocation state.
|
||||
Server-target resolution and server-connection failures should remain
|
||||
deferred to `ctx.server().await?` or existing explicit
|
||||
`resolve_server_target(...)` calls. The refactor should not make
|
||||
malformed target/server resolution errors eager at context-construction
|
||||
time.
|
||||
|
||||
- **Keep `auth status` as an explicit-global-JSON command.**
|
||||
Most in-scope commands should read output mode from
|
||||
`ctx.user_settings().cli.output`, but `auth status` is a special case:
|
||||
it currently emits JSON only for the explicit invocation-wide global
|
||||
`--json` path, not merely because resolved CLI settings say
|
||||
`output.format = json`. That distinction should remain intact, so the
|
||||
context needs both resolved output settings and a separate helper for
|
||||
the explicit global JSON flag.
|
||||
|
||||
- **Create a base invocation context once, then derive target/connection
|
||||
variants from it.**
|
||||
`main.rs` should keep using raw settings during pre-tracing bootstrap.
|
||||
After that, it should build a base `CommandContext` once for each
|
||||
in-scope dispatch path. Command families then derive
|
||||
target-based or connection-based contexts from that base without
|
||||
re-supplying `Printer` and `CliLayer`.
|
||||
|
||||
- **Allow private derivation state inside `CommandContext` if that is the
|
||||
simplest way to avoid raw parameter threading.**
|
||||
Storing a private `CliLayer` or equivalent internal builder state is
|
||||
acceptable if it enables methods like `with_target(...)` or
|
||||
`with_connection(...)` and keeps the raw plumbing hidden behind the
|
||||
abstraction boundary.
|
||||
|
||||
- **Keep render helpers explicit.**
|
||||
Command entrypoints and family dispatchers should align on
|
||||
`CommandContext`, but low-level helpers such as table rendering,
|
||||
summary formatting, and browser-opening routines may keep explicit
|
||||
`Printer` / `Styles` / boolean parameters where that stays simpler than
|
||||
threading the full context downward.
|
||||
|
||||
- **Keep workflow/manifest layer assembly command-local.**
|
||||
Commands such as `run`, `preflight`, `validate`, and `graph` should
|
||||
continue to build their workflow/project/manifests with the existing
|
||||
command-owned helpers. `CommandContext` can provide `cwd`, merged user
|
||||
settings for output behavior, and server access, but it should not
|
||||
absorb manifest-building policy or workflow-layer composition.
|
||||
|
||||
- **Migrate family-by-family with temporary compatibility wrappers if
|
||||
needed.**
|
||||
This is a cross-cutting refactor with wide signature churn. It is
|
||||
better to allow short-lived constructor/adapter overlap during the
|
||||
migration than to force a single giant all-or-nothing patch that is
|
||||
harder to validate.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Should this refactor introduce a second wrapper type such as
|
||||
`Services` or `InvocationContext`?**
|
||||
No. The repo already has a partially landed `CommandContext`, and the
|
||||
simplest aligned design is to finish that abstraction rather than
|
||||
splitting responsibilities across two overlapping context types.
|
||||
|
||||
- **Should `CommandContext` absorb the entire `CliNamespace`?**
|
||||
No. Public command consumers should read output mode and verbosity from
|
||||
`ctx.user_settings().cli.output`, while command-specific configuration
|
||||
stays local to the commands that own it.
|
||||
|
||||
- **Should `process_local_json` become part of `CommandContext`?**
|
||||
Yes. It is invocation-scoped, currently leaks across multiple command
|
||||
signatures, and is the one remaining piece of global command plumbing
|
||||
that is not already represented by merged settings.
|
||||
|
||||
- **Should preview/ssh be treated as `run` work or `sandbox` work in
|
||||
this plan?**
|
||||
Treat them as `sandbox` work at the public command boundary. The leaf
|
||||
implementation modules remain under `commands/run/*`, but the raw
|
||||
plumbing boundary in the current CLI is `commands/sandbox/mod.rs` and
|
||||
the plan should align to that boundary and its tests.
|
||||
|
||||
- **Should `auth status` remain “explicit global JSON only”?**
|
||||
Yes. R3 for this plan is behavioral preservation, and the current
|
||||
contract is that `auth status` emits JSON only when the explicit
|
||||
invocation-global `--json` switch is active.
|
||||
|
||||
- **Should `Styles` move into `CommandContext` in the same pass?**
|
||||
No. That would enlarge the abstraction without addressing the actual
|
||||
duplicated plumbing problem.
|
||||
|
||||
- **Should out-of-scope local commands be forced onto `CommandContext`
|
||||
just for uniformity?**
|
||||
No. This pass should target the families where `CommandContext` already
|
||||
provides real value or is already partially adopted.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Exact API names for derived contexts.**
|
||||
The implementation may settle on `with_target(...)`,
|
||||
`for_target_from(...)`, or similar naming. The important contract is
|
||||
that callers no longer pass raw `Printer` and `CliLayer` repeatedly.
|
||||
|
||||
- **Whether static constructors remain temporarily during migration.**
|
||||
If temporary wrappers reduce compile churn while family-by-family
|
||||
patches land, they are acceptable. Final cleanup should remove the
|
||||
now-redundant raw-plumbing entrypoints from in-scope call sites.
|
||||
|
||||
- **Whether `CommandContext` should be cheaply cloneable or should build
|
||||
derived variants from private state on demand.**
|
||||
Either is acceptable if it preserves the abstraction boundary and does
|
||||
not change runtime behavior.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*
|
||||
|
||||
| Boundary | Current shape | Target shape |
|
||||
|---|---|---|
|
||||
| `main.rs` -> command family | `dispatch(args, &cli_settings, &cli_layer, process_local_json, printer)` | `dispatch(args, &base_ctx)` |
|
||||
| family dispatch -> leaf command | raw CLI plumbing plus `CommandContext::for_target(...)` inside the leaf | derive `target_ctx` / `connection_ctx` once from `base_ctx`, then pass `&CommandContext` or already-resolved client/output helpers |
|
||||
| output mode lookup | `cli.output.format` / `cli.output.verbosity` | `ctx.user_settings().cli.output.*` |
|
||||
| global `--json` guard | separate `process_local_json` parameter | `ctx` accessor/helper |
|
||||
| printing | raw `printer` parameter | `ctx.printer()` or a narrower printer extracted from `ctx` |
|
||||
|
||||
Directional flow:
|
||||
|
||||
```text
|
||||
bootstrap raw globals/settings for tracing + upgrade check
|
||||
-> build base CommandContext once for the in-scope command dispatch
|
||||
-> family dispatch receives &base_ctx
|
||||
-> family derives:
|
||||
target_ctx from target args
|
||||
connection_ctx from storage-dir-aware args
|
||||
base/local ctx for settings-only commands
|
||||
-> leaf command reads:
|
||||
ctx.cwd()
|
||||
ctx.machine_settings()
|
||||
ctx.user_settings().cli.output.*
|
||||
ctx.require_no_json_override() or equivalent
|
||||
ctx.printer()
|
||||
ctx.server().await?
|
||||
-> render-only helpers stay explicit over Printer / Styles where simpler
|
||||
```
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Reframe `CommandContext` as the invocation-boundary object**
|
||||
|
||||
**Goal:** Make `CommandContext` capable of carrying the invocation
|
||||
plumbing that is still leaking through command signatures, while keeping
|
||||
the type narrowly scoped.
|
||||
|
||||
**Requirements:** R1, R2, R3, R4, R6
|
||||
|
||||
**Dependencies:** None
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/command_context.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs`
|
||||
- Test: `lib/crates/fabro-cli/src/command_context.rs`
|
||||
|
||||
**Approach:**
|
||||
- Add the remaining invocation-only plumbing that does not already exist
|
||||
on the context, specifically the global `--json` switch used today via
|
||||
`process_local_json`.
|
||||
- Make printer access part of the live API so the dead-code allowance on
|
||||
the `printer` field/accessor can be removed.
|
||||
- Add context-derivation methods that let callers obtain target-based or
|
||||
connection-based variants from a base invocation context without
|
||||
re-supplying raw `Printer` and `CliLayer`.
|
||||
- Keep output format and verbosity sourced from
|
||||
`ctx.user_settings().cli.output` rather than storing a second public
|
||||
output-format copy on the side, while still exposing the explicit
|
||||
invocation-global JSON flag separately for commands like `auth status`
|
||||
whose contract is not identical to resolved output format.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/command_context.rs`
|
||||
- `docs/plans/2026-04-22-001-refactor-settings-api-entrypoints-plan.md`
|
||||
for owner-first context boundaries
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: a base context exposes the same output format and verbosity
|
||||
that commands currently read from merged CLI settings.
|
||||
- Happy path: a base context preserves both resolved output settings and
|
||||
the explicit invocation-global JSON flag so commands can distinguish
|
||||
between “resolved output format is JSON” and “user passed global
|
||||
`--json`”.
|
||||
- Happy path: deriving a target-based context preserves printer/global
|
||||
JSON state and resolves server access through the existing
|
||||
`server_client::connect_server_with_settings(...)` path.
|
||||
- Edge case: deriving a connection-based context with a storage-dir
|
||||
override changes only the storage-backed settings path and preserves
|
||||
other invocation-scoped data.
|
||||
- Error path: settings-load failures tied to context construction still
|
||||
surface during context construction, while malformed target resolution
|
||||
remains deferred until `ctx.server().await?` or explicit
|
||||
`resolve_server_target(...)` calls.
|
||||
|
||||
**Verification:**
|
||||
- The `printer` field/accessor is no longer dead code.
|
||||
- There is one clear way to obtain a base context and derive
|
||||
target/connection variants without raw plumbing at the call site.
|
||||
- The context API makes the distinction between resolved output format
|
||||
and explicit global JSON invocation state unambiguous.
|
||||
|
||||
- [x] **Unit 2: Move `main.rs` and the run/preflight/graph/sandbox boundary to context-first dispatch**
|
||||
|
||||
**Goal:** Eliminate raw plumbing from the top-level dispatch path and the
|
||||
run-oriented command family plus the public `sandbox preview` /
|
||||
`sandbox ssh` boundary that already rely heavily on `CommandContext`.
|
||||
|
||||
**Requirements:** R1, R3, R4, R5, R6, R7
|
||||
|
||||
**Dependencies:** Unit 1
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/command.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/create.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/preview.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/ssh.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/sandbox/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/resume.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/rewind.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/fork.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/wait.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/diff.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/logs.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/run/cp.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/preflight.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/validate.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/graph.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/run.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/create.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/start.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/attach.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/diff.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/logs.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/preflight.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/validate.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/graph.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/sandbox_preview.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/sandbox_ssh.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/json_global.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/lifecycle.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/scenario/recovery.rs`
|
||||
|
||||
**Approach:**
|
||||
- Build a base `CommandContext` in `main.rs` only after the existing
|
||||
bootstrap phase completes.
|
||||
- Change the run-family and run-adjacent entrypoints to accept context
|
||||
instead of raw `cli` / `cli_layer` / `printer` bundles.
|
||||
- Replace direct reads of `cli.output.format` and
|
||||
`cli.output.verbosity` with `ctx.user_settings().cli.output.*`.
|
||||
- Replace direct `process_local_json` threading with a context helper
|
||||
for the small number of commands that still need it (`graph`,
|
||||
`commands/sandbox/mod.rs` for the public preview/ssh boundary).
|
||||
- Move the public `sandbox preview` / `sandbox ssh` dispatch boundary to
|
||||
the same context-first shape as the run-family boundary, while leaving
|
||||
the leaf implementation modules in `commands/run/*` if that remains
|
||||
the cleanest internal organization.
|
||||
- Keep `Styles` local to the leaf commands and keep `attach` / `start`
|
||||
client helpers narrow if broadening them adds no value.
|
||||
|
||||
**Execution note:** Start by preserving or expanding characterization
|
||||
coverage for JSON/text output and global `--json` gating before removing
|
||||
the old raw-plumbing signatures from these entrypoints.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/run/create.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/preflight.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/graph.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/sandbox/mod.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `fabro run --detach` still prints a bare run ID in text
|
||||
mode and the same JSON payload in JSON mode after output format moves
|
||||
behind `CommandContext`.
|
||||
- Happy path: `fabro run` / `resume` / `attach` still inherit verbose
|
||||
rendering from CLI output verbosity and preserve idle-sleep behavior.
|
||||
- Edge case: `fabro graph --json` without an explicit output file still
|
||||
rejects the global JSON override exactly as it does today.
|
||||
- Edge case: `fabro sandbox preview --open` still opens the browser only
|
||||
when global JSON mode is not active.
|
||||
- Edge case: `fabro sandbox ssh` still allows `--print` under global
|
||||
JSON mode but continues to reject the unsupported interactive
|
||||
combination.
|
||||
- Error path: `preflight` and `validate` continue to fail on validation
|
||||
errors with the same text-vs-JSON contract and exit behavior.
|
||||
- Integration: create -> start -> attach and resume/recovery flows still
|
||||
resolve targets, stream output, and summarize results through the same
|
||||
black-box CLI contracts.
|
||||
|
||||
**Verification:**
|
||||
- `main.rs` no longer passes the raw plumbing bundle into the run /
|
||||
preflight / validate / graph / sandbox preview-ssh boundary.
|
||||
- Those command boundaries obtain shared invocation data exclusively via
|
||||
`CommandContext`.
|
||||
|
||||
- [x] **Unit 3: Migrate runs/artifact/store families to context-first family dispatch**
|
||||
|
||||
**Goal:** Remove repeated target-context reconstruction from the command
|
||||
families that already build a target-based `CommandContext` immediately
|
||||
and mostly use raw CLI state only for output mode.
|
||||
|
||||
**Requirements:** R1, R3, R4, R6, R7
|
||||
|
||||
**Dependencies:** Units 1-2
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/list.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/archive.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/rm.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/runs/inspect.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/artifact/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/artifact/list.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/artifact/cp.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/store/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/store/dump.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/archive.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/inspect.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/rm.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/artifact_list.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/artifact_cp.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/store_dump.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/store.rs`
|
||||
|
||||
**Approach:**
|
||||
- Have each family receive a context-first boundary and derive its
|
||||
target-based command context once, close to the namespace/selector
|
||||
boundary.
|
||||
- Switch output-mode branches to
|
||||
`ctx.user_settings().cli.output.format`.
|
||||
- Preserve existing client-sharing patterns such as
|
||||
`ServerSummaryLookup::from_client(ctx.server().await?)`.
|
||||
- Keep leaf helpers narrow where they already only need a resolved
|
||||
client, resolved run ID, or printer.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/secret/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/artifact/mod.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `runs list`, `archive`, `unarchive`, and `rm` still render
|
||||
the same JSON and text shapes after output-mode decisions move behind
|
||||
the context.
|
||||
- Happy path: `runs inspect` remains a JSON-only projection of server
|
||||
state and still resolves the selected run before fetching the state.
|
||||
- Edge case: “no runs found” and “no artifacts found” text-mode messages
|
||||
remain unchanged.
|
||||
- Error path: ambiguous or missing run selectors still fail through the
|
||||
existing server/client resolution path.
|
||||
- Integration: artifact listing/copy and store dump continue to hit the
|
||||
same server-backed data path and respect output-format selection.
|
||||
|
||||
**Verification:**
|
||||
- These family dispatchers no longer need separate `cli_layer` and
|
||||
`printer` arguments merely to reconstruct a target context.
|
||||
|
||||
- [x] **Unit 4: Migrate PR, secret, and system command families**
|
||||
|
||||
**Goal:** Align the families that mix local settings, target-based
|
||||
server access, and storage-dir-aware server access onto the same
|
||||
context-first boundary.
|
||||
|
||||
**Requirements:** R1, R3, R4, R6, R7
|
||||
|
||||
**Dependencies:** Units 1-3
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/list.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/create.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/view.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/merge.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/close.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/secret/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/secret/list.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/secret/set.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/secret/rm.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/system/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/system/info.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/system/df.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/system/events.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/system/prune.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/pr.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/pr_list.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/pr_create.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/pr_view.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/pr_merge.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/pr_close.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/secret.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/secret_list.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/secret_set.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/secret_rm.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/system.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/system_info.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/system_df.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/system_events.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/system_prune.rs`
|
||||
|
||||
**Approach:**
|
||||
- Keep `pr`’s split between base-settings work and target-based run
|
||||
lookup, but move both sides onto a common context-first boundary so
|
||||
raw `cli_layer` / `printer` threading disappears from the family API.
|
||||
- Preserve `secret`’s existing pattern of resolving the server once at
|
||||
the family boundary and passing the client into subcommands.
|
||||
- For `system`, derive connection-aware contexts from the base
|
||||
invocation context so storage-dir override behavior remains explicit
|
||||
and unchanged.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/pr/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/secret/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/system/mod.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: PR list/view/create/merge/close continue to render the same
|
||||
JSON/text contracts and still resolve GitHub credentials from merged
|
||||
local settings.
|
||||
- Happy path: secret list/set/rm continue to resolve one server client at
|
||||
the namespace boundary and honor JSON mode.
|
||||
- Happy path: system info/df/events/prune continue to use
|
||||
storage-dir-aware connection mode where appropriate.
|
||||
- Edge case: missing secret / no matching runs-to-prune / empty PR list
|
||||
still produce the same user-visible text-mode outcomes.
|
||||
- Error path: invalid storage-dir or connection resolution still fails
|
||||
before the command attempts remote work.
|
||||
- Integration: the `system` family continues to respect explicit
|
||||
`--storage-dir` overrides and local daemon resolution semantics.
|
||||
|
||||
**Verification:**
|
||||
- These family boundaries no longer accept raw plumbing bundles when the
|
||||
only reason was to build a `CommandContext` or inspect output mode.
|
||||
|
||||
- [x] **Unit 5: Finish remaining base/target context users**
|
||||
|
||||
**Goal:** Complete the context-first migration for the remaining in-scope
|
||||
command surfaces that already use `CommandContext` but still expose raw
|
||||
plumbing at their entrypoints.
|
||||
|
||||
**Requirements:** R1, R2, R3, R5, R6, R7
|
||||
|
||||
**Dependencies:** Units 1-4
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/model.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/repo/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/repo/init.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/repo/deinit.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/login.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/logout.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/auth/status.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/provider/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/provider/login.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/config/mod.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/version.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/doctor.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/model.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/model_list.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/model_test.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/repo.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/repo_init.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/repo_deinit.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/auth.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/provider.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/provider_login.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/config.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/version.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/doctor.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/json_global.rs`
|
||||
|
||||
**Approach:**
|
||||
- Move base-context-only command families (`auth`, `provider`, parts of
|
||||
`repo`) onto `CommandContext` so JSON gating and printer usage come
|
||||
from the shared invocation object.
|
||||
- Use `ctx.machine_settings()` / `ctx.user_settings()` consistently for
|
||||
local settings lookups rather than parallel raw-CLI arguments.
|
||||
- Preserve the special-case JSON contract for `auth status`: explicit
|
||||
invocation-global `--json` remains the only JSON trigger, even if
|
||||
resolved CLI settings say `output.format = json`.
|
||||
- Keep `repo deinit` and similar pure-local leaf helpers narrow if a
|
||||
derived `json_output` boolean or `Printer` extracted from the context
|
||||
keeps the internal helper clearer than passing the full context.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `lib/crates/fabro-cli/src/commands/auth/login.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/auth/status.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/config/mod.rs`
|
||||
- `lib/crates/fabro-cli/src/commands/version.rs`
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `auth status` and `provider login` preserve global `--json`
|
||||
restrictions and still resolve the intended server target from merged
|
||||
settings.
|
||||
- Happy path: `config`, `version`, `model`, and `doctor` continue to
|
||||
honor text-vs-JSON output without a direct `CliNamespace` parameter.
|
||||
- Edge case: persisted `cli.output.format = "json"` without explicit
|
||||
global `--json` still leaves `auth status` on its current text-mode
|
||||
path.
|
||||
- Edge case: explicit global `--json` still forces `auth status` onto
|
||||
its JSON output path even though the implementation no longer receives
|
||||
a raw `process_local_json` parameter.
|
||||
- Edge case: `repo init` non-JSON progress output and JSON result
|
||||
payloads stay unchanged.
|
||||
- Edge case: `repo deinit` still stays local and does not accidentally
|
||||
require server access just because the family boundary now uses
|
||||
`CommandContext`.
|
||||
- Error path: missing auth sessions, invalid server targets, and missing
|
||||
GitHub access continue to fail with the same user-facing contract.
|
||||
|
||||
**Verification:**
|
||||
- Remaining in-scope command entrypoints no longer expose the raw
|
||||
plumbing bundle as part of their public internal API.
|
||||
|
||||
- [x] **Unit 6: Remove migration scaffolding and prove the boundary is clean**
|
||||
|
||||
**Goal:** Delete transitional surface area and confirm the in-scope
|
||||
command tree is consistently aligned on `CommandContext`.
|
||||
|
||||
**Requirements:** R1, R2, R6, R7
|
||||
|
||||
**Dependencies:** Units 1-5
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-cli/src/command_context.rs`
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs`
|
||||
- Modify: in-scope command modules touched by transitional wrappers
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/top_level.rs`
|
||||
- Test: `lib/crates/fabro-cli/tests/it/cmd/json_global.rs`
|
||||
|
||||
**Approach:**
|
||||
- Remove temporary wrappers or compatibility constructors that were only
|
||||
present to get through the migration.
|
||||
- Delete stale comments and “still being wired through” dead-code
|
||||
annotations once the boundary is real.
|
||||
- Do a final sweep to ensure in-scope command boundaries are not still
|
||||
taking `&CliNamespace`, `&CliLayer`, `Printer`, and
|
||||
`process_local_json` together out of habit.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Keep cleanup limited to true scaffolding removal; do not reopen command
|
||||
semantics or formatting behavior in the cleanup pass.
|
||||
|
||||
**Test scenarios:**
|
||||
- Test expectation: none -- cleanup-only unit. Behavioral coverage should
|
||||
already exist from Units 1-5.
|
||||
|
||||
**Verification:**
|
||||
- The command-boundary API is visibly simpler and consistent across the
|
||||
in-scope families.
|
||||
- No in-scope command still looks half-migrated.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** `main.rs` bootstrap -> base `CommandContext` ->
|
||||
family dispatchers -> derived target/connection contexts ->
|
||||
`server_client.rs` / `user_config.rs`. This touches nearly every
|
||||
user-facing CLI family that already talks to settings or server
|
||||
resolution.
|
||||
- **Error propagation:** context-construction failures remain early and
|
||||
synchronous at the command boundary; server access errors still flow
|
||||
through `ctx.server().await?` and should not move deeper into render
|
||||
helpers.
|
||||
- **State lifecycle risks:** the biggest correctness risk is accidental
|
||||
reuse of the wrong derived context, especially storage-dir-aware
|
||||
contexts in the `system` family and target-based contexts in run/PR
|
||||
flows.
|
||||
- **API surface parity:** although this is an internal refactor, it
|
||||
touches external CLI contracts indirectly through JSON/text output,
|
||||
verbosity, global `--json` restrictions, and server-target resolution.
|
||||
- **Integration coverage:** black-box command tests and scenario tests
|
||||
are the main safety net. Unit tests should only cover context
|
||||
construction/derivation and not replace CLI integration coverage.
|
||||
- **Unchanged invariants:** tracing and upgrade bootstrap ordering stays
|
||||
in `main.rs`; `exec` keeps its distinct direct-provider path; server
|
||||
connection semantics stay in `server_client.rs`; `Styles` remain
|
||||
command-local.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| Output-mode drift when replacing `cli.output.format` reads with `ctx.user_settings().cli.output.format` | Keep characterization coverage in existing `cmd/*` tests for both text and JSON paths before deleting the raw parameters |
|
||||
| Global `--json` behavior changes while moving `process_local_json` into the context | Add targeted coverage in `json_global.rs`, `auth.rs`, `provider_login.rs`, `graph.rs`, and sandbox preview/ssh command tests |
|
||||
| Storage-dir-aware system commands accidentally derive a target-mode context instead of a connection-mode context | Keep connection-specific derivation explicit and cover `system_info`, `system_df`, `system_events`, and `system_prune` with CLI integration tests |
|
||||
| `CommandContext` grows into a second god object | Keep explicit scope rules: invocation plumbing only, no command args, no `Styles`, no feature-specific render state |
|
||||
| The refactor becomes a giant compile-fix patch with poor reviewability | Land the work family-by-family with temporary compatibility wrappers where needed, and verify each family with its existing tests before cleanup |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- No user-facing documentation changes are expected.
|
||||
- Internal comments in `command_context.rs` and nearby command modules
|
||||
should be updated to describe the final boundary, not the transitional
|
||||
“still being wired through” state.
|
||||
- The earlier April 8 plan should remain as historical context; this plan
|
||||
supersedes it for the command-boundary alignment work.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- Prior plan: `docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md`
|
||||
- Related plan: `docs/plans/2026-04-22-001-refactor-settings-api-entrypoints-plan.md`
|
||||
- Related code:
|
||||
`lib/crates/fabro-cli/src/command_context.rs`
|
||||
`lib/crates/fabro-cli/src/main.rs`
|
||||
`lib/crates/fabro-cli/src/server_client.rs`
|
||||
`lib/crates/fabro-cli/src/commands/run/mod.rs`
|
||||
`lib/crates/fabro-cli/src/commands/pr/mod.rs`
|
||||
`lib/crates/fabro-cli/src/commands/secret/mod.rs`
|
||||
`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: `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`
|
||||
`4b30a5f16 refactor(cli): route command output through Printer`
|
||||
|
|
@ -1,339 +0,0 @@
|
|||
---
|
||||
title: "refactor: replace merge.rs with Combine trait + derive (uv pattern)"
|
||||
type: refactor
|
||||
status: completed
|
||||
date: 2026-04-23
|
||||
sequence_after: 2026-04-23-001-refactor-collapse-settings-resolve-indirection-plan.md
|
||||
---
|
||||
|
||||
# refactor: replace merge.rs with Combine trait + derive (uv pattern)
|
||||
|
||||
## For the engineer picking this up
|
||||
|
||||
This is the second of two related settings-architecture refactors. PR 1 (`docs/plans/2026-04-23-001-...`) collapses the resolve-indirection layer (`Resolver`, `ResolvedSettingsTree`, `*_into` methods). PR 2 — this one — replaces the 750-line hand-rolled `merge.rs` with a small `Combine` trait, a dumb derive macro, and a handful of newtypes. Land PR 1 first; the two are orthogonal but PR 1 is smaller and lower-risk.
|
||||
|
||||
The pattern is lifted directly from astral-sh/uv. The user's reference is `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-settings/src/combine.rs` and `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-macros/src/lib.rs` — read both before starting. They're short.
|
||||
|
||||
## Overview
|
||||
|
||||
`lib/crates/fabro-config/src/merge.rs` contains 42 hand-rolled `combine_*` functions implementing the v2 settings-merge matrix. Most are mechanical "field: higher.x.or(lower.x)" boilerplate. Replace them with:
|
||||
|
||||
1. A `Combine` trait in `fabro-types` (single `fn combine(self, other: Self) -> Self` method).
|
||||
2. A dumb `#[derive(Combine)]` proc-macro in the existing `fabro-macros` crate that emits `Self { f: self.f.combine(other.f), ... }` field-by-field. ~25 lines.
|
||||
3. Concrete `impl Combine` blocks for `Option<leaf>` types (`Option<String>`, `Option<u64>`, option-wrapped settings enums, etc.). Most are one-liners (`self.or(other)`).
|
||||
4. A generic `impl<T: Combine> Combine for Option<T>` for recursive optional subtables only.
|
||||
5. Newtypes for strategy-bearing collection fields (`ReplaceMap`, `StickyMap`, `MergeMap`, plus exact Vec impls or list newtypes where needed).
|
||||
6. Bespoke `impl Combine` on irregular cases (hooks, splices, whole-replace structs).
|
||||
|
||||
Every merge-participating settings type gets a `Combine` impl. Field-merge structs can derive it. Whole-replace structs and special collection cases must implement it manually. `merge.rs` deletes entirely after its tests are moved.
|
||||
|
||||
## Why this matters (don't skip — it's load-bearing)
|
||||
|
||||
I (the previous engineer / Claude) initially recommended AGAINST a derive macro because attribute-driven derives hide the merge matrix behind macro expansion. **uv's pattern sidesteps this by encoding the rule in the type, not in attributes.** The derive is dead-stupid — it dispatches to `field.combine(other.field)` and that's it. The intelligence lives one level down in `impl Combine` for each field type. The merge matrix is auditable in one file (`combine.rs`) with one stanza per field strategy, and the type system enforces it: you can't accidentally use the wrong merge strategy for a map because `ReplaceMap`, `StickyMap`, and `MergeMap` are different types.
|
||||
|
||||
If you're tempted to add `#[combine(strategy = "...")]` attributes — DON'T. That defeats the entire point. If a field needs a custom rule, it gets a newtype.
|
||||
|
||||
## Reference: how uv does it
|
||||
|
||||
Read these in order:
|
||||
|
||||
1. `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-macros/src/lib.rs` lines 17-52 — the entire derive macro.
|
||||
2. `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-settings/src/combine.rs` — the trait, the `impl_combine_or!` macro for one-line `self.or(other)` impls, and the bespoke struct impls. Read uv's collection impls for context, but do not copy them blindly; Fabro's collection fields need the explicit strategy rules below.
|
||||
3. `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-settings/src/settings.rs` — search for `#[derive(...Combine...)]` to see how it's applied to the `*Options` structs.
|
||||
|
||||
The whole pattern is small — under 400 lines including the derive crate.
|
||||
|
||||
## Fabro-specific wrinkle: collection strategy lives in field types
|
||||
|
||||
uv's pattern works cleanly because every field type is structurally distinct. Fabro currently has multiple bare collection fields whose merge strategy depends on the field, not the Rust type. Do not add a blanket `Combine` impl for `HashMap` or `Vec`; make strategy visible in the field type instead.
|
||||
|
||||
| Field | Type today | Today's `merge.rs` rule | New field type |
|
||||
|-------|------------|-------------------------|----------------|
|
||||
| `project.metadata`, `workflow.metadata`, `run.metadata` | `HashMap<String, String>` | replace whole map if higher/self is non-empty (`merge_string_map_replace`) | `ReplaceMap<String>` |
|
||||
| `run.sandbox.env` | `HashMap<String, InterpString>` | sticky-by-key (`merge_string_map_sticky`) | `StickyMap<InterpString>` |
|
||||
| `daytona.labels` | `HashMap<String, String>` | sticky-by-key (`merge_string_map_sticky`) | `StickyMap<String>` |
|
||||
| `run.agent.mcps`, `cli.exec.agent.mcps` | `HashMap<String, McpEntryLayer>` | sticky-by-key; higher/self replaces the whole entry for the same key | `StickyMap<McpEntryLayer>` |
|
||||
| `server.integrations.github.permissions` | `HashMap<String, InterpString>` | sticky-by-key | `StickyMap<InterpString>` |
|
||||
| `run.notifications` | `HashMap<String, NotificationRouteLayer>` | per-key recursive combine | `MergeMap<NotificationRouteLayer>` |
|
||||
|
||||
To use uv's "rule lives in the type" pattern, introduce these newtypes in `lib/crates/fabro-types/src/settings/`:
|
||||
|
||||
```
|
||||
#[serde(transparent)]
|
||||
pub struct ReplaceMap<V>(pub HashMap<String, V>);
|
||||
|
||||
#[serde(transparent)]
|
||||
pub struct StickyMap<V>(pub HashMap<String, V>);
|
||||
|
||||
#[serde(transparent)]
|
||||
pub struct MergeMap<V>(pub HashMap<String, V>);
|
||||
```
|
||||
|
||||
And impl `Combine` for each. Field declarations in the layer types now document the rule:
|
||||
|
||||
```
|
||||
pub struct ProjectLayer {
|
||||
pub metadata: ReplaceMap<String>, // visibly "replace whole"
|
||||
// ...
|
||||
}
|
||||
pub struct RunSandboxLayer {
|
||||
pub env: StickyMap<InterpString>, // visibly "sticky-by-key"
|
||||
// ...
|
||||
}
|
||||
pub struct RunLayer {
|
||||
pub notifications: MergeMap<NotificationRouteLayer>, // visibly "per-key recursive"
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
This is a strict ergonomic improvement: today you have to grep `merge.rs` to find out how `metadata` merges; after, the field type tells you.
|
||||
|
||||
**Migration consideration:** these newtypes need careful serde handling. Use bare newtypes, not `Option<...>`, for fields that are bare `HashMap` today. The existing schema treats "absent" and "present but empty" as the same default empty map, and `merge.rs` falls back when the higher map is empty. Preserve that behavior with `#[serde(default, skip_serializing_if = "ReplaceMap::is_empty")]` / equivalent helpers. Verify with the existing `tests/parse_*` tests in `fabro-config` and add new round-trip tests.
|
||||
|
||||
## Irregular cases (hand-written `impl Combine`)
|
||||
|
||||
These don't fit the derive pattern. Each gets a bespoke `impl Combine` on its own type. Look at `merge.rs` for current behavior:
|
||||
|
||||
| Type | Current fn | New shape |
|
||||
|------|-----------|-----------|
|
||||
| `Vec<HookEntry>` | `combine_hooks` | exact `impl Combine for Vec<HookEntry>` or `HookList` newtype — ordered merge with optional `id` replacement |
|
||||
| `Vec<ModelRefOrSplice>` | `splice_model_fallbacks` | exact `impl Combine for Vec<ModelRefOrSplice>` or `ModelFallbackList` newtype — splice with `Splice` sentinel |
|
||||
| `Vec<StringOrSplice>` (events) | `splice_events` | exact `impl Combine for Vec<StringOrSplice>` or `EventList` newtype — splice variant |
|
||||
| `RunPrepareLayer` | `combine_run_prepare` (returns `higher` whole) | `impl Combine for RunPrepareLayer { fn combine(self, _other) = self }` |
|
||||
| `CliTargetLayer` | `combine_cli_target` (returns `higher` whole) | same shape as above |
|
||||
| `ServerListenLayer` | `combine_listen` (returns `higher` whole) | same shape as above |
|
||||
| `FeaturesLayer` | top-level `replace_if_some` | `impl Combine for FeaturesLayer { fn combine(self, _other) = self }` |
|
||||
| `RunArtifactsLayer` | `replace_if_some` | whole-replace `impl Combine` returning `self` |
|
||||
| `RunCheckpointLayer.exclude_globs` | guards "if higher empty, take lower" | hand-written `impl Combine for RunCheckpointLayer` that returns `self` when `self.exclude_globs` is non-empty, else `other` |
|
||||
| `Option<...>` fields currently merged with `higher.x.or(lower.x)` | one-line whole replacement | either concrete `impl Combine for Option<Leaf>` or an inner `impl Combine for Leaf` returning `self` |
|
||||
| `MergeMap<NotificationRouteLayer>` | `combine_notifications` (per-key recursive combine) | `impl<V: Combine> Combine for MergeMap<V>` |
|
||||
| `StickyMap<McpEntryLayer>` | `merge_string_map_sticky` | per-key sticky replacement, not recursive field merge |
|
||||
|
||||
Do not add a blanket `impl<T> Combine for Vec<T>`. Exact Vec impls are allowed only for the concrete special cases above. If an exact impl starts to collide with an option/list strategy, use a newtype instead.
|
||||
|
||||
## Convention to pick: argument order / which side wins
|
||||
|
||||
uv uses `self.combine(other)` where **`self` wins** (self is the higher-precedence layer). Fabro's current `merge.rs` uses `combine_files(lower, higher)` where **higher (the second arg) wins**. Pick one and stick with it.
|
||||
|
||||
Recommendation: adopt uv's "self wins" convention. It reads naturally — `user_settings.combine(defaults)` = "user settings, with defaults as fallback." For multi-layer stacking: `workspace.combine(user).combine(defaults)` gives `workspace > user > defaults`.
|
||||
|
||||
This means `apply_builtin_defaults` becomes:
|
||||
|
||||
```
|
||||
pub fn apply_builtin_defaults(layer: SettingsLayer) -> SettingsLayer {
|
||||
layer.combine(defaults_layer().clone())
|
||||
}
|
||||
```
|
||||
|
||||
And the existing `combine_files(lower, higher)` callers need their argument order swapped.
|
||||
|
||||
## Core coherence rules
|
||||
|
||||
These rules are mandatory. They avoid the compile-time and behavior traps that a naive port from uv would introduce in Fabro.
|
||||
|
||||
1. `Combine` lives in `fabro-types`, because the settings layer structs live in `fabro-types` and `fabro-config` already depends on `fabro-types`. Putting the trait in `fabro-config` would create a dependency cycle.
|
||||
2. The derive macro lives in the existing `fabro-macros` proc-macro crate. `fabro-types` already depends on `fabro-macros`, so do not create a new `fabro-config-macros` crate.
|
||||
3. Do not implement `Combine` for scalar inner types like `String`, `bool`, `InterpString`, or settings enums. Implement `Combine` for `Option<String>`, `Option<bool>`, `Option<InterpString>`, `Option<RunMode>`, etc. This lets `impl<T: Combine> Combine for Option<T>` coexist with concrete scalar option impls.
|
||||
4. `impl<T: Combine> Combine for Option<T>` is for recursive optional subtables only. It preserves whole-replace behavior only when the inner type's `Combine` impl returns `self`.
|
||||
5. Do not derive `Combine` for a type just because it is a `*Layer`. Derive only when the current `merge.rs` behavior is field-by-field merge. If current behavior is `higher.or(lower)` or `replace_if_some`, the inner type needs a whole-replace `Combine` impl returning `self`.
|
||||
6. Do not implement blanket `Combine` for `Vec<T>` or `HashMap<K, V>`. Use exact impls or strategy newtypes.
|
||||
|
||||
## Implementation Units
|
||||
|
||||
- [x] **Unit 1: Add `Combine` trait + option leaf impls in `fabro-types`**
|
||||
|
||||
**Goal:** Lay down the trait infrastructure with no derive yet.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-types/src/settings/combine.rs`
|
||||
- Modify: `lib/crates/fabro-types/src/settings/mod.rs` (add `mod combine; pub use combine::Combine;`)
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs` if desired to re-export `settings::Combine` at the crate root.
|
||||
|
||||
**Approach:**
|
||||
- Copy uv's trait shape verbatim. Convention: `self` wins.
|
||||
- Add `impl<T: Combine> Combine for Option<T>` for recursive optional subtables:
|
||||
```
|
||||
match (self, other) {
|
||||
(Some(this), Some(fallback)) => Some(this.combine(fallback)),
|
||||
(this, fallback) => this.or(fallback),
|
||||
}
|
||||
```
|
||||
- Add an `impl_combine_or_option!` macro for one-line whole-replace option leaves. List every leaf scalar/enum used in `*Layer` types as `Option<T>` impls: `Option<String>`, `Option<bool>`, numeric options, `Option<InterpString>`, `Option<RunMode>`, `Option<ApprovalMode>`, `Option<ObjectStoreProvider>`, `Option<WebhookStrategy>`, `Option<ServerAuthMethod>` where applicable, etc. Grep `lib/crates/fabro-types/src/settings/` for the full list.
|
||||
- Add concrete whole-replace option impls for composite leaves that should not recursively merge, such as `Option<HashMap<String, toml::Value>>` for `run.inputs` and any `Option<Vec<...>>` fields that remain bare vectors after Unit 3.
|
||||
- Do **not** implement `Combine` for scalar inner types (`String`, `bool`, `InterpString`, enums). If `String: Combine` exists, it conflicts with `impl Combine for Option<String>`.
|
||||
- Do **not** implement blanket `Combine` for `Vec<T>` or `HashMap<K, V>`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `Some("a").combine(Some("b")) == Some("a")`.
|
||||
- Happy path: `None.combine(Some("a")) == Some("a")`.
|
||||
- Edge case: `Some("a").combine(None) == Some("a")`.
|
||||
- Recursive option: `Some(FieldMergeLayer { a: Some(1), b: None }).combine(Some(FieldMergeLayer { a: Some(2), b: Some(3) }))` preserves `a = 1` and inherits `b = 3`.
|
||||
- Whole-replace option: `Some(WholeReplaceLayer { a: Some(1), b: None }).combine(Some(WholeReplaceLayer { a: Some(2), b: Some(3) }))` returns the `self` layer without inheriting `b`.
|
||||
- Each option leaf type gets at least one assertion proving `self.or(other)` semantics.
|
||||
|
||||
**Verification:** `cargo build -p fabro-types` clean. New unit tests pass.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 2: Add `#[derive(Combine)]` to the existing `fabro-macros` crate**
|
||||
|
||||
**Goal:** The dumb derive macro.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-macros/src/lib.rs`
|
||||
- Modify: `lib/crates/fabro-types/src/lib.rs` or `lib/crates/fabro-types/src/settings/mod.rs` to re-export the derive if that keeps call sites simple.
|
||||
|
||||
**Approach:**
|
||||
- Copy uv's `derive_combine` verbatim from `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-macros/src/lib.rs:17-52`.
|
||||
- The derive emits `Self { f1: self.f1.combine(other.f1), ... }` for named fields. Unnamed fields / enums: `unimplemented!()` (uv does the same; we don't need them).
|
||||
- The derive may reference `crate::settings::Combine` or `crate::Combine`; if using `crate::Combine`, re-export the trait at the `fabro-types` crate root first. This works because the derive output expands inside `fabro-types`, where the layer structs live.
|
||||
- Do not derive `Combine` in `fabro-config`; `fabro-config` is the consumer of the combined settings tree, not the owner of the layer types.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: a small struct `#[derive(Combine)] struct Foo { a: Option<u32>, b: Option<String> }` produces a working `Combine` impl. Proven by a unit test that asserts `Foo { a: Some(1), b: None }.combine(Foo { a: Some(2), b: Some("x".into()) }) == Foo { a: Some(1), b: Some("x".into()) }`.
|
||||
- Integration: nested struct with an `Option<InnerStruct>` field combines recursively.
|
||||
- Whole-replace integration: nested struct with an `Option<WholeReplaceStruct>` field does not inherit fields when both sides are `Some`.
|
||||
|
||||
**Verification:** `cargo build -p fabro-macros` and `cargo build -p fabro-types` clean. Derive test passes.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 3: Introduce collection strategy newtypes and migrate strategy-bearing maps**
|
||||
|
||||
**Goal:** Move map merge rules into the type system.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-types/src/settings/maps.rs` (or extend existing module)
|
||||
- Modify: `lib/crates/fabro-types/src/settings/mod.rs` to export the newtypes
|
||||
- Modify: `lib/crates/fabro-types/src/settings/combine.rs` or `maps.rs` to add `impl Combine for ReplaceMap<V>`, `StickyMap<V>`, and `MergeMap<V>`.
|
||||
- Modify field declarations in `lib/crates/fabro-types/src/settings/{project,workflow,run,cli,server}.rs`:
|
||||
- `project.metadata`, `workflow.metadata`, `run.metadata` -> `ReplaceMap<String>`
|
||||
- `run.sandbox.env` -> `StickyMap<InterpString>`
|
||||
- `daytona.labels` -> `StickyMap<String>`
|
||||
- `run.agent.mcps`, `cli.exec.agent.mcps` -> `StickyMap<McpEntryLayer>`
|
||||
- `server.integrations.github.permissions` -> `StickyMap<InterpString>`
|
||||
- `run.notifications` -> `MergeMap<NotificationRouteLayer>`
|
||||
- Audit every consumer of these fields. They currently access `HashMap` directly; with newtypes they'll need `.0`, `Deref`, iterator helpers, or explicit conversion at resolve boundaries.
|
||||
|
||||
**Approach:**
|
||||
- `#[serde(transparent)]` on the newtype.
|
||||
- Implement `Deref<Target = HashMap<String, V>>`, `DerefMut`, `From<HashMap<String, V>>`, and `IntoIterator` as needed so existing read-side consumers keep working without churn.
|
||||
- Implement `Default`, `Debug`, `Clone`, `PartialEq`, `Serialize`, `Deserialize`.
|
||||
- `impl<V> Combine for ReplaceMap<V>`: if `self.0` is non-empty take self, else take other (matches today's `merge_string_map_replace` with self/other swapped per the convention chosen in Unit 1).
|
||||
- `impl<V> Combine for StickyMap<V>`: per-key insert-or-keep where `self` wins on conflict (matches `merge_string_map_sticky` after swapping argument order).
|
||||
- `impl<V: Combine> Combine for MergeMap<V>`: per-key recursive combine where `self` wins on conflict and missing keys are inherited from `other`.
|
||||
- Keep `run.inputs: Option<HashMap<String, toml::Value>>` as a concrete whole-replace option leaf unless there is a stronger reason to newtype it.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `ReplaceMap` round-trips through TOML deserialize/serialize unchanged.
|
||||
- Happy path: `ReplaceMap::combine` with both non-empty takes `self`'s map whole.
|
||||
- Happy path: `StickyMap::combine` merges keys, `self` wins on conflict.
|
||||
- Happy path: `MergeMap<NotificationRouteLayer>` recursively combines an existing route by key.
|
||||
- Edge case: `ReplaceMap` empty + `StickyMap` empty + `MergeMap` empty — combine produces empty values and preserves fallback behavior.
|
||||
- Integration: existing `tests/parse_*` tests still parse the same TOML fixtures without modification (proves transparent serde works).
|
||||
|
||||
**Verification:** All existing parse tests pass. New newtype tests pass.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 4: Add selective `Combine` impls to settings layer types**
|
||||
|
||||
**Goal:** Cover every settings type. After this unit, `SettingsLayer.combine(other)` works.
|
||||
|
||||
**Files:**
|
||||
- Modify: `*Layer` definitions in `lib/crates/fabro-types/src/settings/{cli,project,workflow,run,server,features,layer}.rs` to add `#[derive(Combine)]` only where current behavior is field-by-field merge.
|
||||
- Modify: whole-replace and irregular types to add bespoke `impl Combine`. Place each impl next to its type definition, or group them in `settings/combine.rs` if local style reads cleaner.
|
||||
- Move the tests currently embedded in `lib/crates/fabro-config/src/merge.rs` into a surviving test module before deleting `merge.rs`.
|
||||
|
||||
**Approach:**
|
||||
- Walk through `merge.rs` function-by-function. For each `combine_<name>(lower, higher) -> NameLayer`:
|
||||
- If the body is field-by-field `higher.x.or(lower.x)` for every field → add `#[derive(Combine)]` to the struct, delete the function.
|
||||
- If one or two fields are special (`merge_string_map_replace` etc.) → if those fields have been migrated to newtypes (Unit 3), the derive handles it. If not, hand-write `impl Combine` on the struct.
|
||||
- If the body returns `higher` whole → hand-written `impl Combine` returning `self`.
|
||||
- If a field currently uses `higher.x.or(lower.x)` and `x` is an `Option<SomeLayer>`, treat it as whole-replace unless the current `merge.rs` calls a recursive `combine_*` helper for that type elsewhere.
|
||||
- For Vec types with splice semantics (model fallbacks, events) → exact bespoke `impl Combine for Vec<...>` or a list newtype. The current `splice_*` helpers can be inlined into the impls. Do not add a blanket Vec impl.
|
||||
- For hook lists → exact bespoke `impl Combine for Vec<HookEntry>` or a `HookList` newtype preserving the current id-aware ordering.
|
||||
- For `RunCheckpointLayer` → hand-write the special "self non-empty wins, otherwise fallback" behavior.
|
||||
- For `FeaturesLayer`, `RunPrepareLayer`, `RunArtifactsLayer`, `CliTargetLayer`, and `ServerListenLayer` → whole-replace impl returning `self`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: for each layer struct, an existing `merge.rs` test (search for `#[test]` in `lib/crates/fabro-config/src/merge.rs` or `tests/`) continues to pass with the new infrastructure substituted. (Recommended: write the new infra to coexist with `merge.rs` initially, swap call sites in Unit 5, then delete `merge.rs` in Unit 6.)
|
||||
- Edge case: hooks ordered merge with id replacement — assert the exact ordering produced today is preserved.
|
||||
- Edge case: model fallbacks splice — verify `Splice` sentinel handling.
|
||||
- Edge case: a whole-replace optional subtable with missing fields does not inherit fallback fields.
|
||||
|
||||
**Verification:** `cargo build --workspace` clean. Existing merge tests still pass when run against the new trait dispatch.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 5: Swap `combine_files` call sites to use `Combine` trait; rewrite `apply_builtin_defaults`**
|
||||
|
||||
**Goal:** All merging goes through `.combine()`.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-config/src/defaults.rs` — `apply_builtin_defaults` becomes `layer.combine(defaults_layer().clone())`.
|
||||
- Modify: every caller of `combine_files` — search `grep -rn "combine_files" lib/`. Audit and convert each.
|
||||
- Modify callers to import `fabro_types::settings::Combine` (or `fabro_types::Combine` if re-exported at crate root).
|
||||
- Argument-order check: today's `combine_files(lower, higher)` becomes `higher.combine(lower)` under the "self wins" convention.
|
||||
|
||||
**Verification:** `cargo build --workspace` clean. `cargo nextest run --workspace` green.
|
||||
|
||||
---
|
||||
|
||||
- [x] **Unit 6: Delete `merge.rs`**
|
||||
|
||||
**Goal:** Final cleanup.
|
||||
|
||||
**Files:**
|
||||
- Delete: `lib/crates/fabro-config/src/merge.rs`
|
||||
- Modify: `lib/crates/fabro-config/src/lib.rs` remove `mod merge;` and any re-exports of merge helpers (`combine_files`, etc.)
|
||||
- Confirm the characterization tests formerly inside `merge.rs` now live in a surviving test module.
|
||||
|
||||
**Verification:**
|
||||
- `cargo build --workspace` clean.
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` clean.
|
||||
- `cargo nextest run --workspace` green.
|
||||
- `grep -rn "combine_files\|merge_option\|merge_string_map" lib/` returns no hits.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **API surface:** `fabro_config::combine_files` removed. `fabro_types::settings::Combine` becomes the trait API for layer combination. Likely no external callers depend on `combine_files`, but verify with grep before deleting.
|
||||
- **Consumer code:** Field reads on `metadata`/`env`/`labels`/`notifications`/`mcps`/`permissions` may need `.0`, iterator helpers, or conversion if `Deref` is not sufficient. Audit during Unit 3.
|
||||
- **Serde compatibility:** `#[serde(transparent)]` on newtypes must round-trip identically to today's bare `HashMap` fields. Existing `tests/parse_*` are the canary.
|
||||
- **Test coverage:** every `merge.rs` test must keep passing, just running through the new infrastructure. Move those tests before deleting `merge.rs`; do not lose behavior parity coverage.
|
||||
- **Net code change:** ~750 lines of `merge.rs` removed; ~25 (derive macro) + ~160 (`combine.rs` trait + option leaf impls + strategy impls) + ~80 (newtypes + consumer adjustments) + bespoke impls. Net reduction is still expected, but exact line count is less important than preserving the merge matrix.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|------|------------|
|
||||
| `Deref<Target = HashMap>` on newtypes doesn't cover every access pattern (e.g., methods that take `HashMap` by value or by `&mut`) | Audit consumers during Unit 3. Add `From`/`Into` impls or change consumer code to take the newtype. |
|
||||
| Serde `#[serde(transparent)]` doesn't behave identically to bare HashMap for some TOML edge cases | The existing `tests/parse_*` fixtures are the contract. Run them after Unit 3; any failure is the migration bug. |
|
||||
| Convention swap (lower/higher → self/other) introduces subtle bugs at `combine_files` call sites | Do Unit 5 carefully. Each call-site swap is a 2-line diff but easy to invert. Lean on existing merge tests. |
|
||||
| Generic `Option<T: Combine>` accidentally field-merges a subtable that currently replaces whole | Unit 4 must audit every `higher.x.or(lower.x)` site. Any inner type with whole-replace semantics gets `impl Combine for T { fn combine(self, _other) -> Self { self } }` or a concrete `impl Combine for Option<T>` leaf impl. Add a regression test where the fallback has a field missing from self and confirm it is not inherited. |
|
||||
| Exact `Vec<...>` impls collide with a future broad list strategy | Do not add blanket `Vec<T>` impls. If exact Vec impls become awkward, migrate those fields to explicit newtypes (`HookList`, `ModelFallbackList`, `EventList`) instead. |
|
||||
| Macro path breaks because derive output expands inside `fabro-types` modules | Re-export `Combine` at a stable path before deriving. Prefer `crate::settings::Combine` or `crate::Combine` and verify with `cargo build -p fabro-types` in Unit 2. |
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved (from design conversation)
|
||||
|
||||
- **Trait + dumb derive vs. attribute-driven derive?** Dumb derive (uv pattern). Attributes hide the merge matrix.
|
||||
- **Where does `Combine` live?** `fabro-types`, because the layer types live there and `fabro-config` depends on `fabro-types`.
|
||||
- **Where does the derive live?** Existing `fabro-macros`, not a new `fabro-config-macros` crate.
|
||||
- **How does generic `Option<T: Combine>` avoid changing whole-replace behavior?** Whole-replace inner types implement `Combine` by returning `self`; scalar leaves get concrete `Option<T>` impls and do not implement `Combine` on `T`.
|
||||
- **Newtypes for map variants?** Yes. Rule lives in the type. Include `ReplaceMap`, `StickyMap`, and `MergeMap`, not just the original three `HashMap<String, String>` cases.
|
||||
- **Blanket collection impls?** No blanket `Vec<T>` or `HashMap<K, V>` impls.
|
||||
- **Convention?** "Self wins" (uv). Swap argument order at call sites in Unit 5.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Should `combine_files` survive as a thin wrapper or be deleted entirely?** Probably delete; `layer.combine(other)` reads fine.
|
||||
- **Exact Vec impls or list newtypes for hooks/fallbacks/events?** Start with exact impls if they stay conflict-free. Move to `HookList`, `ModelFallbackList`, or `EventList` if type coherence or readability gets worse.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Reference implementation:** `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-settings/src/combine.rs` and `/Users/bhelmkamp/p/astral-sh/uv/crates/uv-macros/src/lib.rs` (read both fully before starting).
|
||||
- **Sequencing:** Land `2026-04-23-001-refactor-collapse-settings-resolve-indirection-plan.md` first.
|
||||
- **Design conversation:** preserved in chat transcript with Bryan dated 2026-04-23. Key decisions: rule-lives-in-type beats attribute-driven derive; collection merge strategies need newtypes; `WorkflowSettings` includes `ServerNamespace` (PR 1 decision); `Combine` is the right shape but `Resolve` is not (resolve is per-field, not per-type).
|
||||
- **Origin of current `merge.rs`:** "v2 merge matrix implementation" header note; rules trace to settings TOML redesign requirements (`docs/plans/2026-04-08-settings-toml-redesign-implementation-plan.md` and the follow-on handoffs).
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -1,569 +0,0 @@
|
|||
---
|
||||
title: "refactor: Source-based LLM client resolution + RunServices split"
|
||||
type: refactor
|
||||
status: completed
|
||||
date: 2026-04-23
|
||||
deepened: 2026-04-23
|
||||
---
|
||||
|
||||
# refactor: Source-based LLM client resolution + RunServices split
|
||||
|
||||
## Overview
|
||||
|
||||
PR #168 revealed that `fabro-llm::generate::generate()` silently falls back to `Client::from_env()` when no explicit client is passed. Vault-configured credentials (`openai_codex`) get bypassed. PR #168 is a point fix that threads `Option<Client>` through the pipeline. This plan replaces that with the correct architecture.
|
||||
|
||||
**Design in one line:** credentials are the long-lived authority; clients are short-lived derivations built at the point of use.
|
||||
|
||||
**Greenfield context.** No production installs, no backwards-compat, no migration. The bar is elegance.
|
||||
|
||||
**Two changes:**
|
||||
|
||||
1. Replace the silent env fallback with `CredentialSource` as the credential authority and `Client::from_source(&source)` as the idiomatic constructor. Every `generate()` requires an explicit `Arc<Client>` (compile-time enforcement). Delete `DEFAULT_CLIENT`, `set_default_client`, `get_default_client`, and `Client::from_env`.
|
||||
|
||||
2. Split `EngineServices` into cross-phase `RunServices` (holds `llm_source: Arc<dyn CredentialSource>`) + execute-only `EngineServices` (holds `Arc<RunServices>` + execute-only state). Phase structs carry `Arc<RunServices>` or `Arc<EngineServices>`, not individual service fields. PR #168's `Option<Client>` plumbing unwinds.
|
||||
|
||||
**Prerequisite.** PR #168 must merge to main before Phase 2. Phase 1 is independent of PR #168's merge state.
|
||||
|
||||
## Problem Frame
|
||||
|
||||
Two smells, one architectural root:
|
||||
|
||||
- **Silent env fallback.** `generate()` without an explicit client silently uses `Client::from_env()` — env-only, vault-unaware. Every future call site that forgets a client reintroduces the class bug.
|
||||
- **`Option<Client>` threading.** PR #168 plumbed `Option<Client>` through phase structs to fix one instance. In production the client is always present; the `Option` is a domain lie.
|
||||
|
||||
**Root cause:** `Client` plays two roles today — a short-lived RPC handle AND the point of credential resolution. When a caller forgets to pass one, the "resolution" role silently falls through to env. Separating the two roles — `CredentialSource` is the long-lived authority, `Client` is always derived from one — makes the class bug unrepresentable.
|
||||
|
||||
## Requirements Trace
|
||||
|
||||
- **R1.** `fabro_llm::generate::generate()` fails to compile when no client is supplied. No runtime fallback of any kind.
|
||||
- **R2.** Every long-lived runtime context that needs LLM access (`RunServices`, `AppState`, `HookExecutor`) holds `Arc<dyn CredentialSource>`, not a pinned `Client`. CLI subcommands resolve sources on demand via a `CommandContext::llm_source()` helper, not a held field.
|
||||
- **R3.** OAuth refresh behavior is preserved — clients get fresh tokens at point of use, not at process start.
|
||||
- **R4.** `RunServices` (cross-phase) and `EngineServices` (execute-only) have distinct types. Retro/finalize/PR-body code cannot reach execute-only state.
|
||||
- **R5.** PR #168's production bug stays fixed, covered by a pipeline-level regression test (run with vault-only `openai_codex`, auto-PR body succeeds).
|
||||
- **R6.** Duplicate `build_llm_client` in `fabro-workflow/handler/llm/api.rs` and `fabro-server/server_secrets.rs` collapses to one implementation.
|
||||
|
||||
## Scope Boundaries
|
||||
|
||||
- Don't rework `Client` internals, provider adapters, `from_credentials`, or any `fabro-llm` provider registration logic.
|
||||
- Don't redesign vault/credential storage — `VaultCredentialSource` adapts existing `CredentialResolver` logic.
|
||||
- Don't change phase ordering or per-phase behavior — only where shared state lives.
|
||||
- Don't touch the `fabro-client` crate extraction (`docs/plans/2026-04-20-002`).
|
||||
- Don't create `docs/solutions/` (separate opportunity).
|
||||
|
||||
## Context & Research
|
||||
|
||||
### Relevant Code
|
||||
|
||||
**`fabro-llm`:**
|
||||
- `lib/crates/fabro-llm/src/client.rs` — `Client::new`, `Client::from_env`, `Client::from_credentials`, `provider_names`. `Client` derives `Clone`.
|
||||
- `lib/crates/fabro-llm/src/generate.rs` — `DEFAULT_CLIENT: OnceCell<Arc<Client>>`, `set_default_client`, `get_default_client`, `generate`, `stream_with_tool_loop`, `stream_generate`, `generate_object`. `GenerateParams.client: Option<Arc<Client>>`.
|
||||
|
||||
**`fabro-auth`:**
|
||||
- `lib/crates/fabro-auth/src/resolve.rs` — `CredentialResolver { vault: Arc<AsyncRwLock<Vault>>, env_lookup: EnvLookup }`. `resolve(provider, usage)` returns `ResolvedCredential::Api(ApiCredential)` or error. Handles OAuth refresh and writes back to vault.
|
||||
- `ApiCredential`, `ApiKeyHeader` — already imported by `fabro-llm::client::Client::from_env`.
|
||||
|
||||
**`fabro-workflow`:**
|
||||
- `lib/crates/fabro-workflow/src/handler/mod.rs` — `EngineServices` (13 fields today).
|
||||
- `lib/crates/fabro-workflow/src/handler/llm/api.rs` — `build_llm_client(resolver: Option<&CredentialResolver>)`; `AgentApiBackend::create_session_for` and `one_shot` rebuild client per session via `build_llm_client(self.resolver.as_ref()).await?.client` at `:268` and `:349`. **This per-session rebuild is load-bearing for OAuth refresh.**
|
||||
- `lib/crates/fabro-workflow/src/handler/llm/cli.rs` — parallel `AgentCliBackend` with its own `new_from_env`.
|
||||
- `lib/crates/fabro-workflow/src/pipeline/types.rs` — phase structs and options.
|
||||
- `lib/crates/fabro-workflow/src/pipeline/initialize.rs:555-566` — `SandboxReady` hook fires BEFORE `build_registry` at `:587` builds the LLM client. Any design that requires a client at hook time regresses this.
|
||||
- `lib/crates/fabro-workflow/src/pipeline/{execute,retro,finalize,pull_request}.rs` — phase implementations.
|
||||
- `lib/crates/fabro-workflow/src/operations/start.rs` — `RunSession`, `StartServices`. `RunSession.vault: Option<Arc<AsyncRwLock<Vault>>>` threads to `InitOptions.vault` at `:714`.
|
||||
|
||||
**Consumers:**
|
||||
- `lib/crates/fabro-cli/src/main.rs` — CLI entry.
|
||||
- `lib/crates/fabro-cli/src/command_context.rs:61-72` — `CommandContext::with_target` and `with_connection` re-derive context per subcommand with different `storage_dir_override`. **A process-global source install is not correct here.**
|
||||
- `lib/crates/fabro-cli/src/commands/pr/create.rs` — loads vault at `:103`, calls `maybe_open_pull_request(..., None)`.
|
||||
- `lib/crates/fabro-cli/src/shared/provider_auth.rs` — already passes explicit client.
|
||||
- `lib/crates/fabro-hooks/src/executor.rs` — `execute_prompt` (default client today), `execute_agent` (`Client::from_env()` at `:358`).
|
||||
- `lib/crates/fabro-agent/src/cli.rs:436` — `Client::from_env()`.
|
||||
- `lib/crates/fabro-server/src/server.rs:2488` — `build_app_state`; `Vault::load` at `:2500`.
|
||||
- `lib/crates/fabro-server/src/server_secrets.rs:87-112` — duplicate `ProviderCredentials::build_llm_client`.
|
||||
|
||||
### Institutional Learnings
|
||||
|
||||
- **`docs/plans/2026-04-20-002-refactor-extract-fabro-client-crate-plan.md`** — `CredentialFallback` named-trait precedent. Same rationale applies here: named trait makes the role obvious at the call site.
|
||||
- **`docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md:171,485`** — Already flagged `from_env()` as a smell; this plan resolves the deferred follow-up.
|
||||
- **`docs/plans/2026-04-22-003-refactor-lock-down-server-secrets-plan.md:74-78`** — Credential taxonomy. LLM provider credentials live on the Vault + `ProviderCredentials` track.
|
||||
- **`docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md:59-61`** and **`docs/plans/2026-04-23-001-refactor-command-context-alignment-plan.md:273-277`** — Repo has twice rejected adding a peer-wrapper alongside an existing context. This plan's `RunServices`/`EngineServices` split is **composition** (`EngineServices` contains `Arc<RunServices>`), not a peer wrapper — and is about the pipeline (`fabro-workflow`), not CLI (`fabro-cli`). The rejections do not apply.
|
||||
|
||||
## Key Technical Decisions
|
||||
|
||||
### 1. Credentials are the authority; clients are derived
|
||||
|
||||
`CredentialSource` trait lives in `fabro-auth`:
|
||||
|
||||
```rust
|
||||
pub struct ResolvedCredentials {
|
||||
pub credentials: Vec<ApiCredential>,
|
||||
pub auth_issues: Vec<(Provider, ResolveError)>,
|
||||
}
|
||||
|
||||
pub trait CredentialSource: Send + Sync {
|
||||
/// Full resolution with OAuth refresh. Expensive. Returns credentials + auth issues.
|
||||
async fn resolve(&self) -> Result<ResolvedCredentials, Error>;
|
||||
|
||||
/// Cheap preflight: which providers have credentials configured at all?
|
||||
/// No OAuth refresh. Used for model selection and manifest building.
|
||||
async fn configured_providers(&self) -> Vec<Provider>;
|
||||
}
|
||||
```
|
||||
|
||||
The richer return type preserves today's partial-resolution diagnostics. `auth_issues` exists because `CredentialResolver::resolve` can fail for one provider (e.g. "OpenAI OAuth refresh failed") while another succeeds — callers produce user-facing messages like "OpenAI requires re-authentication; Anthropic is not configured." This is load-bearing at four sites: `pipeline/initialize.rs:301-318` (error message on "no usable providers"), `server/src/server.rs:6652` (diagnostics endpoint), `server/src/server.rs:6821-6833` (`create_completion` logs `warn!` per issue), `server/src/diagnostics.rs:90`.
|
||||
|
||||
Natural home: `fabro-auth` already owns `ApiCredential`, `CredentialResolver`, and `ResolveError`. No new dep cycles. `fabro-llm` exposes `Client::from_source(&dyn CredentialSource) -> Result<Arc<Client>, Error>` — a convenience that discards `auth_issues` and returns only the Client. Callers that need diagnostics call `source.resolve()` directly and inspect both halves.
|
||||
|
||||
**Implementors:**
|
||||
- `VaultCredentialSource` in `fabro-auth` — wraps `CredentialResolver`. Iterates `Provider::ALL` calling `resolver.resolve(provider, CredentialUsage::ApiRequest)`, collecting credentials and auth issues. Two constructors:
|
||||
- `VaultCredentialSource::new(Arc<AsyncRwLock<Vault>>)` — default env lookup (used by workflow path).
|
||||
- `VaultCredentialSource::with_env_lookup(Arc<AsyncRwLock<Vault>>, env_lookup)` — server uses this with its own env policy (preserves today's `ProviderCredentials::with_env_lookup` behavior at `server_secrets.rs:67`). Replaces `build_llm_client` in both `fabro-workflow/handler/llm/api.rs` and `fabro-server/server_secrets.rs`.
|
||||
- `EnvCredentialSource` in `fabro-auth` — reads env vars for each provider, emits `ApiCredential`s. Replaces `Client::from_env`. `auth_issues` is typically empty for this source.
|
||||
|
||||
**Server-side implication:** `ProviderCredentials` collapses into a `VaultCredentialSource` constructed via `with_env_lookup`. The server doesn't need its own `CredentialSource` impl — the env-lookup policy is a constructor argument, not a type-level distinction. This is the key insight that lets the consolidation actually happen rather than just moving duplication behind a trait.
|
||||
|
||||
### 2. No process-global state
|
||||
|
||||
No `DEFAULT_CLIENT`, no `defaults::install`, no `Client::available_default`. Every long-lived runtime context holds its own `Arc<dyn CredentialSource>`:
|
||||
|
||||
- `RunServices.llm_source` — built from `InitOptions.vault` at initialize (or `EnvCredentialSource` if vault is `None`; see §3).
|
||||
- `AppState.llm_source` — built from `Vault::load` at `build_app_state`.
|
||||
- `HookExecutor.llm_source` — received on construction from the invoker.
|
||||
- Standalone agent CLI — builds source at startup from resolved vault or env.
|
||||
- Tests — build stubs directly, no install ceremony.
|
||||
|
||||
**CLI subcommands resolve sources on demand.** `CommandContext` does not hold a source as a field. Instead it exposes a lazy helper:
|
||||
|
||||
```rust
|
||||
impl CommandContext {
|
||||
pub async fn llm_source(&self) -> Result<Arc<dyn CredentialSource>> { ... }
|
||||
}
|
||||
```
|
||||
|
||||
This mirrors the existing `CommandContext::server()` pattern (`command_context.rs:106-134`). The helper is re-derived per `with_target`/`with_connection` call, so each subcommand gets the right source for its resolved storage dir — no binding hazard.
|
||||
|
||||
This design eliminates: CLI re-derivation hazard (`CommandContext::with_connection` can change storage_dir), test cross-contamination on shared statics, double-install policy questions, feature-gate hazards, and the question "which install site wins."
|
||||
|
||||
### 3. `RunServices.llm_source` is always `Some` — no `Option`
|
||||
|
||||
Today's `RunSession.vault: Option<Arc<AsyncRwLock<Vault>>>` is optional (workflows can run without a vault, e.g. dry-run or env-only). The plan keeps `RunServices.llm_source` **non-optional** to preserve the elegance of "every context has a source." Rule:
|
||||
|
||||
- **Vault is `Some`:** build `VaultCredentialSource` from it.
|
||||
- **Vault is `None`:** build `EnvCredentialSource::new()` — reads env vars; may resolve empty. Same semantics as today's `build_llm_client` with `resolver: None` branch.
|
||||
- **Dry-run:** `EngineServices.dry_run` (separate flag, as today) is the authoritative signal. When true, handlers skip LLM stages entirely; `llm_source` is constructed anyway but unused.
|
||||
- **No credentials anywhere:** `source.resolve()` returns empty `Vec<ApiCredential>`. `Client::from_source` returns a Client with `provider_names().is_empty()`. Consumers that need to `generate()` detect this via the same check as today (`initialize.rs:302`) and error with a helpful message built from `auth_issues`.
|
||||
|
||||
The error "No usable LLM providers configured" becomes a point-of-use error rather than an initialize-time error, **except** for graphs where `graph::needs_llm_handler_type` is true — for those, `initialize` preflights `source.resolve()` once and errors early with the same message today produces. Preserves UX.
|
||||
|
||||
### 4. Clients are built at point of use
|
||||
|
||||
`AgentApiBackend` today rebuilds `Client` per session via `build_llm_client(resolver)` — load-bearing for OAuth refresh on long runs. The new design preserves this pattern: every caller that wants a client calls `Client::from_source(&source).await?` at the point of use. Under the hood, `source.resolve()` calls `resolver.resolve()` which refreshes OAuth tokens and writes back to the vault.
|
||||
|
||||
No pinned per-run `Client`. No stale-token regression.
|
||||
|
||||
### 5. `GenerateParams.client: Arc<Client>` is required
|
||||
|
||||
Not `Option`. `GenerateParams::new(model, client)` takes both. Compile error if a future caller forgets.
|
||||
|
||||
### 6. Delete `Client::from_env`
|
||||
|
||||
`Client::from_env` was the silent-fallback gateway. It's replaced by `Client::from_source(&EnvCredentialSource::new())` — explicit, one-line, same result, and doesn't leave a footgun for future contributors.
|
||||
|
||||
`Client::from_credentials` stays as the lowest-level constructor (used internally by `from_source`).
|
||||
|
||||
### 7. `SandboxReady` hooks get a source, not a client
|
||||
|
||||
Hooks run at `pipeline/initialize.rs:555`, before `build_registry` at `:587`. In the source-on-context design this is fine: `InitOptions.vault` already exists at hook time; `initialize` builds a `VaultCredentialSource` eagerly (or `EnvCredentialSource` if vault is `None`) and passes it to the hook runner. A `SandboxReady` hook that wants to `generate()` calls `Client::from_source(&source).await?` at its point of use.
|
||||
|
||||
### 8. `RunServices` / `EngineServices` split is composition, not peer wrapping
|
||||
|
||||
Today's single `EngineServices` (13 fields) mixes two lifetimes:
|
||||
|
||||
- **Cross-phase** (live past execute into retro/finalize/PR): `run_store`, `emitter`, `sandbox`, `hook_runner`, `cancel_requested`, `provider`, and the new `llm_source`.
|
||||
- **Execute-only** (die at the execute→retro boundary): `registry`, `inputs`, `workflow_bundle`, `workflow_path`, `dry_run`, `env`, `git_state`.
|
||||
|
||||
Split into two structs with `EngineServices { run: Arc<RunServices>, ...execute_only_fields }`. Retroed/Concluded/PullRequestOptions carry `Arc<RunServices>` only — they can't reach execute-only state by construction.
|
||||
|
||||
This is composition (`EngineServices` contains `Arc<RunServices>`), not the peer-wrapper pattern the CLI plans rejected. Handlers read `services.run.emitter` for cross-phase state and `services.registry` for execute-only state. One access shape, two concerns.
|
||||
|
||||
### 9. Server's `ProviderCredentials` collapses into `VaultCredentialSource::with_env_lookup`
|
||||
|
||||
`fabro-server/src/server_secrets.rs` today owns two capabilities:
|
||||
- `build_llm_client` (`:87-112`) — full resolution with OAuth refresh, plus `auth_issues`.
|
||||
- `configured_providers` (`:114-119`) — cheap preflight used for model selection at `server.rs:3929` and `run_manifest.rs:355`.
|
||||
|
||||
Both collapse into `VaultCredentialSource`: `build_llm_client` → `source.resolve()`; `configured_providers` → `source.configured_providers()` (the second trait method). With `VaultCredentialSource::with_env_lookup` covering the server's env policy (§1), `ProviderCredentials` disappears — `build_app_state` constructs `VaultCredentialSource::with_env_lookup(vault, env_lookup)` directly and stores it as `Arc<dyn CredentialSource>` on `AppState`. Callers at `server.rs:3929` and `run_manifest.rs:355` swap `state.provider_credentials.configured_providers().await` → `state.llm_source.configured_providers().await`. One trait, one type, two capabilities.
|
||||
|
||||
## Open Questions
|
||||
|
||||
### Resolved During Planning
|
||||
|
||||
- **Trait home?** `fabro-auth` (owns `ApiCredential`, `CredentialResolver`). Avoids `fabro-auth → fabro-llm` cycle.
|
||||
- **Keep `Client::from_env`?** No. Replaced by `EnvCredentialSource` + `Client::from_source`. One construction path.
|
||||
- **Process-global static?** No. Every context holds its own source.
|
||||
- **`Client::available_default`?** Not needed. Callers use `Client::from_source(&ctx.llm_source)` where `ctx` is whatever context they hold.
|
||||
- **Per-run client caching?** No. `Client::from_source` is called at point of use. Cost is acceptable (one resolver iteration + `from_credentials`), and this is where OAuth refresh happens.
|
||||
- **OAuth refresh preservation?** Automatic. `resolver.resolve()` handles refresh; it runs every time a caller builds a client from a source.
|
||||
- **CLI install site?** None. Each `CommandContext`-derived command that needs LLM builds its own source from the context's storage dir.
|
||||
- **Server install site?** None. `build_app_state` constructs `VaultCredentialSource` once and stores it on `AppState`.
|
||||
- **`SandboxReady` hook ordering?** No change. `InitOptions.vault` already exists at hook time; source is built before the hook runs.
|
||||
- **Duplicate `build_llm_client` in server?** Delete. Server uses `VaultCredentialSource`. Parity test in Unit 1.2 guards the deletion.
|
||||
- **`install_mock_llm` test helper?** Delete. Tests construct sources and clients directly.
|
||||
- **Partial resolution diagnostics (`auth_issues`)?** Preserved. Trait returns `ResolvedCredentials { credentials, auth_issues }`. Four diagnostic call sites (`initialize.rs:301`, `server.rs:6652`, `server.rs:6821-6833` per-issue `warn!`, `diagnostics.rs:90`) consume `auth_issues` directly via `source.resolve()`. `Client::from_source` is the convenience path for callers that don't need diagnostics.
|
||||
- **What source exists when `InitOptions.vault` is `None`?** `EnvCredentialSource::new()`. `RunServices.llm_source` is never `Option`. Graph-needs-LLM preflight inside `initialize` produces the same user-facing error today produces.
|
||||
- **CLI source ownership?** `CommandContext::llm_source(&self) -> Result<Arc<dyn CredentialSource>>` — lazy helper, re-derived per `with_target`/`with_connection`. Mirrors existing `CommandContext::server()`.
|
||||
|
||||
### Deferred to Implementation
|
||||
|
||||
- **Exact error type on the trait.** `Result<ResolvedCredentials, ?>` — use `fabro-auth::Error` or introduce a trait-level `CredentialSourceError`. Decide while writing the trait.
|
||||
- **Where `CommandContext::llm_source` caches.** `OnceCell<Arc<dyn CredentialSource>>` on the context like `server: OnceCell<Arc<Client>>` today, or freshly built per call. Decide by measuring: if CLI subcommands only call it once per invocation anyway, a `OnceCell` is overkill.
|
||||
- **`HookExecutor` construction signature.** Takes `Arc<dyn CredentialSource>`. Workflow callers pass `services.run.llm_source.clone()`; standalone callers construct their own.
|
||||
- **Test harness fixture.** `RunServices::for_test()` builds a stub source + minimal services. Exact surface decided during Unit 2.1.
|
||||
|
||||
## High-Level Technical Design
|
||||
|
||||
> *Directional guidance for review, not implementation specification.*
|
||||
|
||||
### Client resolution flow
|
||||
|
||||
```
|
||||
Caller has long-lived Arc<dyn CredentialSource>
|
||||
|
||||
When a generate() is needed:
|
||||
let client = Client::from_source(&source).await?;
|
||||
generate(GenerateParams::new(model, client).prompt("..."))
|
||||
|
||||
Under the hood:
|
||||
Client::from_source(&source)
|
||||
└── source.resolve() → ResolvedCredentials { credentials, auth_issues }
|
||||
└── VaultCredentialSource: iterate Provider::ALL, resolver.resolve() (with OAuth refresh)
|
||||
or EnvCredentialSource: iterate Provider::ALL, read env
|
||||
└── Client::from_credentials(resolved.credentials) // Client::from_source discards auth_issues
|
||||
|
||||
For diagnostics-aware callers (initialize preflight, server diag endpoint):
|
||||
let resolved = source.resolve().await?;
|
||||
if resolved.credentials.is_empty() && graph_needs_llm {
|
||||
// build detailed error from resolved.auth_issues
|
||||
}
|
||||
```
|
||||
|
||||
### Services topology
|
||||
|
||||
```
|
||||
┌────────────────────── RunServices (Arc) ────────────────────────┐
|
||||
│ run_store, emitter, sandbox, hook_runner, cancel_requested, │
|
||||
│ provider, llm_source: Arc<dyn CredentialSource> │
|
||||
└───────────────────────────────┬─────────────────────────────────┘
|
||||
│ Arc<RunServices>
|
||||
▼
|
||||
┌──────────────────── EngineServices (Arc) ───────────────────────┐
|
||||
│ run: Arc<RunServices>, │
|
||||
│ registry, inputs, workflow_bundle, workflow_path, │
|
||||
│ dry_run, env, git_state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
|
||||
Phase data flow:
|
||||
Persisted → Initialized { engine: Arc<EngineServices> }
|
||||
→ Executed { engine: Arc<EngineServices> }
|
||||
→ Retroed { services: Arc<RunServices> } // drops execute-only state
|
||||
→ Concluded { services: Arc<RunServices> }
|
||||
→ Finalized { /* no services — terminal */ }
|
||||
```
|
||||
|
||||
### Where sources come from
|
||||
|
||||
| Context | Source construction |
|
||||
|---|---|
|
||||
| Workflow run | `pipeline/initialize.rs` — `VaultCredentialSource::new(vault)` if `InitOptions.vault` is `Some`, else `EnvCredentialSource::new()` |
|
||||
| CLI subcommand | `CommandContext::llm_source().await?` — lazy helper built from the context's resolved storage dir |
|
||||
| Server | `build_app_state` — `VaultCredentialSource::with_env_lookup(vault, env_lookup)` from `Vault::load` (preserves today's server env-lookup policy) |
|
||||
| Standalone `fabro agent` | CLI startup — resolved vault or `EnvCredentialSource` |
|
||||
| Tests | Inline stub impl |
|
||||
|
||||
## Implementation Units
|
||||
|
||||
### Phase 1 — Source-based client resolution
|
||||
|
||||
- [x] **Unit 1.1: Add `CredentialSource` trait + `VaultCredentialSource` + `EnvCredentialSource` + `Client::from_source`**
|
||||
|
||||
**Goal:** Pure addition of the new abstractions. No consumer changes. Existing code compiles and runs unchanged.
|
||||
|
||||
**Requirements:** R2, R3 (groundwork).
|
||||
|
||||
**Dependencies:** None.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-auth/src/lib.rs` (re-exports)
|
||||
- Create: `lib/crates/fabro-auth/src/credential_source.rs` (trait)
|
||||
- Create: `lib/crates/fabro-auth/src/vault_source.rs` (`VaultCredentialSource`)
|
||||
- Create: `lib/crates/fabro-auth/src/env_source.rs` (`EnvCredentialSource`)
|
||||
- Modify: `lib/crates/fabro-llm/src/client.rs` (add `Client::from_source`)
|
||||
- Test: inline unit tests in each new file; `lib/crates/fabro-llm/src/client.rs` test for `from_source`
|
||||
|
||||
**Approach:**
|
||||
- `struct ResolvedCredentials { credentials: Vec<ApiCredential>, auth_issues: Vec<(Provider, ResolveError)> }`.
|
||||
- `trait CredentialSource: Send + Sync` with `async fn resolve(&self) -> Result<ResolvedCredentials, Error>`. Use `async_trait::async_trait`.
|
||||
- `VaultCredentialSource::new(Arc<AsyncRwLock<Vault>>) -> Self` wraps `CredentialResolver::new` (default env lookup).
|
||||
- `VaultCredentialSource::with_env_lookup(Arc<AsyncRwLock<Vault>>, F) -> Self` where `F: Fn(&str) -> Option<String> + Send + Sync + 'static` wraps `CredentialResolver::with_env_lookup` (preserves server env policy).
|
||||
- `resolve()` iterates `Provider::ALL`, matching today's logic at `handler/llm/api.rs:43-78` byte-for-byte — both credentials accumulation and `auth_issues` accumulation.
|
||||
- `configured_providers()` delegates to `CredentialResolver::configured_providers(&vault)` at `fabro-auth/src/resolve.rs:140`. Cheap vault read; no OAuth refresh. Matches today's `ProviderCredentials::configured_providers` at `server_secrets.rs:114-119` byte-for-byte.
|
||||
- For `EnvCredentialSource`, `configured_providers()` iterates `Provider::ALL` checking env-var presence for each (returns providers whose env vars are set).
|
||||
- `EnvCredentialSource::new()` reads env for each provider in `Provider::ALL`, emitting `ApiCredential`s. `auth_issues` is always empty. Replaces the body of today's `Client::from_env`.
|
||||
- `Client::from_source(source: &dyn CredentialSource) -> Result<Arc<Client>, Error>` — calls `source.resolve()`, discards `auth_issues`, calls `Client::from_credentials`, wraps in `Arc`. Callers that need diagnostics call `source.resolve()` directly.
|
||||
- Move `auth_issue_message` helper (today duplicated in `fabro-workflow/handler/llm/api.rs:82` and `fabro-server/server_secrets.rs:127`) to `fabro-auth` alongside the trait.
|
||||
- `ApiCredential` must have a redacting `Debug` impl (verify/add using `fabro-redact`). Add unit test asserting `format!("{:?}", credential)` does not echo key material.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `CredentialFallback` trait shape in `docs/plans/2026-04-20-002-refactor-extract-fabro-client-crate-plan.md`.
|
||||
- Existing `CredentialResolver` iteration in `lib/crates/fabro-workflow/src/handler/llm/api.rs:43-78` (preserve semantics exactly, including partial-resolution `auth_issues` accumulation).
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `VaultCredentialSource::resolve()` with a vault containing `openai_codex` returns `ResolvedCredentials` with the OpenAI entry in `.credentials` and empty `.auth_issues`.
|
||||
- Happy path: `VaultCredentialSource::configured_providers()` with a vault containing OpenAI + Anthropic returns `[OpenAi, Anthropic]`. No OAuth refresh happens (verified via a stub vault that panics on write).
|
||||
- Happy path: `EnvCredentialSource::configured_providers()` with `ANTHROPIC_API_KEY` set returns `[Anthropic]`; with nothing set, returns empty.
|
||||
- Happy path (partial resolution): `VaultCredentialSource::resolve()` with a vault containing `openai_codex` whose refresh token has expired **and** a working Anthropic `ApiKey` returns both — Anthropic in `.credentials`, `(OpenAi, ResolveError::RefreshFailed{...})` in `.auth_issues`. Matches real auth shapes (`CodexOAuth` is OpenAI-only per `fabro-auth/src/credential.rs:69-73`).
|
||||
- Happy path: `EnvCredentialSource` with `ANTHROPIC_API_KEY` set returns one entry; with nothing set, returns an empty `ResolvedCredentials` (not an error).
|
||||
- Happy path: `Client::from_source(&stub)` where stub returns a single-provider `ResolvedCredentials` yields a Client with that provider registered.
|
||||
- Happy path: `Client::from_source(&VaultCredentialSource::new(vault))` with OAuth credential calls through `resolver.resolve` (verified via a stub vault that records calls).
|
||||
- Edge case: source returning empty credentials yields a Client with `provider_names().is_empty()` — no error.
|
||||
- Redaction: `format!("{:?}", credential)` does not contain the key/token.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-auth -p fabro-llm` passes.
|
||||
- `cargo +nightly-2026-04-14 clippy -p fabro-auth -p fabro-llm --all-targets -- -D warnings` clean.
|
||||
|
||||
- [x] **Unit 1.2: Migrate every LLM consumer to hold/pass sources and build clients explicitly**
|
||||
|
||||
**Goal:** Every `generate()`/`generate_object()`/`stream_generate()` call site constructs its `Arc<Client>` explicitly (via `Client::from_source`). Every long-lived backend/executor/context holds `Arc<dyn CredentialSource>`. `DEFAULT_CLIENT` and the default-client code path remain temporarily so each migration step compiles/tests cleanly.
|
||||
|
||||
**Requirements:** R2, R3, R6.
|
||||
|
||||
**Dependencies:** Unit 1.1.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/handler/llm/api.rs` — `AgentApiBackend` holds `Arc<dyn CredentialSource>`; `create_session_for` and `one_shot` call `Client::from_source(&self.source)` per call (matching today's per-session rebuild). Delete `build_llm_client` and the local `auth_issue_message` helper (both moved to `fabro-auth` in Unit 1.1).
|
||||
- Modify: `lib/crates/fabro-workflow/src/handler/llm/cli.rs` — parallel treatment for `AgentCliBackend`.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/initialize.rs` — `build_registry` takes/holds `Arc<dyn CredentialSource>`. Builds source from `InitOptions.vault` when `Some`, else `EnvCredentialSource::new()`. Passes source to backends. For `graph_needs_llm` paths, preflights `source.resolve()` once at initialize and produces the same "No usable LLM providers configured: ..." error at `:301-318` by consuming `ResolvedCredentials.auth_issues`. Phase 2 moves the source onto `RunServices`; for this unit, hold it alongside the registry return value.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/initialize.rs:555-566` — `SandboxReady` hook invocation passes the already-built source into the hook runner.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/pull_request.rs` — `build_pr_body`/`maybe_open_pull_request` accept an explicit client (PR #168 already added this; here it becomes non-Option).
|
||||
- Modify: `lib/crates/fabro-hooks/src/executor.rs` — `HookExecutor::new(..., source: Arc<dyn CredentialSource>)`. `execute_prompt` and `execute_agent` call `Client::from_source(&self.source)` at point of use. Remove `Client::from_env()` at `:358`.
|
||||
- Modify: `lib/crates/fabro-hooks/src/runner.rs` — `HookRunner` carries source, forwards to executor.
|
||||
- Modify: `lib/crates/fabro-cli/src/main.rs` — no process-global install.
|
||||
- Modify: `lib/crates/fabro-cli/src/command_context.rs` — add lazy helper `pub async fn llm_source(&self) -> Result<Arc<dyn CredentialSource>>`. Resolves from the context's current storage dir; builds `VaultCredentialSource` when a vault is present, `EnvCredentialSource` otherwise. Follow the existing `CommandContext::server()` pattern at `:106-134`.
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/create.rs` — replace today's direct `Vault::load` at `:103` with `ctx.llm_source().await?`. Call `Client::from_source(&source)`, pass into `maybe_open_pull_request`.
|
||||
- Modify: `lib/crates/fabro-cli/src/shared/provider_auth.rs` — already passes an explicit client. No change.
|
||||
- Modify: `lib/crates/fabro-agent/src/cli.rs` — replace `Client::from_env()` with source-based resolution (either via `CommandContext::llm_source` or an equivalent startup helper).
|
||||
- Modify/delete: `lib/crates/fabro-server/src/server_secrets.rs` — delete `ProviderCredentials` entirely (struct at `:61-75`, `build_llm_client` at `:87-112`, `configured_providers` at `:114-119`, local `auth_issue_message` at `:127`). Both capabilities move to `VaultCredentialSource` via the `CredentialSource` trait. Diagnostic callers at `server.rs:6652`, `server.rs:6821`, and `diagnostics.rs:90` consume `ResolvedCredentials.auth_issues` from `source.resolve()`.
|
||||
- Modify: `lib/crates/fabro-server/src/server.rs` — `build_app_state` (`:2488`) constructs `VaultCredentialSource::with_env_lookup(vault, env_lookup)` and stores it as `Arc<dyn CredentialSource>` on `AppState`. `create_completion` (`:6821-6833`) calls `state.llm_source.resolve()` directly (not `Client::from_source`), logs each `auth_issue` via `warn!` (preserving today's observability at `:6831-6833`), then builds the client via `Client::from_credentials(resolved.credentials)`. Server diagnostics endpoint (`:6652`) same pattern. Site at `:3929` swaps `state.provider_credentials.configured_providers().await` → `state.llm_source.configured_providers().await`.
|
||||
- Modify: `lib/crates/fabro-server/src/run_manifest.rs:355` — same swap: `state.provider_credentials.configured_providers().await` → `state.llm_source.configured_providers().await`.
|
||||
- Test: per-crate unit tests; a workflow-level integration test that runs a minimal pipeline with a vault-only `openai_codex` credential and asserts agent stages use a fresh client each session.
|
||||
|
||||
**Approach:**
|
||||
- Mechanical migration. Each consumer that previously used the default client now constructs explicitly from a source it already has access to.
|
||||
- `AgentApiBackend` today: `build_llm_client(self.resolver.as_ref()).await?.client` per session. New: `Client::from_source(&self.source).await?` per session. Functionally equivalent; OAuth refresh still happens because `source.resolve()` calls `resolver.resolve()` which refreshes.
|
||||
- `build_registry` no longer needs to return a client — it returns the registry and the source (passed to backends). Clients are built per session inside the backends.
|
||||
- Diagnostic sites that previously called `build_llm_client(...).auth_issues` now call `source.resolve()` and consume `.auth_issues` directly. Four sites: `initialize.rs:301` (error message), `server.rs:6652` (diagnostics endpoint), `server.rs:6821-6833` (`create_completion` per-issue `warn!`), `diagnostics.rs:90`. Each of these stays on the `resolve()` path rather than using the `Client::from_source` convenience — they need both halves.
|
||||
|
||||
**Patterns to follow:**
|
||||
- `AgentApiBackend::create_session_for:268` (today's per-session pattern) is the model.
|
||||
- `CommandContext::server()` (`command_context.rs:106-134`) is the model for the new `llm_source()` helper — lazy, re-derived per context, cached via `OnceCell` per context.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path (workflow, vault): pipeline run with vault-configured `openai_codex` produces a Client per session with `openai` registered. Verified via a test that wraps a stub source and counts `resolve()` calls (should equal session count + 1 for retro/PR + 1 for initialize preflight).
|
||||
- Happy path (workflow, no vault): `InitOptions.vault = None`, graph has no LLM handlers — initialize succeeds; `llm_source` is an `EnvCredentialSource` and is never queried.
|
||||
- Error path (workflow, no vault, graph needs LLM): `InitOptions.vault = None`, graph has LLM handlers, no env credentials — initialize preflight `source.resolve()` returns empty credentials; error produced is the same "No usable LLM providers configured: ..." message today builds from `auth_issues` (empty for env source → plain "No LLM providers configured" fallback).
|
||||
- Error path (workflow, vault with one bad credential + one good): partial resolution — `openai_codex` with expired refresh token + working Anthropic `ApiKey`. Initialize preflight succeeds (Anthropic is usable); `auth_issues` is logged or surfaced per today's behavior.
|
||||
- Happy path (CLI `pr create`): command calls `ctx.llm_source().await?`, builds client, generates PR body. No `None` parameter anywhere.
|
||||
- Happy path (CLI context re-derivation): `ctx.with_connection(args)` produces a new context with its own `llm_source` bound to the new storage dir. Verified by calling `llm_source` on two derived contexts with different storage dirs.
|
||||
- Happy path (hooks, workflow-invoked): `SandboxReady` hook that wants to generate receives source from `initialize`; builds a client and calls `generate`.
|
||||
- Happy path (hooks, standalone agent): `fabro agent` CLI builds source at startup, passes to `HookExecutor`; hooks build clients as needed.
|
||||
- Regression: server `create_completion` request generates successfully after `build_app_state` stores the source on `AppState`.
|
||||
- Regression: server diagnostic endpoint at `server.rs:6652` still reports auth issues for misconfigured providers.
|
||||
- Regression: server `create_completion` at `server.rs:6821-6833` still emits `warn!` per auth issue before building the client. Verified via a test with a partial-resolution fixture source (one working provider, one failing) that captures `warn!` events and asserts the expected log output.
|
||||
- Regression: `AgentCliBackend` (CLI-mode agent) works with source-based resolution.
|
||||
- Parity (resolve): `VaultCredentialSource::with_env_lookup(vault, env_lookup).resolve()` output (credentials + auth_issues) matches today's `ProviderCredentials::build_llm_client()` output for the same fixture vault + env policy.
|
||||
- Parity (configured_providers): `VaultCredentialSource::with_env_lookup(vault, env_lookup).configured_providers()` output matches today's `ProviderCredentials::configured_providers()` output for the same fixture. Required before deleting the old path.
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `cargo +nightly-2026-04-14 clippy --workspace --all-targets -- -D warnings` clean.
|
||||
- `rg 'Client::from_env' lib/crates/` — only `client.rs` (constructor definition), `EnvCredentialSource` (if it reuses the body), and test files.
|
||||
- `rg 'build_llm_client' lib/crates/` — zero hits.
|
||||
|
||||
- [x] **Unit 1.3: Delete the default-client machinery and `Client::from_env`; require `GenerateParams.client`**
|
||||
|
||||
**Goal:** Atomic cleanup. Every consumer already passes an explicit client (Unit 1.2). Now remove the fallback paths.
|
||||
|
||||
**Requirements:** R1, R6.
|
||||
|
||||
**Dependencies:** Unit 1.2.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-llm/src/generate.rs` — delete `DEFAULT_CLIENT`, `set_default_client`, `get_default_client`, the `Client::from_env()` fallback inside `get_default_client`. `GenerateParams.client: Arc<Client>` (not `Option`). `GenerateParams::new(model, client)` takes both. Drop the `.client(...)` builder method.
|
||||
- Modify: `lib/crates/fabro-llm/src/lib.rs` — drop `set_default_client` re-export.
|
||||
- Modify: `lib/crates/fabro-llm/src/client.rs` — delete `Client::from_env`. Keep `Client::from_credentials` (used internally by `EnvCredentialSource` and `Client::from_source`).
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/pull_request.rs` — delete `install_mock_llm` helper and the three `install_mock_llm()` call sites. Tests construct clients directly via a mock source.
|
||||
- Modify: ~30 test sites in `lib/crates/fabro-llm/src/generate.rs` — use a helper `#[cfg(test)] fn test_params(model: &str) -> GenerateParams` that constructs a mock client.
|
||||
- Test: new negative test — attempting to build `GenerateParams` without a client is a compile error (trybuild or inspection).
|
||||
|
||||
**Approach:**
|
||||
- Introduce the test helper first, then swap sites mechanically.
|
||||
- `GenerateParams` spread patterns (`GenerateParams { response_format: ..., ..params }`) continue to work since `client` is a field with a value being propagated.
|
||||
- `MockProvider` in `pull_request.rs` keeps its `name` field (added by PR #168) — useful for the regression test where one mock is registered under the "openai" provider name.
|
||||
|
||||
**Test scenarios:**
|
||||
- Compile-time enforcement: `GenerateParams::new(model)` without a client arg fails to compile (by the struct shape).
|
||||
- All existing `fabro-llm` generate tests pass with `test_params(model)` swap.
|
||||
- Regression (pipeline-level): workflow with vault-only `openai_codex` runs to completion and generates a PR body using vault-resolved credentials. (This is the class-bug fix from PR #168, now type-enforced.)
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `rg 'DEFAULT_CLIENT|set_default_client|get_default_client|install_mock_llm|Client::from_env' lib/crates/` — zero hits.
|
||||
- `rg 'Option<Arc<Client>>' lib/crates/` — zero hits in production code.
|
||||
|
||||
### Phase 2 — `RunServices` split + PR #168 `Option<Client>` unwind
|
||||
|
||||
**Prerequisite:** PR #168 must have merged to main.
|
||||
|
||||
- [x] **Unit 2.1: Introduce `RunServices` + `EngineServices` split**
|
||||
|
||||
**Goal:** Today's `EngineServices` (13 fields, mixed lifetimes) partitions into cross-phase `RunServices` + execute-only `EngineServices`. Handlers read cross-phase state as `services.run.xxx`.
|
||||
|
||||
**Requirements:** R4.
|
||||
|
||||
**Dependencies:** Phase 1 complete.
|
||||
|
||||
**Files:**
|
||||
- Create: `lib/crates/fabro-workflow/src/services.rs` (both structs + `RunServices::for_test`)
|
||||
- Modify: `lib/crates/fabro-workflow/src/handler/mod.rs` — delete old `EngineServices`; re-export from `services`.
|
||||
- Modify: `lib/crates/fabro-workflow/src/handler/{parallel,manager_loop,prompt,agent,command,fan_in,human}.rs` — mechanical rewrite: `services.run_store` → `services.run.run_store`, etc.
|
||||
- Modify: `lib/crates/fabro-workflow/src/node_handler.rs` — same rewrites.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/initialize.rs` — `build_registry` now returns `Arc<EngineServices>` (holding `Arc<RunServices>` with `llm_source`). Dry-run still produces a valid services pair.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/execute.rs` — use `Arc<EngineServices>` directly instead of reconstructing it.
|
||||
- Modify: `lib/crates/fabro-workflow/src/test_support.rs` — test fixture adapts.
|
||||
- Test: handler unit tests and `fabro-workflow/tests/it/integration.rs` pipeline tests.
|
||||
|
||||
**Approach:**
|
||||
|
||||
| Field | Lives on |
|
||||
|---|---|
|
||||
| `run_store` | `RunServices` |
|
||||
| `emitter` | `RunServices` |
|
||||
| `sandbox` | `RunServices` |
|
||||
| `hook_runner` | `RunServices` |
|
||||
| `cancel_requested` | `RunServices` |
|
||||
| `provider` | `RunServices` |
|
||||
| `llm_source` | `RunServices` (**new**) |
|
||||
| `registry` | `EngineServices` |
|
||||
| `inputs` | `EngineServices` |
|
||||
| `workflow_bundle` | `EngineServices` |
|
||||
| `workflow_path` | `EngineServices` |
|
||||
| `dry_run` | `EngineServices` |
|
||||
| `env` | `EngineServices` |
|
||||
| `git_state` | `EngineServices` |
|
||||
|
||||
- `RunServices::for_test() -> Arc<Self>` builds a minimal services bundle with a stub source. Used by handler and pipeline tests.
|
||||
- No delegation methods on `EngineServices`; handlers read through `services.run.xxx` explicitly. More lines but clearer boundary.
|
||||
|
||||
**Patterns to follow:**
|
||||
- Existing `Arc<EngineServices>` construction at `pipeline/execute.rs:84`.
|
||||
|
||||
**Test scenarios:**
|
||||
- Happy path: `RunServices::for_test()` constructs cleanly and supports all handler unit tests.
|
||||
- Happy path: end-to-end pipeline test runs without regression.
|
||||
- Type-level: a retro-phase test asserting `services.run.emitter` compiles but `services.registry` does not (via a compile-fail test or a comment marker).
|
||||
- Edge case: `services.run_hooks(&HookContext)` method lives on `RunServices` since `hook_runner` moved there.
|
||||
- Edge case: `services.git_state()` / `set_git_state(...)` stays on `EngineServices` (execute-only).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run -p fabro-workflow` passes.
|
||||
- `cargo clippy -p fabro-workflow --all-targets -- -D warnings` clean.
|
||||
- `rg 'services\.run_store' lib/crates/fabro-workflow/src/handler/` — zero hits (all now `services.run.run_store`).
|
||||
|
||||
- [x] **Unit 2.2: Shrink phase structs; unwind PR #168 `Option<Client>`**
|
||||
|
||||
**Goal:** `Initialized`/`Executed` carry `Arc<EngineServices>`; `Retroed`/`Concluded` carry `Arc<RunServices>`. Delete `Option<Client>` threading introduced by PR #168.
|
||||
|
||||
**Requirements:** R4, R5.
|
||||
|
||||
**Dependencies:** Unit 2.1 + PR #168 merged.
|
||||
|
||||
**Files:**
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/types.rs` — shrink phase structs (below), shrink Options structs.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/execute.rs` — destructure updates (carry `engine`).
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/retro.rs` — read `executed.engine.run`; drop `options.llm_client`.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/finalize.rs` — destructure updates.
|
||||
- Modify: `lib/crates/fabro-workflow/src/pipeline/pull_request.rs` — drop `Option<Client>` parameter from `build_pr_body`/`maybe_open_pull_request`/`pull_request`; build via `Client::from_source(&services.run.llm_source)`.
|
||||
- Modify: `lib/crates/fabro-workflow/src/operations/start.rs` — `RunSession::run` threads services Arc through phase calls (no longer cloning `executed.llm_client`).
|
||||
- Modify: `lib/crates/fabro-cli/src/commands/pr/create.rs` — build `RunServices::for_cli(source, run_store, ...)` and pass to `maybe_open_pull_request`.
|
||||
- Test: `lib/crates/fabro-workflow/tests/it/integration.rs` pipeline-level regression; update phase-level tests.
|
||||
|
||||
**Approach — phase structs after the split:**
|
||||
|
||||
- `Initialized { graph, source, inputs, run_options, workflow_path, workflow_bundle, checkpoint, seed_context, engine: Arc<EngineServices>, model }`
|
||||
- `Executed { graph, outcome, run_options, duration_ms, final_context, engine: Arc<EngineServices>, model }`
|
||||
- `Retroed { graph, outcome, run_options, duration_ms, retro, services: Arc<RunServices> }`
|
||||
- `Concluded { run_id, outcome, conclusion, pushed_branch, graph, run_options, services: Arc<RunServices> }`
|
||||
- `Finalized { run_id, outcome, conclusion, pushed_branch, pr_url }` (unchanged, terminal)
|
||||
- `RetroOptions` drops `llm_client`, `provider`, `sandbox`, `run_store`, `emitter` (read from services); keeps `run_id`, `workflow_name`, `goal`, `run_dir`, `failed`, `run_duration_ms`, `enabled`, `model`.
|
||||
- `PullRequestOptions` drops `run_store`; keeps `run_dir`, `pr_config`, `github_app`, `origin_url`, `model`.
|
||||
- `build_pr_body(services: &RunServices, diff, goal, model, conclusion) -> Result<String, String>` — builds client via `Client::from_source(&services.llm_source)`.
|
||||
|
||||
All phase structs retain `#[non_exhaustive]` (already present).
|
||||
|
||||
**Patterns to follow:**
|
||||
- Unit 2.1's `Arc<EngineServices>` shape.
|
||||
|
||||
**Test scenarios:**
|
||||
- Regression (the R5 pipeline-level test): workflow run with vault-configured `openai_codex`, no `OPENAI_API_KEY` env, generates a PR body successfully. Previously failed with "Provider 'openai' not registered."
|
||||
- Happy path: CLI `fabro pr create` resolves vault, builds source, builds `RunServices::for_cli`, calls `maybe_open_pull_request`.
|
||||
- Edge case: retro when disabled still no-ops (doesn't call `from_source`).
|
||||
- Edge case: workflow with no LLM stages and no vault initializes cleanly (source built from vault; `Client::from_source` is called lazily by consumers, not eagerly).
|
||||
|
||||
**Verification:**
|
||||
- `cargo nextest run --workspace` passes.
|
||||
- `rg 'llm_client:' lib/crates/fabro-workflow/` — zero hits in non-test code.
|
||||
- `rg 'Option<Client>' lib/crates/` — zero production hits.
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph:** Every `generate`/`generate_object`/`stream_generate` consumer is affected — `fabro-workflow`, `fabro-hooks`, `fabro-agent`, `fabro-cli`, `fabro-server`. Each now builds its client from a source it already holds.
|
||||
- **Error propagation:** Source-resolution errors (vault lookup failure, OAuth refresh failure) surface at `Client::from_source` call sites, which is the same point they surface today at `build_llm_client` call sites. Error semantics preserved.
|
||||
- **State lifecycle risks:** `Client::from_source` builds a fresh client per call. For most contexts this runs once per long-running operation (per session, per PR body, per hook invocation). The cost is identical to today's `build_llm_client(resolver)` pattern — unchanged.
|
||||
- **API surface parity:** `fabro_llm::set_default_client` re-export deletes. `GenerateParams::new` signature changes. `Client::from_env` deletes. Internal-only API shape changes; no external consumers in this monorepo.
|
||||
- **Integration coverage:** R5's pipeline-level regression test (Unit 2.2) is the critical insurance — proves the class bug is closed at the pipeline shape level, not just at one unit.
|
||||
- **Credential trust boundary:** `RunServices.llm_source` is shared across all phases by design. Workflow stages run against the same vault as retro/PR body — which matches today's behavior. Callers deploying for multi-tenant workflows must not mix trust levels in a single run. Per-phase credential scoping is out of scope.
|
||||
- **Unchanged invariants:** `Vault`, `CredentialResolver`, `ApiCredential`, `Provider::ALL`, `ResolvedCredential` enum, phase ordering, `#[non_exhaustive]` on all phase structs, OAuth refresh behavior.
|
||||
|
||||
## Risks & Dependencies
|
||||
|
||||
| Risk | Mitigation |
|
||||
|---|---|
|
||||
| PR #168 lands with `Option<Client>` threading that Phase 2 needs to unwind. If PR #168 stalls, Phase 2 blocks. | Phase 1 is independent of PR #168 and can land first. Phase 2 starts when PR #168 merges. |
|
||||
| 30+ `GenerateParams::new("mock-model")` test sites in `fabro-llm/src/generate.rs`. | Introduce `test_params(model)` helper before migrating sites; one-line edits thereafter (Unit 1.3). |
|
||||
| Phase struct destructure patterns in `pipeline/execute.rs`, `pipeline/retro.rs`, `pipeline/finalize.rs` break when struct shape changes. | Unit 2.2 updates them explicitly. `#[non_exhaustive]` protects external crates; in-crate destructures adjust. |
|
||||
| Server `ProviderCredentials` owns two capabilities (`build_llm_client` + `configured_providers`). Consolidation must preserve both. | Unit 1.2 parity tests on both paths: `resolve()` vs today's `build_llm_client()` (credentials + auth_issues), and `configured_providers()` vs today's `configured_providers()`, against the same fixture vault + env policy. Reconcile any divergence before deletion. |
|
||||
| `SandboxReady` hooks today have no client; tomorrow they call `Client::from_source(&source)` on demand. Construction cost per hook. | Source already holds the resolver; `source.resolve()` is the same cost as today's `build_llm_client` call that would happen anyway if a hook wanted to generate. No net regression. |
|
||||
| `AgentApiBackend` per-session client rebuild is load-bearing for OAuth refresh. | Preserved verbatim: backend holds source, calls `Client::from_source(&source)` per session. `source.resolve()` → `resolver.resolve()` → OAuth refresh. Identical behavior. |
|
||||
|
||||
## Documentation / Operational Notes
|
||||
|
||||
- Add a short strategy doc at `docs-internal/llm-client-resolution.md` describing the source-on-context rule: `fabro-auth::CredentialSource` is the authority, `Client` is always derived via `Client::from_source`, `generate()` requires an explicit client. Reference `docs-internal/server-secrets-strategy.md` for the adjacent "no `from_env` in production paths" enforcement model.
|
||||
- A future follow-up should create a `docs/solutions/` entry capturing "pipeline boundary drop" as a pattern learning. Out of scope for this plan.
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Related PR:** #168 (`fix(workflow): reuse resolved llm client for auto-pr`) — the point fix this refactor replaces.
|
||||
- **Related plans:**
|
||||
- `docs/plans/2026-04-20-002-refactor-extract-fabro-client-crate-plan.md` — `CredentialFallback` named-trait precedent.
|
||||
- `docs/plans/2026-04-05-server-canonical-secrets-doctor-repo-plan.md` — `from_env()` smell pre-flagged.
|
||||
- `docs/plans/2026-04-22-003-refactor-lock-down-server-secrets-plan.md` — credential taxonomy.
|
||||
- `docs/plans/2026-04-08-cli-services-command-context-refactor-plan.md`, `docs/plans/2026-04-23-001-refactor-command-context-alignment-plan.md` — "no peer wrapper" precedent (addressed in Key Technical Decisions).
|
||||
- **Strategy docs:**
|
||||
- `docs-internal/server-secrets-strategy.md` — the `set_var`/`remove_var` enforcement model is precedent for enforcing "no `from_env` in production paths."
|
||||
- **Target files:** `lib/crates/fabro-llm/`, `lib/crates/fabro-auth/`, `lib/crates/fabro-workflow/`, `lib/crates/fabro-cli/`, `lib/crates/fabro-server/`, `lib/crates/fabro-hooks/`, `lib/crates/fabro-agent/`.
|
||||
|
||||
## Unresolved questions
|
||||
|
||||
- **`docs/solutions/` seeding** — out of scope for this plan; flagged as a follow-up.
|
||||
- **Observability** — should `VaultCredentialSource::resolve` emit a tracing event on successful resolution? Low-value, but worth deciding while implementing.
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Reference in a new issue