diff --git a/.chisel/cartography/codebase-map.json b/.chisel/cartography/codebase-map.json new file mode 100644 index 000000000..42b523f3f --- /dev/null +++ b/.chisel/cartography/codebase-map.json @@ -0,0 +1,926 @@ +{ + "schema_version": 1, + "cartography_version": 1, + "created_at": "2026-07-27T14:07:02Z", + "repository": { + "name": "fabro", + "root": ".", + "revision": "2bcf94fed8a9b429f18d9196fa824711d6f4cb0a", + "short_revision": "2bcf94fed" + }, + "instructions": [ + "AGENTS.md", + "CLAUDE.md", + "CONTRIBUTING.md" + ], + "overview": "Fabro is a Cargo workspace whose CLI and HTTP server compose shared workflow, agent, model, sandbox, persistence, integration, and foundation crates. A Bun workspace contains the React web application, Astro marketing site, Remotion composition, and OpenAPI-derived TypeScript client tooling; the OpenAPI document is the shared HTTP contract. Public and internal documentation, protocol twins, fixture corpora, evaluation tooling, build/release/deployment automation, and repository-local agent workflows form separate support boundaries around the product runtime.", + "global_exclusions": [ + { + "globs": [ + "lib/packages/fabro-api-client/src/**" + ], + "reason": "Generated TypeScript/Axios output written by the package's pinned OpenAPI Generator command; generated headers and .openapi-generator metadata corroborate the output boundary." + }, + { + "globs": [ + "apps/marketing/.vercel/**" + ], + "reason": "Vercel CLI link metadata whose own README identifies it as automatically created local project/team state." + }, + { + "globs": [ + "lib/apps/fabro-spa/assets/**" + ], + "reason": "Placeholder for ignored embedded-SPA build output; repository instructions and .gitignore identify the directory as generated." + }, + { + "globs": [ + "docs/brainstorms/**", + "docs/ideation/**", + "docs/plans/**", + "docs/superpowers/plans/**", + "docs/superpowers/specs/**", + "docs/internal/cargo-target-apfs-churn-plan.md", + "docs/internal/cli-workflow-coupling-audit.md", + "docs/internal/event-schema-competitive-analysis.md", + "docs/internal/fabro-event-schema-v2-proposal.md", + "docs/internal/mcp-server-qa-test-plan.md", + "docs/internal/plan-events-as-source-of-truth-follow-ups.md", + "docs/internal/plan-events-as-source-of-truth.md", + "docs/internal/slow-test-opportunities-2026-04-07.md" + ], + "reason": "Point-in-time brainstorms, implementation plans, audits, research, handoffs, and superseded proposals rather than maintained source contracts." + }, + { + "globs": [ + "docs/internal/demo/*.svg", + "docs/internal/demo/*.png", + "docs/public/images/*-workflow.svg", + "docs/public/images/tutorial-*.svg", + "docs/public/images/brave-search-research.svg", + "docs/public/images/how-fabro-works.svg", + "docs/public/images/nlspec-conformance.svg", + "docs/public/images/plan-implement-readme.svg" + ], + "reason": "Graphviz-generated SVG and PNG renderings whose executable or documentation graph sources remain assigned." + }, + { + "globs": [ + "docs/internal/licenses/**" + ], + "reason": "Vendored third-party Graphviz license text rather than Fabro source." + }, + { + "globs": [ + "evals/swe-bench/scoreboard/**" + ], + "reason": "Committed evaluation records generated by record_results.py, not executable evaluation source." + }, + { + "globs": [ + ".fabro/skills/rust-style-guide/**" + ], + "reason": "Vendored policy payload copied from the brynary/rust-style-guide repository at a recorded commit." + }, + { + "globs": [ + "Cargo.lock", + "bun.lock" + ], + "reason": "Machine-maintained dependency resolution snapshots consumed in locked or frozen mode." + }, + { + "globs": [ + ".claude/skills/*/watermark" + ], + "reason": "Generated progress-state commit SHAs overwritten by the owning skill workflows." + }, + { + "globs": [ + ".fabro/project.toml.bak" + ], + "reason": "Stale backup of the canonical .fabro/project.toml configuration." + }, + { + "globs": [ + ".fabro/workflows/goal/workflow.svg", + ".github/assets/**" + ], + "reason": "Non-runtime workflow illustration and unreferenced pull-request review screenshots." + }, + { + "globs": [ + "CLAUDE.md", + "install.sh", + "install.md" + ], + "reason": "Tracked symlink aliases whose canonical targets are assigned elsewhere, avoiding duplicate assessment of identical content." + }, + { + "globs": [ + "LICENSE.md" + ], + "reason": "Repository legal text rather than an implementation or documentation component." + } + ], + "components": [ + { + "id": "fabro-cli", + "name": "Fabro CLI Application", + "purpose": "Provides the fabro command-line process, command dispatch, terminal presentation, server bootstrap, and hidden run-worker entry.", + "globs": ["lib/apps/fabro-cli/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-cli/src/main.rs:main", "lib/apps/fabro-cli/src/args.rs:Commands"], + "owns": ["CLI process and command lifecycle, output contracts, command context, local server discovery, and the run-worker subprocess entry"], + "depends_on": ["fabro-acp", "fabro-agent", "fabro-api", "fabro-auth", "fabro-build-support", "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-mcp-server", "fabro-model", "fabro-oauth", "fabro-proc", "fabro-redact", "fabro-sandbox", "fabro-server", "fabro-static", "fabro-store", "fabro-telemetry", "fabro-template", "fabro-tool", "fabro-types", "fabro-util", "fabro-validate", "fabro-vault", "fabro-workflow", "workflow-test-corpus"], + "evidence": ["lib/apps/fabro-cli/Cargo.toml — declares the fabro binary and its direct workspace dependencies", "lib/apps/fabro-cli/src/main.rs:main_inner — constructs shared command state and dispatches the complete command surface"] + }, + { + "id": "fabro-mcp-server", + "name": "Fabro MCP Stdio Server", + "purpose": "Exposes Fabro run operations as an MCP stdio tool service and generates supported MCP client configuration.", + "globs": ["lib/apps/fabro-mcp-server/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-mcp-server/src/lib.rs:start", "lib/apps/fabro-mcp-server/src/config.rs:init_agent"], + "owns": ["MCP stdio service lifecycle, tool router, lazy Fabro client backend, and MCP client configuration updates"], + "depends_on": ["fabro-api", "fabro-client", "fabro-config", "fabro-manifest", "fabro-model", "fabro-server", "fabro-tool", "fabro-types", "fabro-util"], + "evidence": ["lib/apps/fabro-mcp-server/Cargo.toml — declares a distinct MCP server library package", "lib/apps/fabro-mcp-server/src/server.rs:start — owns the rmcp stdio service lifecycle"] + }, + { + "id": "fabro-server", + "name": "Fabro HTTP Server", + "purpose": "Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, workers, schedulers, sessions, authentication, and integrations.", + "globs": ["lib/apps/fabro-server/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-server/src/serve.rs:serve_command", "lib/apps/fabro-server/src/server.rs:build_router"], + "owns": ["Server startup and shutdown, AppState, API and web routing, authentication, scheduling, worker control, and integration coordination"], + "depends_on": ["fabro-agent", "fabro-api", "fabro-auth", "fabro-automation", "fabro-build-support", "fabro-client", "fabro-config", "fabro-db", "fabro-environment", "fabro-github", "fabro-graphviz", "fabro-hooks", "fabro-http", "fabro-http-api-contract", "fabro-install", "fabro-interview", "fabro-llm", "fabro-manifest", "fabro-mcp-store", "fabro-model", "fabro-proc", "fabro-redact", "fabro-sandbox", "fabro-slack", "fabro-spa", "fabro-static", "fabro-store", "fabro-tool", "fabro-types", "fabro-util", "fabro-validate", "fabro-variable", "fabro-vault", "fabro-workflow"], + "evidence": ["lib/apps/fabro-server/Cargo.toml — declares the HTTP server package and its application dependencies", "lib/apps/fabro-server/src/server.rs:AppState — centralizes the service's stores, runtimes, schedulers, credentials, integrations, and shutdown state"] + }, + { + "id": "fabro-spa", + "name": "Embedded SPA Assets", + "purpose": "Provides compile-time embedded production SPA lookup, bytes, and content hashes to the Rust server.", + "globs": ["lib/apps/fabro-spa/Cargo.toml", "lib/apps/fabro-spa/src/**"], + "exclude_globs": [], + "entry_points": ["lib/apps/fabro-spa/src/lib.rs:get", "lib/apps/fabro-spa/src/lib.rs:AssetBytes"], + "owns": ["Compile-time SPA embedding, asset lookup, byte and hash metadata, and source-map exclusion"], + "depends_on": [], + "evidence": ["lib/apps/fabro-spa/Cargo.toml — declares a distinct embedded-assets package", "lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets — defines compile-time asset embedding and lookup", "lib/apps/fabro-server/src/static_files.rs — consumes the embedded asset interface"] + }, + { + "id": "fabro-acp", + "name": "Agent Client Protocol Runtime", + "purpose": "Launches and controls Agent Client Protocol processes through Fabro sandboxes and translates their sessions into run results.", + "globs": ["lib/components/fabro-acp/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-acp/src/command.rs:AcpProcessSpec", "lib/components/fabro-acp/src/session.rs:run_acp_turn"], + "owns": ["ACP process specifications, transport and session lifetime, live steering, cancellation, and exit translation"], + "depends_on": ["fabro-sandbox", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-acp/Cargo.toml — declares the ACP backend and optional sandbox runtime edge", "lib/components/fabro-acp/tests/session.rs — exercises the ACP session boundary"] + }, + { + "id": "fabro-agent", + "name": "Coding Agent Runtime", + "purpose": "Runs programmable coding-agent sessions with model profiles, context management, native and MCP tools, permissions, and subagents.", + "globs": ["lib/components/fabro-agent/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-agent/src/session.rs:Session", "lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry"], + "owns": ["Agent session history, prompts and profiles, tool execution, context compaction, permissions, questions, todos, and subagents"], + "depends_on": ["fabro-auth", "fabro-config", "fabro-http", "fabro-llm", "fabro-mcp", "fabro-model", "fabro-sandbox", "fabro-static", "fabro-template", "fabro-types", "fabro-util", "fabro-vault"], + "evidence": ["lib/components/fabro-agent/Cargo.toml — describes a programmable agentic loop and its runtime dependencies", "lib/components/fabro-agent/src/lib.rs — exposes the session, profile, tool, permission, history, and subagent facade"] + }, + { + "id": "fabro-automation", + "name": "Automation Definitions and Storage", + "purpose": "Validates, versions, imports, and durably stores scheduled, API-triggered, and manual automation definitions.", + "globs": ["lib/components/fabro-automation/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-automation/src/store.rs:AutomationStore", "lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once"], + "owns": ["Automation identifiers, targets, triggers, revisions, SQLite records, and legacy import"], + "depends_on": ["fabro-db"], + "evidence": ["lib/components/fabro-automation/Cargo.toml — declares the automation domain and durable storage boundary", "lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs — evolves the owned persistence format"] + }, + { + "id": "fabro-checkpoint", + "name": "Git Checkpoint Storage", + "purpose": "Stores 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/branch.rs:BranchStore", "lib/components/fabro-checkpoint/src/git.rs:Store"], + "owns": ["Checkpoint commits, Git trees, metadata branches, authorship, trailers, and checkpoint errors"], + "depends_on": ["fabro-config", "fabro-store", "fabro-types"], + "evidence": ["lib/components/fabro-checkpoint/Cargo.toml — identifies Git-backed workflow checkpoint storage", "lib/components/fabro-checkpoint/src/lib.rs — exposes the branch, Git, author, trailer, and error surface"] + }, + { + "id": "fabro-dump", + "name": "Run Dump Materialization", + "purpose": "Materializes stored run projections, events, checkpoints, artifacts, and 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::write_to_dir"], + "owns": ["Dump layout, stage ranking, blob hydration, serialization, and directory writing"], + "depends_on": ["fabro-store", "fabro-types"], + "evidence": ["lib/components/fabro-dump/Cargo.toml — gives the operation a distinct crate and storage dependency", "lib/components/fabro-dump/src/lib.rs:RunDump — contains the public dump-building lifecycle"] + }, + { + "id": "fabro-environment", + "name": "Environment Definitions and Storage", + "purpose": "Validates, seeds, versions, imports, and durably stores server-owned execution environment definitions.", + "globs": ["lib/components/fabro-environment/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-environment/src/store.rs:EnvironmentStore", "lib/components/fabro-environment/src/store.rs:seed_default_environment"], + "owns": ["Environment identifiers, revisions, drafts, SQLite records, built-in seeding, and legacy import"], + "depends_on": ["fabro-config", "fabro-db", "fabro-types"], + "evidence": ["lib/components/fabro-environment/Cargo.toml — declares a server-owned environment domain and store", "lib/components/fabro-environment/tests/store.rs — exercises the independent persistence boundary"] + }, + { + "id": "fabro-github", + "name": "GitHub Authentication and API", + "purpose": "Resolves GitHub credentials and performs authenticated App, repository, branch, and pull-request 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:create_pull_request"], + "owns": ["GitHub credentials and token minting, API translation, repository URL handling, and pull-request lifecycle calls"], + "depends_on": ["fabro-http", "fabro-redact", "fabro-static", "fabro-types"], + "evidence": ["lib/components/fabro-github/Cargo.toml — describes the GitHub App authentication and API adapter", "lib/components/fabro-github/src/lib.rs:GitHubContext — defines the credential context and testable HTTP boundary"] + }, + { + "id": "fabro-graphviz", + "name": "Workflow Graph Language", + "purpose": "Parses Graphviz DOT into Fabro's typed graph model and handles conditions, stylesheets, fidelity, and graph rendering.", + "globs": ["lib/components/fabro-graphviz/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-graphviz/src/parser/mod.rs:parse", "lib/components/fabro-graphviz/src/render.rs:render_dot"], + "owns": ["DOT lexer, parser, semantic conversion, graph errors, condition and stylesheet syntax, and rendering normalization"], + "depends_on": ["fabro-types", "workflow-test-corpus"], + "evidence": ["lib/components/fabro-graphviz/Cargo.toml — names the crate as the DOT parser and graph data model", "lib/components/fabro-graphviz/src/parser/mod.rs:parse — is the source-to-typed-graph entry point"] + }, + { + "id": "fabro-hooks", + "name": "Workflow Lifecycle Hooks", + "purpose": "Configures and executes user-defined workflow hooks and bridges tool hooks into the agent runtime.", + "globs": ["lib/components/fabro-hooks/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-hooks/src/runner.rs:HookRunner", "lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback"], + "owns": ["Hook definitions and selection, execution context, result merging, command and HTTP dispatch, and agent bridging"], + "depends_on": ["fabro-agent", "fabro-auth", "fabro-http", "fabro-llm", "fabro-model", "fabro-redact", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-hooks/Cargo.toml — identifies the workflow hook boundary and runtime dependencies", "lib/components/fabro-hooks/tests/host_command_hooks.rs — tests host hooks through the public lifecycle"] + }, + { + "id": "fabro-install", + "name": "Installation Persistence", + "purpose": "Prepares, persists, and rolls 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"], + "owns": ["Install persistence plans, settings and environment mutations, vault writes, development tokens, and rollback"], + "depends_on": ["fabro-config", "fabro-db", "fabro-environment", "fabro-static", "fabro-types", "fabro-util", "fabro-vault"], + "evidence": ["lib/components/fabro-install/Cargo.toml — declares shared install primitives for CLI and server", "lib/components/fabro-install/src/lib.rs:InstallPersistencePlan — groups the files, tokens, and vault state committed by one install"] + }, + { + "id": "fabro-interview", + "name": "Human Interaction Runtime", + "purpose": "Represents workflow questions and answers and provides 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/control.rs:ControlInterviewer"], + "owns": ["Question and answer protocol, interviewer request lifetime, timeout behavior, delivery, recording, and replay"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-interview/Cargo.toml — defines interviewer traits and implementations as one crate", "lib/components/fabro-interview/src/lib.rs:Interviewer — is the shared asynchronous human-interaction interface"] + }, + { + "id": "fabro-llm", + "name": "Unified LLM Client", + "purpose": "Provides a provider-neutral generation API with routing, middleware, retries, token and cost accounting, provider adapters, and wire codecs.", + "globs": ["lib/components/fabro-llm/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-llm/src/client.rs:Client", "lib/components/fabro-llm/src/provider.rs:ProviderAdapter"], + "owns": ["Normalized generation types, adapter registry, provider authentication and transport, codecs, retries, middleware, and accounting"], + "depends_on": ["fabro-auth", "fabro-http", "fabro-model", "fabro-redact", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-llm/Cargo.toml — declares the unified multi-provider client", "lib/components/fabro-llm/tests/it/wire/mod.rs — verifies provider codecs against one normalized boundary"] + }, + { + "id": "fabro-manifest", + "name": "Run Manifest Construction", + "purpose": "Resolves workflow and configuration inputs, collects static dependencies, and constructs self-contained run manifests 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:ManifestBuildInput"], + "owns": ["Manifest input and output, configuration resolution, workflow dependency collection, Git context, and pre-run push preparation"], + "depends_on": ["fabro-api", "fabro-config", "fabro-github", "fabro-graphviz", "fabro-template", "fabro-types", "fabro-workflow"], + "evidence": ["lib/components/fabro-manifest/Cargo.toml — declares manifest construction and its graph, Git, and workflow dependencies", "lib/components/fabro-manifest/src/lib.rs:build_run_manifest — is the shared assembly operation used by CLI, server, and MCP server"] + }, + { + "id": "fabro-mcp", + "name": "MCP Client Runtime", + "purpose": "Connects to configured Model Context Protocol servers, manages connections, discovers tools, and dispatches qualified calls.", + "globs": ["lib/components/fabro-mcp/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-mcp/src/client.rs:McpClient", "lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager"], + "owns": ["MCP client connections, stdio and HTTP transports, connection-manager state, tool discovery, and result conversion"], + "depends_on": ["fabro-config", "fabro-http", "fabro-types"], + "evidence": ["lib/components/fabro-mcp/Cargo.toml — declares the MCP client and transport features", "lib/components/fabro-mcp/tests/stdio_integration.rs — verifies the external process boundary over stdio"] + }, + { + "id": "fabro-mcp-store", + "name": "MCP Server Catalog Storage", + "purpose": "Durably stores, revisions, caches, and imports server-managed MCP server definitions.", + "globs": ["lib/components/fabro-mcp-store/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-mcp-store/src/store.rs:McpServerStore", "lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once"], + "owns": ["MCP definition records, optimistic revisions, catalog cache, and legacy directory import"], + "depends_on": ["fabro-db", "fabro-types"], + "evidence": ["lib/components/fabro-mcp-store/Cargo.toml — declares durable MCP catalog storage", "lib/components/fabro-mcp-store/src/lib.rs — explicitly assigns persistence ownership to this crate"] + }, + { + "id": "fabro-sandbox", + "name": "Execution Sandbox Abstraction", + "purpose": "Defines sandbox and provider contracts and implements local, Docker, and Daytona execution lifecycles.", + "globs": ["lib/components/fabro-sandbox/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-sandbox/src/sandbox.rs:Sandbox", "lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry"], + "owns": ["Sandbox filesystem, process, and terminal interface; provider lifecycle; clone setup; reconnect behavior; and provider implementations"], + "depends_on": ["fabro-config", "fabro-github", "fabro-http", "fabro-proc", "fabro-redact", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-sandbox/Cargo.toml — defines provider features around a common sandbox crate", "lib/components/fabro-sandbox/src/provider.rs:SandboxProvider — separates provider lifecycle from per-sandbox operations"] + }, + { + "id": "fabro-slack", + "name": "Slack Interaction Integration", + "purpose": "Connects to Slack Socket Mode and translates questions, answers, run events, and threads 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"], + "owns": ["Slack credentials, Socket Mode lifecycle, API client, block rendering, payload parsing, thread registry, and dispatch"], + "depends_on": ["fabro-http", "fabro-interview", "fabro-static", "fabro-types", "fabro-workflow"], + "evidence": ["lib/components/fabro-slack/Cargo.toml — declares the Slack interviewer integration", "lib/components/fabro-slack/src/connection.rs:run — owns the Socket Mode event loop"] + }, + { + "id": "fabro-store", + "name": "Run and Authentication Persistence", + "purpose": "Persists run events, projections, blobs, artifacts, summaries, catalog indexes, and authentication grants over SlateDB, object storage, and SQLite.", + "globs": ["lib/components/fabro-store/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-store/src/slate/mod.rs:Database", "lib/components/fabro-store/src/run_state.rs:RunProjectionReducer"], + "owns": ["Run event and projection lifecycle, blob and artifact layout, summary indexes, auth records, locking, and storage errors"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-store/src/lib.rs — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth", "lib/components/fabro-store/src/slate/mod.rs:Database — is the shared storage root for the owned stores"] + }, + { + "id": "fabro-tool", + "name": "Run-Control Tools", + "purpose": "Defines and executes 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/common.rs:FabroToolBackend", "lib/components/fabro-tool/src/common.rs:tool_definitions"], + "owns": ["Tool names and schemas, parameter validation, backend-neutral operations, result records, and text rendering"], + "depends_on": ["fabro-api", "fabro-client", "fabro-types", "fabro-util"], + "evidence": ["lib/components/fabro-tool/Cargo.toml — identifies shared run-control tool behavior over API/client contracts", "lib/components/fabro-tool/src/common.rs:FabroToolBackend — is the abstraction shared by CLI, server, workflow, and MCP server"] + }, + { + "id": "fabro-tracker", + "name": "Issue Tracker Adapters", + "purpose": "Provides 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"], + "owns": ["Normalized issues and blockers, candidate selection and transitions, and GitHub Projects and Linear GraphQL adapters"], + "depends_on": ["fabro-github", "fabro-http"], + "evidence": ["lib/components/fabro-tracker/Cargo.toml — declares the tracker trait and provider adapters", "lib/components/fabro-tracker/src/lib.rs:Tracker — defines the provider-neutral issue workflow"] + }, + { + "id": "fabro-validate", + "name": "Workflow Graph Validation", + "purpose": "Runs built-in and catalog-aware lint rules over typed workflow graphs and returns 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:LintRule"], + "owns": ["Validation diagnostics, rule interface and registry, graph and catalog traversal, and error escalation"], + "depends_on": ["fabro-acp", "fabro-graphviz", "fabro-model", "fabro-types", "workflow-test-corpus"], + "evidence": ["lib/components/fabro-validate/Cargo.toml — declares graph validation and its graph/catalog dependencies", "lib/components/fabro-validate/src/rules/mod.rs:built_in_rules — forms the explicit built-in rule registry"] + }, + { + "id": "fabro-variable", + "name": "Workflow Variable Storage", + "purpose": "Validates, durably stores, snapshots, and imports 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:import_legacy_json_once"], + "owns": ["Variable validation, SQLite records, render-context snapshots, and legacy JSON import"], + "depends_on": ["fabro-db", "fabro-types"], + "evidence": ["lib/components/fabro-variable/Cargo.toml — defines workflow-visible variables as a storage concern", "lib/components/fabro-variable/tests/store.rs — verifies its independent persistence and import contract"] + }, + { + "id": "fabro-workflow", + "name": "Workflow Orchestration Engine", + "purpose": "Transforms, validates, initializes, executes, persists, resumes, and finalizes graph-defined Fabro runs.", + "globs": ["lib/components/fabro-workflow/**"], + "exclude_globs": [], + "entry_points": ["lib/components/fabro-workflow/src/operations/start.rs:start", "lib/components/fabro-workflow/src/pipeline/execute.rs:execute"], + "owns": ["Run operations, workflow phases, node handlers, run services, events, checkpoints, Git, artifacts, hooks, status, steering, and cancellation"], + "depends_on": ["fabro-acp", "fabro-agent", "fabro-auth", "fabro-checkpoint", "fabro-config", "fabro-core", "fabro-dump", "fabro-github", "fabro-graphviz", "fabro-hooks", "fabro-http", "fabro-interview", "fabro-llm", "fabro-mcp", "fabro-model", "fabro-redact", "fabro-sandbox", "fabro-static", "fabro-store", "fabro-template", "fabro-tool", "fabro-types", "fabro-util", "fabro-validate", "fabro-vault", "workflow-test-corpus"], + "evidence": ["lib/components/fabro-workflow/Cargo.toml — declares the DOT-based runner and component dependencies", "lib/components/fabro-workflow/src/pipeline/mod.rs — exposes the ordered transform, validate, initialize, execute, and finalize phases"] + }, + { + "id": "fabro-build-support", + "name": "Rust Build-Script Support", + "purpose": "Supplies shared compile-time Git and Cargo profile metadata to Fabro application build scripts.", + "globs": ["lib/foundation/build-support/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/build-support/git_metadata.rs:collect_from", "lib/foundation/build-support/git_metadata.rs:cargo_profile"], + "owns": ["Compile-time Git SHA discovery, Cargo rerun paths, and profile discovery"], + "depends_on": [], + "evidence": ["lib/foundation/build-support/Cargo.toml — declares the shared build-support package", "lib/foundation/build-support/git_metadata.rs:BuildGitMetadata — defines build-script Git and profile metadata", "lib/apps/fabro-cli/build.rs — consumes the shared metadata collector", "lib/apps/fabro-server/build.rs — consumes the shared metadata collector"] + }, + { + "id": "fabro-build-tooling", + "name": "Fabro Build and Developer Tooling", + "purpose": "Runs repository build, documentation, SPA, container, benchmark, release, and test-support automation.", + "globs": ["lib/foundation/fabro-dev/**", "test/bin/release_test.sh", "test/analysis/bench-tests-diff.sql"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-dev/src/main.rs:main"], + "owns": ["Developer CLI dispatch, subprocess plans, generated-reference checks, build and release workflows, and benchmark analysis"], + "depends_on": ["container-packaging-and-deployment", "fabro-cli", "fabro-config", "fabro-macros-metadata", "fabro-spa", "fabro-util", "fabro-web-app", "public-documentation", "repository-development-policy"], + "evidence": ["lib/foundation/fabro-dev/src/lib.rs:Command — dispatches build, Docker, docs, release, SPA, and benchmark commands"] + }, + { + "id": "fabro-api", + "name": "Generated Rust API Client", + "purpose": "Generates the low-level Rust HTTP client and API type facade from OpenAPI while reusing canonical product types and verifying wire 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"], + "owns": ["OpenAPI compatibility transformations, generation settings, type replacement map, generated-client facade, and wire/type parity tests"], + "depends_on": ["fabro-automation", "fabro-config", "fabro-environment", "fabro-http-api-contract", "fabro-model", "fabro-types"], + "evidence": ["lib/foundation/fabro-api/build.rs:main — reads the OpenAPI contract and writes generated Rust code to OUT_DIR", "lib/foundation/fabro-api/tests/run_event_round_trip.rs — verifies identity and JSON parity for canonical reused types"] + }, + { + "id": "fabro-auth", + "name": "Provider Credential Resolution", + "purpose": "Resolves provider credentials and headers from environment or vault sources, refreshes OAuth credentials, and drives authentication strategies.", + "globs": ["lib/foundation/fabro-auth/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver", "lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy"], + "owns": ["Credential-source precedence, provider discovery, OAuth refresh and write-back, header interpolation, and interactive auth state"], + "depends_on": ["fabro-http", "fabro-model", "fabro-oauth", "fabro-redact", "fabro-static", "fabro-types", "fabro-vault"], + "evidence": ["lib/foundation/fabro-auth/Cargo.toml — declares typed provider credential resolution", "lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve — composes catalog policy, source lookup, headers, and refresh"] + }, + { + "id": "fabro-client", + "name": "High-Level Fabro Service Client", + "purpose": "Provides an authenticated Fabro service client over HTTP or Unix sockets with endpoint wrappers, SSE streams, refresh, and local auth storage.", + "globs": ["lib/foundation/fabro-client/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect", "lib/foundation/fabro-client/src/target.rs:ServerTarget"], + "owns": ["Connected transport state, operation wrappers, SSE buffering, token refresh, target normalization, and per-server CLI auth files"], + "depends_on": ["fabro-api", "fabro-http", "fabro-model", "fabro-static", "fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-client/Cargo.toml — distinguishes the high-level client from the generated API client", "lib/foundation/fabro-client/src/client.rs:ClientState — owns transport, generated client, token, URL, and refresh coordination"] + }, + { + "id": "fabro-config", + "name": "Layered Configuration and Runtime Paths", + "purpose": "Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical paths.", + "globs": ["lib/foundation/fabro-config/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder", "lib/foundation/fabro-config/src/resolve/mod.rs"], + "owns": ["Source layers and merge semantics, defaults, parsing and validation, migrations, home/storage/runtime paths, daemon, envfile, and logging configuration"], + "depends_on": ["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", "lib/foundation/fabro-config/src/builders.rs — composes defaults and layers into dense runtime settings"] + }, + { + "id": "fabro-core", + "name": "Generic Graph Execution Kernel", + "purpose": "Executes generic directed 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:Executor::run", "lib/foundation/fabro-core/src/handler.rs:NodeHandler"], + "owns": ["Execution state, graph traversal, handler and lifecycle contracts, retry and visit decisions, cancellation, and stall watchdog"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-core/Cargo.toml — identifies a generic kernel without higher-level workflow dependencies", "lib/foundation/fabro-core/src/executor.rs:Executor::run — owns the traversal and execution lifecycle"] + }, + { + "id": "fabro-db", + "name": "Shared SQLite Database Foundation", + "purpose": "Opens and migrates the shared SQLite database, manages rollback snapshots and permissions, and defines the bundled schema.", + "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"], + "owns": ["SQLite pool policy, migration registry, snapshots, backup paths, permissions, tables, and indexes"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-db/Cargo.toml — declares the shared SQLite foundation", "lib/foundation/fabro-db/migrations/2026071101_secrets.sql — is one migration in the compiled shared schema"] + }, + { + "id": "fabro-http", + "name": "Shared HTTP Transport Construction", + "purpose": "Centralizes reqwest type exposure and synchronous and asynchronous HTTP client construction with Fabro 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:test_http_client"], + "owns": ["Approved reqwest facade, proxy-policy resolution, client builders, and deterministic no-proxy test clients"], + "depends_on": ["fabro-static"], + "evidence": ["lib/foundation/fabro-http/Cargo.toml — declares the shared reqwest wrapper", "lib/foundation/fabro-http/src/lib.rs:ProxyPolicy — defines the common transport-construction policy"] + }, + { + "id": "fabro-macros-metadata", + "name": "Compile-Time Macros and Option Metadata", + "purpose": "Supplies Fabro derive and attribute macros plus the runtime option-metadata model used by 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:derive_options_metadata", "lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata"], + "owns": ["Macro expansion for E2E gates, layer combination, and option metadata plus the runtime visitor and option-tree representation"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl — generates implementations against the runtime metadata crate", "lib/foundation/fabro-macros/tests/options_metadata.rs — tests the compiler/runtime pair together"] + }, + { + "id": "fabro-model", + "name": "LLM Model and Provider Catalog", + "purpose": "Defines provider and model identity, capabilities, billing metadata, embedded catalog data, override merging, and 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::select"], + "owns": ["Provider and model IDs, catalog sources and indexes, auth declarations, capabilities, controls, codecs, reasoning, pricing, and billing"], + "depends_on": ["fabro-static"], + "evidence": ["lib/foundation/fabro-model/Cargo.toml — names model metadata and resolution as the crate responsibility", "lib/foundation/fabro-model/src/catalog/providers/openai.toml — is one tracked built-in provider catalog source"] + }, + { + "id": "fabro-oauth", + "name": "OAuth PKCE and Callback Flow", + "purpose": "Implements generic OAuth 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:refresh_token"], + "owns": ["PKCE and state, authorization URLs, callback listener and shutdown, callback validation, exchange, and refresh"], + "depends_on": ["fabro-http", "fabro-redact", "fabro-static", "fabro-util"], + "evidence": ["lib/foundation/fabro-oauth/Cargo.toml — declares a generic OAuth 2.0 PKCE flow", "lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle — owns the ephemeral callback server lifecycle"] + }, + { + "id": "fabro-proc", + "name": "OS Process Primitives", + "purpose": "Wraps platform process primitives for signals, groups, advisory locks, pre-exec hooks, liveness, and process-title rewriting.", + "globs": ["lib/foundation/fabro-proc/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-proc/src/signal.rs:process_running", "lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid"], + "owns": ["Unix signals and process groups, cross-platform liveness, locks, child pre-exec configuration, and argv/title state"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-proc/Cargo.toml — describes safe process-management wrappers", "lib/foundation/fabro-proc/c/capture_argv.c — establishes the FFI boundary for title rewriting"] + }, + { + "id": "fabro-redact", + "name": "Secret and Credential Redaction", + "purpose": "Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded 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/safe_url.rs:DisplaySafeUrl"], + "owns": ["Rule source and engine, entropy thresholds, overlap merging, structured redaction policy, and safe URL display"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-redact/build.rs:main — compiles the tracked Gitleaks rule source into OUT_DIR", "lib/foundation/fabro-redact/src/lib.rs:redact_string — composes entropy and rule-based detection"] + }, + { + "id": "fabro-static", + "name": "Shared Static Conventions", + "purpose": "Defines dependency-light canonical environment-variable names and registries for 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"], + "owns": ["Canonical environment names and bootstrap and optional secret classification"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-static/Cargo.toml — declares a no-dependency static registry", "lib/foundation/fabro-static/src/env_vars.rs:EnvVars — centralizes environment names used across the workspace"] + }, + { + "id": "fabro-telemetry", + "name": "Analytics and Crash Telemetry", + "purpose": "Initializes analytics and crash reporting, builds anonymous context, buffers events, and delivers them 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:shutdown"], + "owns": ["Process-global telemetry state, identifiers, buffer thread, event context, command sanitization, Segment delivery, and panic capture"], + "depends_on": ["fabro-http", "fabro-static", "fabro-util"], + "evidence": ["lib/foundation/fabro-telemetry/Cargo.toml — declares analytics and crash reporting", "lib/foundation/fabro-telemetry/src/lib.rs:Global — owns sender, identity, context, level, and background thread"] + }, + { + "id": "fabro-template", + "name": "Template Rendering and Dependency Discovery", + "purpose": "Renders MiniJinja templates with source-aware diagnostics, rooted stores, wrappers, and static dependency discovery.", + "globs": ["lib/foundation/fabro-template/**"], + "exclude_globs": [], + "entry_points": ["lib/foundation/fabro-template/src/lib.rs:render_named", "lib/foundation/fabro-template/src/store.rs:TemplateStore"], + "owns": ["Template context, render modes, diagnostics, include safety, stores, caching and recording, and dependency closure"], + "depends_on": ["fabro-types", "fabro-util"], + "evidence": ["lib/foundation/fabro-template/Cargo.toml — declares the shared rendering boundary", "lib/foundation/fabro-template/src/dependency.rs — owns include and import extraction and closure discovery"] + }, + { + "id": "fabro-test", + "name": "Shared Integration-Test Infrastructure", + "purpose": "Provides isolated CLI/server test contexts, twin and live mode control, process harnessing, snapshot normalization, and HTTP assertions.", + "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"], + "owns": ["Temporary test home and storage, managed processes, mode and secret gating, environment isolation, snapshot filters, twins, and HTTP diagnostics"], + "depends_on": ["fabro-config", "fabro-http", "fabro-install", "fabro-proc", "fabro-static", "fabro-types", "fabro-util", "twin-github", "twin-openai", "workflow-test-corpus"], + "evidence": ["lib/foundation/fabro-test/Cargo.toml — declares shared integration-test utilities and twin dependencies", "lib/foundation/fabro-test/src/lib.rs:TestContext — owns isolated paths, subprocesses, filters, and managed server state"] + }, + { + "id": "fabro-types", + "name": "Shared Product Contracts and State Records", + "purpose": "Defines serializable identifiers, settings, run and session events, projections, and other product vocabulary exchanged across Fabro 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"], + "owns": ["Canonical serde shapes and IDs for runs, stages, sessions, events, settings, projections, sandboxes, integrations, billing, and repositories"], + "depends_on": ["fabro-model", "fabro-util"], + "evidence": ["lib/foundation/fabro-types/Cargo.toml — describes shared record structs and enums", "lib/foundation/fabro-types/src/lib.rs — is the single facade for canonical product vocabulary"] + }, + { + "id": "fabro-util", + "name": "Cross-Cutting Runtime and CLI Utilities", + "purpose": "Provides shared environment, filesystem, shell, terminal, logging, token, error, time, backoff, warning, and glob primitives.", + "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"], + "owns": ["Low-level helper contracts plus warning, buffered log, environment, home, token, terminal, backoff, error, and glob state"], + "depends_on": ["fabro-static"], + "evidence": ["lib/foundation/fabro-util/Cargo.toml — identifies shared runtime and terminal helpers", "lib/foundation/fabro-util/src/run_log.rs — owns the buffered run-log guard lifecycle"] + }, + { + "id": "fabro-vault", + "name": "Secret Vault and SQLite Store", + "purpose": "Validates and stores workflow-visible secrets in file, memory, or SQLite stores with revision-aware updates and 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"], + "owns": ["Secret validation and redacted entries, atomic file persistence, SQL CRUD, revisions, snapshots, and legacy import"], + "depends_on": ["fabro-db", "fabro-static", "fabro-types"], + "evidence": ["lib/foundation/fabro-vault/Cargo.toml — declares workflow-visible secret storage", "lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision — exposes concurrent refresh write-back semantics"] + }, + { + "id": "fabro-web-app", + "name": "Fabro Browser Application", + "purpose": "Builds and runs the React SPA for normal operations and first-run installation.", + "globs": ["apps/fabro-web/**"], + "exclude_globs": ["apps/fabro-web/app/components/playground/**"], + "entry_points": ["apps/fabro-web/app/entry.tsx", "apps/fabro-web/scripts/build.ts"], + "owns": ["Browser bundle and route graphs, install flow, shared browser runtime and UI, product operations UX, and public assets"], + "depends_on": ["fabro-api-client-generation", "fabro-http-api-contract", "fabro-workflow-playground"], + "evidence": ["apps/fabro-web/package.json — declares the React application, custom build, tests, and API-client workspace edge", "apps/fabro-web/app/entry.tsx — creates the browser root and selects normal or install routing"] + }, + { + "id": "fabro-workflow-playground", + "name": "Browser Workflow Playground", + "purpose": "Provides a self-contained workflow drafting, simulation, chat, visualization, file-generation, download, and run-launch surface.", + "globs": ["apps/fabro-web/app/components/playground/**"], + "exclude_globs": [], + "entry_points": ["apps/fabro-web/app/components/playground/playground.tsx:Playground", "apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft"], + "owns": ["Workflow draft schema and persistence, simulation, canvas, chat adaptation, generated project files, download, and launch controls"], + "depends_on": ["fabro-http-api-contract", "fabro-web-app"], + "evidence": ["apps/fabro-web/app/components/playground/playground.tsx:Playground — exposes a prop boundary framed for re-embedding", "apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft — owns versioned browser persistence"] + }, + { + "id": "fabro-marketing-site", + "name": "Fabro Marketing Site", + "purpose": "Builds and deploys the public Fabro site with landing content, blog, roadmap, showcase, install resources, and social assets.", + "globs": ["apps/marketing/**", "test/bin/install_test.sh"], + "exclude_globs": ["apps/marketing/.vercel/**"], + "entry_points": ["apps/marketing/src/pages/index.astro", "apps/marketing/astro.config.mjs", "apps/marketing/public/install.sh"], + "owns": ["Astro routes and layout, content collections, marketing presentation, workflow showcases, install resources, redirects, and deployment configuration"], + "depends_on": [], + "evidence": ["apps/marketing/package.json — declares an independent Astro application", "apps/marketing/src/content.config.ts — defines typed roadmap, blog, and showcase collections", "test/bin/install_test.sh — black-box tests the site's canonical install script"] + }, + { + "id": "fabro-remotion-video", + "name": "Fabro Remotion Composition", + "purpose": "Renders the branded FabroIntro motion-graphics video.", + "globs": ["apps/remotion/**"], + "exclude_globs": [], + "entry_points": ["apps/remotion/src/index.ts", "apps/remotion/src/Root.tsx:RemotionRoot"], + "owns": ["Composition registration, frame timeline, image format, logo animation, brand assets, and rendered-video lifecycle"], + "depends_on": [], + "evidence": ["apps/remotion/package.json — declares an independent Remotion project and render target", "apps/remotion/src/Root.tsx:RemotionRoot — declares composition identity, dimensions, frame rate, and duration"] + }, + { + "id": "fabro-api-client-generation", + "name": "TypeScript API Client Generation", + "purpose": "Configures, normalizes, and type-checks the generated TypeScript/Axios client for the Fabro HTTP contract.", + "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": [], + "entry_points": ["lib/packages/fabro-api-client/package.json:scripts.generate", "lib/packages/fabro-api-client/scripts/normalize-generated.ts"], + "owns": ["Generator versions and options, output location, normalization, strict compilation, and hand-written generated-shape invariants"], + "depends_on": ["fabro-http-api-contract"], + "evidence": ["lib/packages/fabro-api-client/package.json — invokes pinned OpenAPI Generator against the shared YAML and writes src", "lib/packages/fabro-api-client/tests/principal-exhaustive.ts — asserts a generated union contract at compile time"] + }, + { + "id": "public-documentation", + "name": "Public Documentation", + "purpose": "Owns authored Fabro user documentation, Mintlify presentation, the repository landing page, and published web-screenshot maintenance.", + "globs": ["README.md", "docs/public/**", "docs/internal/updating-web-screenshots.md"], + "exclude_globs": ["docs/public/api-reference/fabro-api.yaml", "docs/public/changelog/**", "docs/public/images/*-workflow.svg", "docs/public/images/tutorial-*.svg", "docs/public/images/brave-search-research.svg", "docs/public/images/how-fabro-works.svg", "docs/public/images/nlspec-conformance.svg", "docs/public/images/plan-implement-readme.svg"], + "entry_points": ["README.md", "docs/public/docs.json", "docs/public/getting-started/introduction.mdx"], + "owns": ["Mintlify navigation and presentation, public guides and reference prose, curated images and screenshots, syntax definitions, and repository overview"], + "depends_on": ["documentation-demo-workflows", "fabro-cli", "fabro-http-api-contract", "public-release-history"], + "evidence": ["docs/public/docs.json — declares the Mintlify theme, navigation, OpenAPI, and changelog surfaces", "README.md — links to the published docs and embeds their canonical assets", "docs/internal/updating-web-screenshots.md — defines the screenshot capture and verification workflow"] + }, + { + "id": "public-release-history", + "name": "Published Changelog", + "purpose": "Preserves and publishes dated user-facing release and change records independently of current reference documentation.", + "globs": ["docs/public/changelog/**"], + "exclude_globs": [], + "entry_points": ["docs/public/changelog/2026-07-25.mdx"], + "owns": ["Dated titles, migration warnings, feature summaries, and historical behavior notes"], + "depends_on": ["public-documentation"], + "evidence": ["docs/public/docs.json — gives the changelog its own top-level tab and enumerates every page", "docs/public/changelog/2026-07-25.mdx — is the newest dated release entry at the assessed revision"] + }, + { + "id": "fabro-http-api-contract", + "name": "Fabro HTTP API Contract", + "purpose": "Defines the OpenAPI-first wire contract used by the server, generated clients, conformance tests, and published API reference.", + "globs": ["docs/public/api-reference/fabro-api.yaml"], + "exclude_globs": [], + "entry_points": ["docs/public/api-reference/fabro-api.yaml"], + "owns": ["HTTP routes, request and response schemas, authentication declarations, and API-facing wire documentation"], + "depends_on": [], + "evidence": ["AGENTS.md — identifies the OpenAPI file as the HTTP interface source of truth", "lib/foundation/fabro-api/build.rs:main — consumes the contract for Rust generation", "lib/apps/fabro-server/tests/it/openapi_conformance.rs — reads it for router conformance"] + }, + { + "id": "documentation-demo-workflows", + "name": "Executable Documentation Demos", + "purpose": "Provides runnable workflow definitions, configuration, and prompts used by public tutorials and demonstrations.", + "globs": ["docs/internal/demo/*.fabro", "docs/internal/demo/*.toml", "docs/internal/demo/prompts/**"], + "exclude_globs": [], + "entry_points": ["docs/internal/demo/01-hello.fabro", "docs/internal/demo/14-search-imagegen.toml"], + "owns": ["Executable example graphs, the image-generation run configuration, and shared demo prompt text"], + "depends_on": ["fabro-cli", "fabro-sandbox", "fabro-workflow"], + "evidence": ["docs/public/tutorials/hello-world.mdx — invokes a demo workflow path directly", "docs/internal/demo/14-search-imagegen.toml — selects the demo graph, environment, and output assets"] + }, + { + "id": "internal-engineering-guidance", + "name": "Internal Engineering Guidance", + "purpose": "Records active repository-wide engineering policies and maintained architecture and runtime contracts.", + "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"], + "exclude_globs": [], + "entry_points": ["docs/internal/events-strategy.md", "docs/internal/testing-strategy.md", "docs/internal/error-handling-strategy.md"], + "owns": ["Logging, events, testing, migrations, secrets, error handling, React effects, panic, event catalog, LLM resolution, parallelism, and run-file guidance"], + "depends_on": ["fabro-cli", "fabro-config", "fabro-server", "fabro-types", "fabro-web-app", "fabro-workflow"], + "evidence": ["AGENTS.md — makes the strategy and policy documents mandatory before related changes", "docs/internal/events.md — is the maintained serialized event catalog"] + }, + { + "id": "product-context", + "name": "Internal Product Context", + "purpose": "Maintains product intent, audience, current shape, success signals, and stable technical and product constraints.", + "globs": ["docs/internal/product/**"], + "exclude_globs": [], + "entry_points": ["docs/internal/product/product-description.md", "docs/internal/product/current-state.md"], + "owns": ["Business problem, personas, product description, current state, success metrics, and product-level technical requirements"], + "depends_on": [], + "evidence": ["docs/internal/product/current-state.md — identifies itself as a concise current product snapshot", "docs/internal/product/technical-requirements.md — records stable constraints for product changes"] + }, + { + "id": "twin-openai", + "name": "OpenAI Protocol Twin", + "purpose": "Provides a deterministic OpenAI-compatible HTTP service for black-box and protocol-contract tests.", + "globs": ["test/twin/openai/**"], + "exclude_globs": [], + "entry_points": ["test/twin/openai/src/main.rs:main", "test/twin/openai/src/lib.rs:build_app"], + "owns": ["OpenAI-compatible routes, scenario queues, request logs, deterministic IDs, streaming and failure behavior, admin APIs, and debug UI"], + "depends_on": ["fabro-http", "fabro-static"], + "evidence": ["test/twin/openai/Cargo.toml — declares a fake OpenAI-compatible library and binary", "test/twin/openai/src/state.rs:AppState — owns namespaced counters, scenario queues, and request logs"] + }, + { + "id": "twin-github", + "name": "GitHub Protocol Twin", + "purpose": "Provides an in-process fake GitHub service with seeded mutable state and temporary Git repositories.", + "globs": ["test/twin/github/**"], + "exclude_globs": [], + "entry_points": ["test/twin/github/src/server.rs:TestServer::start", "test/twin/github/src/server.rs:build_router"], + "owns": ["Fake GitHub App, OAuth, REST, GraphQL, smart-HTTP, repositories, pull requests, releases, projects, tokens, and test keys"], + "depends_on": ["fabro-http"], + "evidence": ["test/twin/github/Cargo.toml — declares an independent fake GitHub service", "test/twin/github/src/state.rs:AppState — owns the seeded and mutable GitHub-domain state"] + }, + { + "id": "workflow-test-corpus", + "name": "Shared Workflow Compatibility Fixtures", + "purpose": "Supplies reusable workflow, compatibility, configuration, prompt, partial, and template inputs to cross-crate 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/templates/static_dependencies/workflow.fabro"], + "owns": ["Representative workflow syntax and behavior cases, Attractor compatibility graphs, DOT fixtures, and template dependency trees"], + "depends_on": [], + "evidence": ["lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture — resolves named inputs from the shared test directory", "lib/components/fabro-workflow/tests/it/attractor_compat.rs — enumerates the Attractor corpus"] + }, + { + "id": "documentation-workflow-tests", + "name": "Documentation Workflow Conformance", + "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, extraction and stub generation, validation and execution phases, parallel runner state, and checklist"], + "depends_on": ["fabro-cli", "fabro-workflow", "public-documentation"], + "evidence": ["test/docs/run_tests.sh — discovers and runs every tracked documentation workflow", "test/docs/extract_dots.py:main — extracts complete graphs and creates companion fixtures"] + }, + { + "id": "swe-bench-evaluation", + "name": "SWE-Bench Evaluation Workflow", + "purpose": "Generates Fabro patches for SWE-bench Lite, grades them, monitors runs, builds environments, and records normalized summaries.", + "globs": ["evals/swe-bench/*.py", "evals/swe-bench/*.fabro", "evals/swe-bench/*.txt", "evals/swe-bench/README.md"], + "exclude_globs": [], + "entry_points": ["evals/swe-bench/run_eval.py:main", "evals/swe-bench/evaluate_daytona.py:main", "evals/swe-bench/record_results.py:main"], + "owns": ["Dataset selection, per-instance workflow generation, sandbox specs, subprocess orchestration, patch extraction, grading, monitoring, and scoreboard schema"], + "depends_on": ["fabro-cli", "fabro-sandbox", "fabro-workflow"], + "evidence": ["evals/swe-bench/README.md — defines the generate, evaluate, and record lifecycle", "evals/swe-bench/run_eval.py:run_instance — creates per-instance Fabro inputs and invokes the CLI"] + }, + { + "id": "repository-development-policy", + "name": "Repository Development Policy", + "purpose": "Defines workspace, dependency, formatting, lint, test, version-control, contributor, and coding-agent development contracts.", + "globs": [".cargo/**", ".config/**", ".gitattributes", ".gitignore", "AGENTS.md", "CONTRIBUTING.md", "Cargo.toml", "package.json", "bunfig.toml", "clippy.toml", "rustfmt.toml"], + "exclude_globs": [], + "entry_points": ["Cargo.toml:[workspace]", "package.json:workspaces", "AGENTS.md"], + "owns": ["Workspace membership and policy, tool aliases, test profiles, lints and formatting, tracked path treatment, contributor workflow, and agent instructions"], + "depends_on": ["fabro-build-tooling"], + "evidence": ["Cargo.toml — declares Rust workspace members, dependencies, lints, and profiles", ".cargo/config.toml — exposes cargo dev and repository test policy", "AGENTS.md — defines architectural and workflow instructions"] + }, + { + "id": "repository-ci", + "name": "Pull-Request and Branch CI", + "purpose": "Runs branch and pull-request validation for Rust and TypeScript and configures GitHub Actions static validation.", + "globs": [".github/workflows/rust.yml", ".github/workflows/typescript.yml", ".github/zizmor.yml"], + "exclude_globs": [], + "entry_points": [".github/workflows/rust.yml", ".github/workflows/typescript.yml"], + "owns": ["Path triggers, formatting, linting, generated-doc checks, tests, E2E modes, TypeScript checks, builds, concurrency, and workflow-lint policy"], + "depends_on": ["fabro-api-client-generation", "fabro-build-tooling", "fabro-web-app", "public-documentation", "repository-development-policy", "twin-openai"], + "evidence": [".github/workflows/rust.yml — runs Rust formatting, lint, generated-document, workspace test, and twin E2E jobs", ".github/workflows/typescript.yml — checks and builds the Bun workspace and embedded SPA"] + }, + { + "id": "release-distribution-automation", + "name": "Release and Package Publication", + "purpose": "Cuts nightly releases and publishes CLI archives, GitHub Releases, multi-architecture images, attestations, and Homebrew formulas.", + "globs": [".github/workflows/nightly.yml", ".github/workflows/release.yml", "installer/**"], + "exclude_globs": [], + "entry_points": [".github/workflows/nightly.yml", ".github/workflows/release.yml", "installer/fabro.rb.template"], + "owns": ["Nightly tag creation, release matrix, archives and checksums, attestations, GitHub Releases, image publication, and Homebrew channels"], + "depends_on": ["container-packaging-and-deployment", "fabro-build-tooling", "fabro-cli", "fabro-web-app", "repository-development-policy"], + "evidence": [".github/workflows/release.yml — packages target matrices and publishes releases, images, and formulas", "installer/fabro.rb.template — defines platform archives, checksums, installation, and smoke tests"] + }, + { + "id": "container-packaging-and-deployment", + "name": "Container Packaging and Deployment", + "purpose": "Packages Fabro as a runtime container and defines local, production, Tailscale, and split-web Compose deployments.", + "globs": [".dockerignore", ".env.example", "Dockerfile", "docker-compose*.yaml", "docker/**"], + "exclude_globs": [], + "entry_points": ["Dockerfile", "docker/entrypoint.sh", "docker-compose.yaml"], + "owns": ["Container image layout, runtime packages and user, storage and Docker socket handoff, preflight checks, proxy behavior, Compose topology, volumes, ports, and health checks"], + "depends_on": ["fabro-build-tooling", "fabro-cli", "fabro-server", "fabro-web-app"], + "evidence": ["Dockerfile — consumes the architecture-specific staged binary and installs the runtime entrypoint", "docker-compose.yaml — defines the primary image, state, socket, port, and health-check contract"] + }, + { + "id": "fabro-repository-automation", + "name": "Fabro-Native Repository Automation", + "purpose": "Configures Fabro's development environment and named workflow graphs, prompts, permissions, and project defaults for repository work.", + "globs": [".fabro/Dockerfile", ".fabro/project.toml", ".fabro/workflows/**"], + "exclude_globs": [".fabro/workflows/goal/workflow.svg"], + "entry_points": [".fabro/project.toml", ".fabro/workflows/implement-plan/workflow.fabro", ".fabro/workflows/smoke/workflow.fabro"], + "owns": ["Repository pull-request defaults, Daytona development environment, named workflow catalog, local prompts, GitHub permissions, and maintenance commands"], + "depends_on": ["fabro-build-tooling", "fabro-cli", "fabro-config", "fabro-github", "fabro-graphviz", "fabro-sandbox", "fabro-workflow", "repository-development-policy"], + "evidence": [".fabro/project.toml — selects the repository environment, resources, lifecycle, labels, and pull-request defaults", ".fabro/workflows/implement-plan/workflow.fabro — invokes repository Cargo and Bun verification and build tooling"] + }, + { + "id": "coding-agent-automation", + "name": "Repository Coding-Agent Automation", + "purpose": "Supplies repository-local review prompts, documentation and changelog skills, edit hooks, and an image-generation helper to coding agents.", + "globs": [".ai/prompts/**", ".claude/settings.json", ".claude/skills/**", "bin/agent/**"], + "exclude_globs": [".claude/skills/*/watermark"], + "entry_points": [".ai/prompts/code-review-fast.md", ".claude/skills/changelog/SKILL.md", ".claude/skills/docs/SKILL.md", "bin/agent/imagegen"], + "owns": ["Code-review orchestration, changelog and documentation maintenance, post-edit formatting hook, and agent image-generation command"], + "depends_on": ["public-documentation", "public-release-history"], + "evidence": [".ai/prompts/code-review-deep-1.md — begins the multi-stage review artifact pipeline", ".claude/skills/docs/SKILL.md — defines the code-to-public-documentation update workflow", ".claude/settings.json — registers the repository post-edit Rust formatting hook"] + } + ], + "unmapped_files": [ + "docs/internal/assets/brand/github-header-v2-mesh.png", + "docs/internal/assets/brand/github-header-v2-mesh.svg", + "docs/internal/assets/brand/logo/logotype-black.svg", + "docs/internal/assets/brand/logo/logotype.svg", + "docs/internal/assets/brand/logo/symbol-black.svg", + "docs/internal/assets/brand/logo/symbol.svg", + "docs/internal/assets/brand/palette-lockups.svg", + "docs/internal/assets/brand/palette-mockup-icons.svg", + "docs/internal/assets/brand/palette-mockup.svg", + "docs/internal/assets/brand/palette.png", + "docs/internal/assets/brand/palette.svg", + "docs/internal/assets/brand/social-card.html", + "docs/internal/assets/brand/social-card.png", + "docs/internal/assets/brand/twitter-card-v0.176.1.html", + "docs/internal/assets/brand/twitter-card-v0.176.1.png" + ], + "coverage": { + "relevant_file_count": 3104, + "assigned_file_count": 2256, + "excluded_file_count": 833, + "unmapped_file_count": 15 + }, + "open_questions": [ + "Should the currently unreferenced docs/internal/assets brand collateral be assigned to a maintained brand component, or remain explicitly unmapped until an ownership and update workflow is identified?", + "Should the first-run browser installer become a separate component if its route and state lifecycle gains an independent entry point, rather than remaining inside fabro-web-app?", + "Should fabro-workflow eventually split run-operation/materialization ownership from pipeline execution if those facades acquire independent state and public contracts?" + ] +} diff --git a/.chisel/cartography/codebase-map.md b/.chisel/cartography/codebase-map.md new file mode 100644 index 000000000..27a800d71 --- /dev/null +++ b/.chisel/cartography/codebase-map.md @@ -0,0 +1,669 @@ +# Chisel Codebase Map + +Cartography v1 · revision `2bcf94fed8a9b429f18d9196fa824711d6f4cb0a` · 2026-07-27T14:07:02Z +Assigned 2256 files · excluded 833 · unmapped 15 · instructions: AGENTS.md, CLAUDE.md, CONTRIBUTING.md + +Fabro is a Cargo workspace whose CLI and HTTP server compose shared workflow, agent, model, sandbox, persistence, integration, and foundation crates. A Bun workspace contains the React web application, Astro marketing site, Remotion composition, and OpenAPI-derived TypeScript client tooling; the OpenAPI document is the shared HTTP contract. Public and internal documentation, protocol twins, fixture corpora, evaluation tooling, build/release/deployment automation, and repository-local agent workflows form separate support boundaries around the product runtime. + +## Components + +### `fabro-cli` — Fabro CLI Application + +- **Purpose:** Provides the fabro command-line process, command dispatch, terminal presentation, server bootstrap, and hidden run-worker entry. +- **Paths:** `lib/apps/fabro-cli/**` +- **Entry points:** `lib/apps/fabro-cli/src/main.rs:main`, `lib/apps/fabro-cli/src/args.rs:Commands` +- **Owns:** CLI process and command lifecycle, output contracts, command context, local server discovery, and the run-worker subprocess entry +- **Depends on:** `fabro-acp`, `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-build-support`, `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-mcp-server`, `fabro-model`, `fabro-oauth`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-server`, `fabro-static`, `fabro-store`, `fabro-telemetry`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `fabro-workflow`, `workflow-test-corpus` +- **Evidence:** lib/apps/fabro-cli/Cargo.toml — declares the fabro binary and its direct workspace dependencies; lib/apps/fabro-cli/src/main.rs:main_inner — constructs shared command state and dispatches the complete command surface + +### `fabro-mcp-server` — Fabro MCP Stdio Server + +- **Purpose:** Exposes Fabro run operations as an MCP stdio tool service and generates supported MCP client configuration. +- **Paths:** `lib/apps/fabro-mcp-server/**` +- **Entry points:** `lib/apps/fabro-mcp-server/src/lib.rs:start`, `lib/apps/fabro-mcp-server/src/config.rs:init_agent` +- **Owns:** MCP stdio service lifecycle, tool router, lazy Fabro client backend, and MCP client configuration updates +- **Depends on:** `fabro-api`, `fabro-client`, `fabro-config`, `fabro-manifest`, `fabro-model`, `fabro-server`, `fabro-tool`, `fabro-types`, `fabro-util` +- **Evidence:** lib/apps/fabro-mcp-server/Cargo.toml — declares a distinct MCP server library package; lib/apps/fabro-mcp-server/src/server.rs:start — owns the rmcp stdio service lifecycle + +### `fabro-server` — Fabro HTTP Server + +- **Purpose:** Hosts Fabro's HTTP control plane and web surface while coordinating persisted run state, workers, schedulers, sessions, authentication, and integrations. +- **Paths:** `lib/apps/fabro-server/**` +- **Entry points:** `lib/apps/fabro-server/src/serve.rs:serve_command`, `lib/apps/fabro-server/src/server.rs:build_router` +- **Owns:** Server startup and shutdown, AppState, API and web routing, authentication, scheduling, worker control, and integration coordination +- **Depends on:** `fabro-agent`, `fabro-api`, `fabro-auth`, `fabro-automation`, `fabro-build-support`, `fabro-client`, `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-http-api-contract`, `fabro-install`, `fabro-interview`, `fabro-llm`, `fabro-manifest`, `fabro-mcp-store`, `fabro-model`, `fabro-proc`, `fabro-redact`, `fabro-sandbox`, `fabro-slack`, `fabro-spa`, `fabro-static`, `fabro-store`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-variable`, `fabro-vault`, `fabro-workflow` +- **Evidence:** lib/apps/fabro-server/Cargo.toml — declares the HTTP server package and its application dependencies; lib/apps/fabro-server/src/server.rs:AppState — centralizes the service's stores, runtimes, schedulers, credentials, integrations, and shutdown state + +### `fabro-spa` — Embedded SPA Assets + +- **Purpose:** Provides compile-time embedded production SPA lookup, bytes, and content hashes to the Rust server. +- **Paths:** `lib/apps/fabro-spa/Cargo.toml`, `lib/apps/fabro-spa/src/**` +- **Entry points:** `lib/apps/fabro-spa/src/lib.rs:get`, `lib/apps/fabro-spa/src/lib.rs:AssetBytes` +- **Owns:** Compile-time SPA embedding, asset lookup, byte and hash metadata, and source-map exclusion +- **Evidence:** lib/apps/fabro-spa/Cargo.toml — declares a distinct embedded-assets package; lib/apps/fabro-spa/src/lib.rs:EmbeddedAssets — defines compile-time asset embedding and lookup; lib/apps/fabro-server/src/static_files.rs — consumes the embedded asset interface + +### `fabro-acp` — Agent Client Protocol Runtime + +- **Purpose:** Launches and controls Agent Client Protocol processes through Fabro sandboxes and translates their sessions into run results. +- **Paths:** `lib/components/fabro-acp/**` +- **Entry points:** `lib/components/fabro-acp/src/command.rs:AcpProcessSpec`, `lib/components/fabro-acp/src/session.rs:run_acp_turn` +- **Owns:** ACP process specifications, transport and session lifetime, live steering, cancellation, and exit translation +- **Depends on:** `fabro-sandbox`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-acp/Cargo.toml — declares the ACP backend and optional sandbox runtime edge; lib/components/fabro-acp/tests/session.rs — exercises the ACP session boundary + +### `fabro-agent` — Coding Agent Runtime + +- **Purpose:** Runs programmable coding-agent sessions with model profiles, context management, native and MCP tools, permissions, and subagents. +- **Paths:** `lib/components/fabro-agent/**` +- **Entry points:** `lib/components/fabro-agent/src/session.rs:Session`, `lib/components/fabro-agent/src/tool_registry.rs:ToolRegistry` +- **Owns:** Agent session history, prompts and profiles, tool execution, context compaction, permissions, questions, todos, and subagents +- **Depends on:** `fabro-auth`, `fabro-config`, `fabro-http`, `fabro-llm`, `fabro-mcp`, `fabro-model`, `fabro-sandbox`, `fabro-static`, `fabro-template`, `fabro-types`, `fabro-util`, `fabro-vault` +- **Evidence:** lib/components/fabro-agent/Cargo.toml — describes a programmable agentic loop and its runtime dependencies; lib/components/fabro-agent/src/lib.rs — exposes the session, profile, tool, permission, history, and subagent facade + +### `fabro-automation` — Automation Definitions and Storage + +- **Purpose:** Validates, versions, imports, and durably stores scheduled, API-triggered, and manual automation definitions. +- **Paths:** `lib/components/fabro-automation/**` +- **Entry points:** `lib/components/fabro-automation/src/store.rs:AutomationStore`, `lib/components/fabro-automation/src/migrations.rs:import_legacy_directory_once` +- **Owns:** Automation identifiers, targets, triggers, revisions, SQLite records, and legacy import +- **Depends on:** `fabro-db` +- **Evidence:** lib/components/fabro-automation/Cargo.toml — declares the automation domain and durable storage boundary; lib/components/fabro-automation/migrations/2026071101_file_definitions_to_sqlite.rs — evolves the owned persistence format + +### `fabro-checkpoint` — Git Checkpoint Storage + +- **Purpose:** Stores workflow checkpoints and metadata in Git commits and dedicated metadata branches. +- **Paths:** `lib/components/fabro-checkpoint/**` +- **Entry points:** `lib/components/fabro-checkpoint/src/branch.rs:BranchStore`, `lib/components/fabro-checkpoint/src/git.rs:Store` +- **Owns:** Checkpoint commits, Git trees, metadata branches, authorship, trailers, and checkpoint errors +- **Depends on:** `fabro-config`, `fabro-store`, `fabro-types` +- **Evidence:** lib/components/fabro-checkpoint/Cargo.toml — identifies Git-backed workflow checkpoint storage; lib/components/fabro-checkpoint/src/lib.rs — exposes the branch, Git, author, trailer, and error surface + +### `fabro-dump` — Run Dump Materialization + +- **Purpose:** Materializes stored run projections, events, checkpoints, artifacts, and blobs into a portable directory tree. +- **Paths:** `lib/components/fabro-dump/**` +- **Entry points:** `lib/components/fabro-dump/src/lib.rs:RunDump`, `lib/components/fabro-dump/src/lib.rs:RunDump::write_to_dir` +- **Owns:** Dump layout, stage ranking, blob hydration, serialization, and directory writing +- **Depends on:** `fabro-store`, `fabro-types` +- **Evidence:** lib/components/fabro-dump/Cargo.toml — gives the operation a distinct crate and storage dependency; lib/components/fabro-dump/src/lib.rs:RunDump — contains the public dump-building lifecycle + +### `fabro-environment` — Environment Definitions and Storage + +- **Purpose:** Validates, seeds, versions, imports, and durably stores server-owned execution environment definitions. +- **Paths:** `lib/components/fabro-environment/**` +- **Entry points:** `lib/components/fabro-environment/src/store.rs:EnvironmentStore`, `lib/components/fabro-environment/src/store.rs:seed_default_environment` +- **Owns:** Environment identifiers, revisions, drafts, SQLite records, built-in seeding, and legacy import +- **Depends on:** `fabro-config`, `fabro-db`, `fabro-types` +- **Evidence:** lib/components/fabro-environment/Cargo.toml — declares a server-owned environment domain and store; lib/components/fabro-environment/tests/store.rs — exercises the independent persistence boundary + +### `fabro-github` — GitHub Authentication and API + +- **Purpose:** Resolves GitHub credentials and performs authenticated App, repository, branch, and pull-request operations. +- **Paths:** `lib/components/fabro-github/**` +- **Entry points:** `lib/components/fabro-github/src/lib.rs:GitHubCredentials`, `lib/components/fabro-github/src/lib.rs:create_pull_request` +- **Owns:** GitHub credentials and token minting, API translation, repository URL handling, and pull-request lifecycle calls +- **Depends on:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-types` +- **Evidence:** lib/components/fabro-github/Cargo.toml — describes the GitHub App authentication and API adapter; lib/components/fabro-github/src/lib.rs:GitHubContext — defines the credential context and testable HTTP boundary + +### `fabro-graphviz` — Workflow Graph Language + +- **Purpose:** Parses Graphviz DOT into Fabro's typed graph model and handles conditions, stylesheets, fidelity, and graph rendering. +- **Paths:** `lib/components/fabro-graphviz/**` +- **Entry points:** `lib/components/fabro-graphviz/src/parser/mod.rs:parse`, `lib/components/fabro-graphviz/src/render.rs:render_dot` +- **Owns:** DOT lexer, parser, semantic conversion, graph errors, condition and stylesheet syntax, and rendering normalization +- **Depends on:** `fabro-types`, `workflow-test-corpus` +- **Evidence:** lib/components/fabro-graphviz/Cargo.toml — names the crate as the DOT parser and graph data model; lib/components/fabro-graphviz/src/parser/mod.rs:parse — is the source-to-typed-graph entry point + +### `fabro-hooks` — Workflow Lifecycle Hooks + +- **Purpose:** Configures and executes user-defined workflow hooks and bridges tool hooks into the agent runtime. +- **Paths:** `lib/components/fabro-hooks/**` +- **Entry points:** `lib/components/fabro-hooks/src/runner.rs:HookRunner`, `lib/components/fabro-hooks/src/bridge.rs:WorkflowToolHookCallback` +- **Owns:** Hook definitions and selection, execution context, result merging, command and HTTP dispatch, and agent bridging +- **Depends on:** `fabro-agent`, `fabro-auth`, `fabro-http`, `fabro-llm`, `fabro-model`, `fabro-redact`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-hooks/Cargo.toml — identifies the workflow hook boundary and runtime dependencies; lib/components/fabro-hooks/tests/host_command_hooks.rs — tests host hooks through the public lifecycle + +### `fabro-install` — Installation Persistence + +- **Purpose:** Prepares, persists, and rolls back shared CLI/server installation settings, credentials, development tokens, and default environments. +- **Paths:** `lib/components/fabro-install/**` +- **Entry points:** `lib/components/fabro-install/src/lib.rs:InstallPersistencePlan`, `lib/components/fabro-install/src/lib.rs:persist_install_outputs_direct` +- **Owns:** Install persistence plans, settings and environment mutations, vault writes, development tokens, and rollback +- **Depends on:** `fabro-config`, `fabro-db`, `fabro-environment`, `fabro-static`, `fabro-types`, `fabro-util`, `fabro-vault` +- **Evidence:** lib/components/fabro-install/Cargo.toml — declares shared install primitives for CLI and server; lib/components/fabro-install/src/lib.rs:InstallPersistencePlan — groups the files, tokens, and vault state committed by one install + +### `fabro-interview` — Human Interaction Runtime + +- **Purpose:** Represents workflow questions and answers and provides console, callback, queue, control, recording, replay, and automatic interviewer implementations. +- **Paths:** `lib/components/fabro-interview/**` +- **Entry points:** `lib/components/fabro-interview/src/lib.rs:Interviewer`, `lib/components/fabro-interview/src/control.rs:ControlInterviewer` +- **Owns:** Question and answer protocol, interviewer request lifetime, timeout behavior, delivery, recording, and replay +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-interview/Cargo.toml — defines interviewer traits and implementations as one crate; lib/components/fabro-interview/src/lib.rs:Interviewer — is the shared asynchronous human-interaction interface + +### `fabro-llm` — Unified LLM Client + +- **Purpose:** Provides a provider-neutral generation API with routing, middleware, retries, token and cost accounting, provider adapters, and wire codecs. +- **Paths:** `lib/components/fabro-llm/**` +- **Entry points:** `lib/components/fabro-llm/src/client.rs:Client`, `lib/components/fabro-llm/src/provider.rs:ProviderAdapter` +- **Owns:** Normalized generation types, adapter registry, provider authentication and transport, codecs, retries, middleware, and accounting +- **Depends on:** `fabro-auth`, `fabro-http`, `fabro-model`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-llm/Cargo.toml — declares the unified multi-provider client; lib/components/fabro-llm/tests/it/wire/mod.rs — verifies provider codecs against one normalized boundary + +### `fabro-manifest` — Run Manifest Construction + +- **Purpose:** Resolves workflow and configuration inputs, collects static dependencies, and constructs self-contained run manifests with Git provenance. +- **Paths:** `lib/components/fabro-manifest/**` +- **Entry points:** `lib/components/fabro-manifest/src/lib.rs:build_run_manifest`, `lib/components/fabro-manifest/src/lib.rs:ManifestBuildInput` +- **Owns:** Manifest input and output, configuration resolution, workflow dependency collection, Git context, and pre-run push preparation +- **Depends on:** `fabro-api`, `fabro-config`, `fabro-github`, `fabro-graphviz`, `fabro-template`, `fabro-types`, `fabro-workflow` +- **Evidence:** lib/components/fabro-manifest/Cargo.toml — declares manifest construction and its graph, Git, and workflow dependencies; lib/components/fabro-manifest/src/lib.rs:build_run_manifest — is the shared assembly operation used by CLI, server, and MCP server + +### `fabro-mcp` — MCP Client Runtime + +- **Purpose:** Connects to configured Model Context Protocol servers, manages connections, discovers tools, and dispatches qualified calls. +- **Paths:** `lib/components/fabro-mcp/**` +- **Entry points:** `lib/components/fabro-mcp/src/client.rs:McpClient`, `lib/components/fabro-mcp/src/connection_manager.rs:McpConnectionManager` +- **Owns:** MCP client connections, stdio and HTTP transports, connection-manager state, tool discovery, and result conversion +- **Depends on:** `fabro-config`, `fabro-http`, `fabro-types` +- **Evidence:** lib/components/fabro-mcp/Cargo.toml — declares the MCP client and transport features; lib/components/fabro-mcp/tests/stdio_integration.rs — verifies the external process boundary over stdio + +### `fabro-mcp-store` — MCP Server Catalog Storage + +- **Purpose:** Durably stores, revisions, caches, and imports server-managed MCP server definitions. +- **Paths:** `lib/components/fabro-mcp-store/**` +- **Entry points:** `lib/components/fabro-mcp-store/src/store.rs:McpServerStore`, `lib/components/fabro-mcp-store/src/store.rs:import_legacy_directory_once` +- **Owns:** MCP definition records, optimistic revisions, catalog cache, and legacy directory import +- **Depends on:** `fabro-db`, `fabro-types` +- **Evidence:** lib/components/fabro-mcp-store/Cargo.toml — declares durable MCP catalog storage; lib/components/fabro-mcp-store/src/lib.rs — explicitly assigns persistence ownership to this crate + +### `fabro-sandbox` — Execution Sandbox Abstraction + +- **Purpose:** Defines sandbox and provider contracts and implements local, Docker, and Daytona execution lifecycles. +- **Paths:** `lib/components/fabro-sandbox/**` +- **Entry points:** `lib/components/fabro-sandbox/src/sandbox.rs:Sandbox`, `lib/components/fabro-sandbox/src/provider.rs:SandboxProviderRegistry` +- **Owns:** Sandbox filesystem, process, and terminal interface; provider lifecycle; clone setup; reconnect behavior; and provider implementations +- **Depends on:** `fabro-config`, `fabro-github`, `fabro-http`, `fabro-proc`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-sandbox/Cargo.toml — defines provider features around a common sandbox crate; lib/components/fabro-sandbox/src/provider.rs:SandboxProvider — separates provider lifecycle from per-sandbox operations + +### `fabro-slack` — Slack Interaction Integration + +- **Purpose:** Connects to Slack Socket Mode and translates questions, answers, run events, and threads between Slack and Fabro. +- **Paths:** `lib/components/fabro-slack/**` +- **Entry points:** `lib/components/fabro-slack/src/connection.rs:run`, `lib/components/fabro-slack/src/client.rs:SlackClient` +- **Owns:** Slack credentials, Socket Mode lifecycle, API client, block rendering, payload parsing, thread registry, and dispatch +- **Depends on:** `fabro-http`, `fabro-interview`, `fabro-static`, `fabro-types`, `fabro-workflow` +- **Evidence:** lib/components/fabro-slack/Cargo.toml — declares the Slack interviewer integration; lib/components/fabro-slack/src/connection.rs:run — owns the Socket Mode event loop + +### `fabro-store` — Run and Authentication Persistence + +- **Purpose:** Persists run events, projections, blobs, artifacts, summaries, catalog indexes, and authentication grants over SlateDB, object storage, and SQLite. +- **Paths:** `lib/components/fabro-store/**` +- **Entry points:** `lib/components/fabro-store/src/slate/mod.rs:Database`, `lib/components/fabro-store/src/run_state.rs:RunProjectionReducer` +- **Owns:** Run event and projection lifecycle, blob and artifact layout, summary indexes, auth records, locking, and storage errors +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-store/src/lib.rs — presents one persistence facade for events, projections, artifacts, summaries, blobs, and auth; lib/components/fabro-store/src/slate/mod.rs:Database — is the shared storage root for the owned stores + +### `fabro-tool` — Run-Control Tools + +- **Purpose:** Defines and executes shared run create, search, get, event, gather, interaction, and pairing tools over an abstract Fabro backend. +- **Paths:** `lib/components/fabro-tool/**` +- **Entry points:** `lib/components/fabro-tool/src/common.rs:FabroToolBackend`, `lib/components/fabro-tool/src/common.rs:tool_definitions` +- **Owns:** Tool names and schemas, parameter validation, backend-neutral operations, result records, and text rendering +- **Depends on:** `fabro-api`, `fabro-client`, `fabro-types`, `fabro-util` +- **Evidence:** lib/components/fabro-tool/Cargo.toml — identifies shared run-control tool behavior over API/client contracts; lib/components/fabro-tool/src/common.rs:FabroToolBackend — is the abstraction shared by CLI, server, workflow, and MCP server + +### `fabro-tracker` — Issue Tracker Adapters + +- **Purpose:** Provides a common issue-tracker interface with GitHub Projects and Linear implementations. +- **Paths:** `lib/components/fabro-tracker/**` +- **Entry points:** `lib/components/fabro-tracker/src/lib.rs:Tracker`, `lib/components/fabro-tracker/src/github.rs:GitHubTracker` +- **Owns:** Normalized issues and blockers, candidate selection and transitions, and GitHub Projects and Linear GraphQL adapters +- **Depends on:** `fabro-github`, `fabro-http` +- **Evidence:** lib/components/fabro-tracker/Cargo.toml — declares the tracker trait and provider adapters; lib/components/fabro-tracker/src/lib.rs:Tracker — defines the provider-neutral issue workflow + +### `fabro-validate` — Workflow Graph Validation + +- **Purpose:** Runs built-in and catalog-aware lint rules over typed workflow graphs and returns structured diagnostics. +- **Paths:** `lib/components/fabro-validate/**` +- **Entry points:** `lib/components/fabro-validate/src/lib.rs:validate`, `lib/components/fabro-validate/src/lib.rs:LintRule` +- **Owns:** Validation diagnostics, rule interface and registry, graph and catalog traversal, and error escalation +- **Depends on:** `fabro-acp`, `fabro-graphviz`, `fabro-model`, `fabro-types`, `workflow-test-corpus` +- **Evidence:** lib/components/fabro-validate/Cargo.toml — declares graph validation and its graph/catalog dependencies; lib/components/fabro-validate/src/rules/mod.rs:built_in_rules — forms the explicit built-in rule registry + +### `fabro-variable` — Workflow Variable Storage + +- **Purpose:** Validates, durably stores, snapshots, and imports workflow-visible non-sensitive variables. +- **Paths:** `lib/components/fabro-variable/**` +- **Entry points:** `lib/components/fabro-variable/src/lib.rs:VariableStore`, `lib/components/fabro-variable/src/lib.rs:import_legacy_json_once` +- **Owns:** Variable validation, SQLite records, render-context snapshots, and legacy JSON import +- **Depends on:** `fabro-db`, `fabro-types` +- **Evidence:** lib/components/fabro-variable/Cargo.toml — defines workflow-visible variables as a storage concern; lib/components/fabro-variable/tests/store.rs — verifies its independent persistence and import contract + +### `fabro-workflow` — Workflow Orchestration Engine + +- **Purpose:** Transforms, validates, initializes, executes, persists, resumes, and finalizes graph-defined Fabro runs. +- **Paths:** `lib/components/fabro-workflow/**` +- **Entry points:** `lib/components/fabro-workflow/src/operations/start.rs:start`, `lib/components/fabro-workflow/src/pipeline/execute.rs:execute` +- **Owns:** Run operations, workflow phases, node handlers, run services, events, checkpoints, Git, artifacts, hooks, status, steering, and cancellation +- **Depends on:** `fabro-acp`, `fabro-agent`, `fabro-auth`, `fabro-checkpoint`, `fabro-config`, `fabro-core`, `fabro-dump`, `fabro-github`, `fabro-graphviz`, `fabro-hooks`, `fabro-http`, `fabro-interview`, `fabro-llm`, `fabro-mcp`, `fabro-model`, `fabro-redact`, `fabro-sandbox`, `fabro-static`, `fabro-store`, `fabro-template`, `fabro-tool`, `fabro-types`, `fabro-util`, `fabro-validate`, `fabro-vault`, `workflow-test-corpus` +- **Evidence:** lib/components/fabro-workflow/Cargo.toml — declares the DOT-based runner and component dependencies; lib/components/fabro-workflow/src/pipeline/mod.rs — exposes the ordered transform, validate, initialize, execute, and finalize phases + +### `fabro-build-support` — Rust Build-Script Support + +- **Purpose:** Supplies shared compile-time Git and Cargo profile metadata to Fabro application build scripts. +- **Paths:** `lib/foundation/build-support/**` +- **Entry points:** `lib/foundation/build-support/git_metadata.rs:collect_from`, `lib/foundation/build-support/git_metadata.rs:cargo_profile` +- **Owns:** Compile-time Git SHA discovery, Cargo rerun paths, and profile discovery +- **Evidence:** lib/foundation/build-support/Cargo.toml — declares the shared build-support package; lib/foundation/build-support/git_metadata.rs:BuildGitMetadata — defines build-script Git and profile metadata; lib/apps/fabro-cli/build.rs — consumes the shared metadata collector; lib/apps/fabro-server/build.rs — consumes the shared metadata collector + +### `fabro-build-tooling` — Fabro Build and Developer Tooling + +- **Purpose:** Runs repository build, documentation, SPA, container, benchmark, release, and test-support automation. +- **Paths:** `lib/foundation/fabro-dev/**`, `test/bin/release_test.sh`, `test/analysis/bench-tests-diff.sql` +- **Entry points:** `lib/foundation/fabro-dev/src/main.rs:main` +- **Owns:** Developer CLI dispatch, subprocess plans, generated-reference checks, build and release workflows, and benchmark analysis +- **Depends on:** `container-packaging-and-deployment`, `fabro-cli`, `fabro-config`, `fabro-macros-metadata`, `fabro-spa`, `fabro-util`, `fabro-web-app`, `public-documentation`, `repository-development-policy` +- **Evidence:** lib/foundation/fabro-dev/src/lib.rs:Command — dispatches build, Docker, docs, release, SPA, and benchmark commands + +### `fabro-api` — Generated Rust API Client + +- **Purpose:** Generates the low-level Rust HTTP client and API type facade from OpenAPI while reusing canonical product types and verifying wire parity. +- **Paths:** `lib/foundation/fabro-api/**` +- **Entry points:** `lib/foundation/fabro-api/build.rs:main`, `lib/foundation/fabro-api/src/lib.rs:ApiClient` +- **Owns:** OpenAPI compatibility transformations, generation settings, type replacement map, generated-client facade, and wire/type parity tests +- **Depends on:** `fabro-automation`, `fabro-config`, `fabro-environment`, `fabro-http-api-contract`, `fabro-model`, `fabro-types` +- **Evidence:** lib/foundation/fabro-api/build.rs:main — reads the OpenAPI contract and writes generated Rust code to OUT_DIR; lib/foundation/fabro-api/tests/run_event_round_trip.rs — verifies identity and JSON parity for canonical reused types + +### `fabro-auth` — Provider Credential Resolution + +- **Purpose:** Resolves provider credentials and headers from environment or vault sources, refreshes OAuth credentials, and drives authentication strategies. +- **Paths:** `lib/foundation/fabro-auth/**` +- **Entry points:** `lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver`, `lib/foundation/fabro-auth/src/strategy.rs:AuthStrategy` +- **Owns:** Credential-source precedence, provider discovery, OAuth refresh and write-back, header interpolation, and interactive auth state +- **Depends on:** `fabro-http`, `fabro-model`, `fabro-oauth`, `fabro-redact`, `fabro-static`, `fabro-types`, `fabro-vault` +- **Evidence:** lib/foundation/fabro-auth/Cargo.toml — declares typed provider credential resolution; lib/foundation/fabro-auth/src/resolve.rs:CredentialResolver::resolve — composes catalog policy, source lookup, headers, and refresh + +### `fabro-client` — High-Level Fabro Service Client + +- **Purpose:** Provides an authenticated Fabro service client over HTTP or Unix sockets with endpoint wrappers, SSE streams, refresh, and local auth storage. +- **Paths:** `lib/foundation/fabro-client/**` +- **Entry points:** `lib/foundation/fabro-client/src/client.rs:ClientBuilder::connect`, `lib/foundation/fabro-client/src/target.rs:ServerTarget` +- **Owns:** Connected transport state, operation wrappers, SSE buffering, token refresh, target normalization, and per-server CLI auth files +- **Depends on:** `fabro-api`, `fabro-http`, `fabro-model`, `fabro-static`, `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-client/Cargo.toml — distinguishes the high-level client from the generated API client; lib/foundation/fabro-client/src/client.rs:ClientState — owns transport, generated client, token, URL, and refresh coordination + +### `fabro-config` — Layered Configuration and Runtime Paths + +- **Purpose:** Parses, combines, migrates, validates, and resolves Fabro configuration layers into runtime settings and canonical paths. +- **Paths:** `lib/foundation/fabro-config/**` +- **Entry points:** `lib/foundation/fabro-config/src/builders.rs:ServerSettingsBuilder`, `lib/foundation/fabro-config/src/resolve/mod.rs` +- **Owns:** Source layers and merge semantics, defaults, parsing and validation, migrations, home/storage/runtime paths, daemon, envfile, and logging configuration +- **Depends on:** `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; lib/foundation/fabro-config/src/builders.rs — composes defaults and layers into dense runtime settings + +### `fabro-core` — Generic Graph Execution Kernel + +- **Purpose:** Executes generic directed graphs with handler, retry, lifecycle, cancellation, checkpoint, visit-limit, and stall-monitoring contracts. +- **Paths:** `lib/foundation/fabro-core/**` +- **Entry points:** `lib/foundation/fabro-core/src/executor.rs:Executor::run`, `lib/foundation/fabro-core/src/handler.rs:NodeHandler` +- **Owns:** Execution state, graph traversal, handler and lifecycle contracts, retry and visit decisions, cancellation, and stall watchdog +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-core/Cargo.toml — identifies a generic kernel without higher-level workflow dependencies; lib/foundation/fabro-core/src/executor.rs:Executor::run — owns the traversal and execution lifecycle + +### `fabro-db` — Shared SQLite Database Foundation + +- **Purpose:** Opens and migrates the shared SQLite database, manages rollback snapshots and permissions, and defines the bundled schema. +- **Paths:** `lib/foundation/fabro-db/**` +- **Entry points:** `lib/foundation/fabro-db/src/lib.rs:Database::connect`, `lib/foundation/fabro-db/src/lib.rs:Database::migrate` +- **Owns:** SQLite pool policy, migration registry, snapshots, backup paths, permissions, tables, and indexes +- **Evidence:** lib/foundation/fabro-db/Cargo.toml — declares the shared SQLite foundation; lib/foundation/fabro-db/migrations/2026071101_secrets.sql — is one migration in the compiled shared schema + +### `fabro-http` — Shared HTTP Transport Construction + +- **Purpose:** Centralizes reqwest type exposure and synchronous and asynchronous HTTP client construction with Fabro proxy policy. +- **Paths:** `lib/foundation/fabro-http/**` +- **Entry points:** `lib/foundation/fabro-http/src/lib.rs:HttpClientBuilder`, `lib/foundation/fabro-http/src/lib.rs:test_http_client` +- **Owns:** Approved reqwest facade, proxy-policy resolution, client builders, and deterministic no-proxy test clients +- **Depends on:** `fabro-static` +- **Evidence:** lib/foundation/fabro-http/Cargo.toml — declares the shared reqwest wrapper; lib/foundation/fabro-http/src/lib.rs:ProxyPolicy — defines the common transport-construction policy + +### `fabro-macros-metadata` — Compile-Time Macros and Option Metadata + +- **Purpose:** Supplies Fabro derive and attribute macros plus the runtime option-metadata model used by configuration and documentation tooling. +- **Paths:** `lib/foundation/fabro-macros/**`, `lib/foundation/fabro-options-metadata/**` +- **Entry points:** `lib/foundation/fabro-macros/src/lib.rs:derive_options_metadata`, `lib/foundation/fabro-options-metadata/src/lib.rs:OptionsMetadata` +- **Owns:** Macro expansion for E2E gates, layer combination, and option metadata plus the runtime visitor and option-tree representation +- **Evidence:** lib/foundation/fabro-macros/src/options_metadata.rs:derive_impl — generates implementations against the runtime metadata crate; lib/foundation/fabro-macros/tests/options_metadata.rs — tests the compiler/runtime pair together + +### `fabro-model` — LLM Model and Provider Catalog + +- **Purpose:** Defines provider and model identity, capabilities, billing metadata, embedded catalog data, override merging, and selection. +- **Paths:** `lib/foundation/fabro-model/**` +- **Entry points:** `lib/foundation/fabro-model/src/catalog.rs:Catalog::builtin`, `lib/foundation/fabro-model/src/catalog.rs:Catalog::select` +- **Owns:** Provider and model IDs, catalog sources and indexes, auth declarations, capabilities, controls, codecs, reasoning, pricing, and billing +- **Depends on:** `fabro-static` +- **Evidence:** lib/foundation/fabro-model/Cargo.toml — names model metadata and resolution as the crate responsibility; lib/foundation/fabro-model/src/catalog/providers/openai.toml — is one tracked built-in provider catalog source + +### `fabro-oauth` — OAuth PKCE and Callback Flow + +- **Purpose:** Implements generic OAuth PKCE authorization, loopback callback serving, browser launch, code exchange, and token refresh. +- **Paths:** `lib/foundation/fabro-oauth/**` +- **Entry points:** `lib/foundation/fabro-oauth/src/lib.rs:run_browser_flow`, `lib/foundation/fabro-oauth/src/lib.rs:refresh_token` +- **Owns:** PKCE and state, authorization URLs, callback listener and shutdown, callback validation, exchange, and refresh +- **Depends on:** `fabro-http`, `fabro-redact`, `fabro-static`, `fabro-util` +- **Evidence:** lib/foundation/fabro-oauth/Cargo.toml — declares a generic OAuth 2.0 PKCE flow; lib/foundation/fabro-oauth/src/lib.rs:CallbackHandle — owns the ephemeral callback server lifecycle + +### `fabro-proc` — OS Process Primitives + +- **Purpose:** Wraps platform process primitives for signals, groups, advisory locks, pre-exec hooks, liveness, and process-title rewriting. +- **Paths:** `lib/foundation/fabro-proc/**` +- **Entry points:** `lib/foundation/fabro-proc/src/signal.rs:process_running`, `lib/foundation/fabro-proc/src/pre_exec.rs:pre_exec_setsid` +- **Owns:** Unix signals and process groups, cross-platform liveness, locks, child pre-exec configuration, and argv/title state +- **Evidence:** lib/foundation/fabro-proc/Cargo.toml — describes safe process-management wrappers; lib/foundation/fabro-proc/c/capture_argv.c — establishes the FFI boundary for title rewriting + +### `fabro-redact` — Secret and Credential Redaction + +- **Purpose:** Detects and redacts credential-like content in strings, URLs, JSON, and JSONL using embedded rules and entropy scanning. +- **Paths:** `lib/foundation/fabro-redact/**` +- **Entry points:** `lib/foundation/fabro-redact/src/lib.rs:redact_string`, `lib/foundation/fabro-redact/src/safe_url.rs:DisplaySafeUrl` +- **Owns:** Rule source and engine, entropy thresholds, overlap merging, structured redaction policy, and safe URL display +- **Evidence:** lib/foundation/fabro-redact/build.rs:main — compiles the tracked Gitleaks rule source into OUT_DIR; lib/foundation/fabro-redact/src/lib.rs:redact_string — composes entropy and rule-based detection + +### `fabro-static` — Shared Static Conventions + +- **Purpose:** Defines dependency-light canonical environment-variable names and registries for bootstrap and optional vault secrets. +- **Paths:** `lib/foundation/fabro-static/**` +- **Entry points:** `lib/foundation/fabro-static/src/env_vars.rs:EnvVars`, `lib/foundation/fabro-static/src/secret_registry.rs:is_bootstrap_secret` +- **Owns:** Canonical environment names and bootstrap and optional secret classification +- **Evidence:** lib/foundation/fabro-static/Cargo.toml — declares a no-dependency static registry; lib/foundation/fabro-static/src/env_vars.rs:EnvVars — centralizes environment names used across the workspace + +### `fabro-telemetry` — Analytics and Crash Telemetry + +- **Purpose:** Initializes analytics and crash reporting, builds anonymous context, buffers events, and delivers them across CLI and server lifecycles. +- **Paths:** `lib/foundation/fabro-telemetry/**` +- **Entry points:** `lib/foundation/fabro-telemetry/src/lib.rs:init_cli`, `lib/foundation/fabro-telemetry/src/lib.rs:shutdown` +- **Owns:** Process-global telemetry state, identifiers, buffer thread, event context, command sanitization, Segment delivery, and panic capture +- **Depends on:** `fabro-http`, `fabro-static`, `fabro-util` +- **Evidence:** lib/foundation/fabro-telemetry/Cargo.toml — declares analytics and crash reporting; lib/foundation/fabro-telemetry/src/lib.rs:Global — owns sender, identity, context, level, and background thread + +### `fabro-template` — Template Rendering and Dependency Discovery + +- **Purpose:** Renders MiniJinja templates with source-aware diagnostics, rooted stores, wrappers, and static dependency discovery. +- **Paths:** `lib/foundation/fabro-template/**` +- **Entry points:** `lib/foundation/fabro-template/src/lib.rs:render_named`, `lib/foundation/fabro-template/src/store.rs:TemplateStore` +- **Owns:** Template context, render modes, diagnostics, include safety, stores, caching and recording, and dependency closure +- **Depends on:** `fabro-types`, `fabro-util` +- **Evidence:** lib/foundation/fabro-template/Cargo.toml — declares the shared rendering boundary; lib/foundation/fabro-template/src/dependency.rs — owns include and import extraction and closure discovery + +### `fabro-test` — Shared Integration-Test Infrastructure + +- **Purpose:** Provides isolated CLI/server test contexts, twin and live mode control, process harnessing, snapshot normalization, and HTTP assertions. +- **Paths:** `lib/foundation/fabro-test/**` +- **Entry points:** `lib/foundation/fabro-test/src/lib.rs:TestContext`, `lib/foundation/fabro-test/src/lib.rs:TestMode` +- **Owns:** Temporary test home and storage, managed processes, mode and secret gating, environment isolation, snapshot filters, twins, and HTTP diagnostics +- **Depends on:** `fabro-config`, `fabro-http`, `fabro-install`, `fabro-proc`, `fabro-static`, `fabro-types`, `fabro-util`, `twin-github`, `twin-openai`, `workflow-test-corpus` +- **Evidence:** lib/foundation/fabro-test/Cargo.toml — declares shared integration-test utilities and twin dependencies; lib/foundation/fabro-test/src/lib.rs:TestContext — owns isolated paths, subprocesses, filters, and managed server state + +### `fabro-types` — Shared Product Contracts and State Records + +- **Purpose:** Defines serializable identifiers, settings, run and session events, projections, and other product vocabulary exchanged across Fabro boundaries. +- **Paths:** `lib/foundation/fabro-types/**` +- **Entry points:** `lib/foundation/fabro-types/src/lib.rs`, `lib/foundation/fabro-types/src/run_event/mod.rs:RunEvent` +- **Owns:** Canonical serde shapes and IDs for runs, stages, sessions, events, settings, projections, sandboxes, integrations, billing, and repositories +- **Depends on:** `fabro-model`, `fabro-util` +- **Evidence:** lib/foundation/fabro-types/Cargo.toml — describes shared record structs and enums; lib/foundation/fabro-types/src/lib.rs — is the single facade for canonical product vocabulary + +### `fabro-util` — Cross-Cutting Runtime and CLI Utilities + +- **Purpose:** Provides shared environment, filesystem, shell, terminal, logging, token, error, time, backoff, warning, and glob primitives. +- **Paths:** `lib/foundation/fabro-util/**` +- **Entry points:** `lib/foundation/fabro-util/src/lib.rs`, `lib/foundation/fabro-util/src/shell.rs:shell_quote` +- **Owns:** Low-level helper contracts plus warning, buffered log, environment, home, token, terminal, backoff, error, and glob state +- **Depends on:** `fabro-static` +- **Evidence:** lib/foundation/fabro-util/Cargo.toml — identifies shared runtime and terminal helpers; lib/foundation/fabro-util/src/run_log.rs — owns the buffered run-log guard lifecycle + +### `fabro-vault` — Secret Vault and SQLite Store + +- **Purpose:** Validates and stores workflow-visible secrets in file, memory, or SQLite stores with revision-aware updates and legacy import. +- **Paths:** `lib/foundation/fabro-vault/**` +- **Entry points:** `lib/foundation/fabro-vault/src/lib.rs:Vault::load`, `lib/foundation/fabro-vault/src/store.rs:SecretStore::open` +- **Owns:** Secret validation and redacted entries, atomic file persistence, SQL CRUD, revisions, snapshots, and legacy import +- **Depends on:** `fabro-db`, `fabro-static`, `fabro-types` +- **Evidence:** lib/foundation/fabro-vault/Cargo.toml — declares workflow-visible secret storage; lib/foundation/fabro-vault/src/store.rs:SecretStore::replace_if_revision — exposes concurrent refresh write-back semantics + +### `fabro-web-app` — Fabro Browser Application + +- **Purpose:** Builds and runs the React SPA for normal operations and first-run installation. +- **Paths:** `apps/fabro-web/**` +- **Excludes:** `apps/fabro-web/app/components/playground/**` +- **Entry points:** `apps/fabro-web/app/entry.tsx`, `apps/fabro-web/scripts/build.ts` +- **Owns:** Browser bundle and route graphs, install flow, shared browser runtime and UI, product operations UX, and public assets +- **Depends on:** `fabro-api-client-generation`, `fabro-http-api-contract`, `fabro-workflow-playground` +- **Evidence:** apps/fabro-web/package.json — declares the React application, custom build, tests, and API-client workspace edge; apps/fabro-web/app/entry.tsx — creates the browser root and selects normal or install routing + +### `fabro-workflow-playground` — Browser Workflow Playground + +- **Purpose:** Provides a self-contained workflow drafting, simulation, chat, visualization, file-generation, download, and run-launch surface. +- **Paths:** `apps/fabro-web/app/components/playground/**` +- **Entry points:** `apps/fabro-web/app/components/playground/playground.tsx:Playground`, `apps/fabro-web/app/components/playground/state/draft.ts:WorkflowDraft` +- **Owns:** Workflow draft schema and persistence, simulation, canvas, chat adaptation, generated project files, download, and launch controls +- **Depends on:** `fabro-http-api-contract`, `fabro-web-app` +- **Evidence:** apps/fabro-web/app/components/playground/playground.tsx:Playground — exposes a prop boundary framed for re-embedding; apps/fabro-web/app/components/playground/state/persist.ts:usePlaygroundDraft — owns versioned browser persistence + +### `fabro-marketing-site` — Fabro Marketing Site + +- **Purpose:** Builds and deploys the public Fabro site with landing content, blog, roadmap, showcase, install resources, and social assets. +- **Paths:** `apps/marketing/**`, `test/bin/install_test.sh` +- **Excludes:** `apps/marketing/.vercel/**` +- **Entry points:** `apps/marketing/src/pages/index.astro`, `apps/marketing/astro.config.mjs`, `apps/marketing/public/install.sh` +- **Owns:** Astro routes and layout, content collections, marketing presentation, workflow showcases, install resources, redirects, and deployment configuration +- **Evidence:** apps/marketing/package.json — declares an independent Astro application; apps/marketing/src/content.config.ts — defines typed roadmap, blog, and showcase collections; test/bin/install_test.sh — black-box tests the site's canonical install script + +### `fabro-remotion-video` — Fabro Remotion Composition + +- **Purpose:** Renders the branded FabroIntro motion-graphics video. +- **Paths:** `apps/remotion/**` +- **Entry points:** `apps/remotion/src/index.ts`, `apps/remotion/src/Root.tsx:RemotionRoot` +- **Owns:** Composition registration, frame timeline, image format, logo animation, brand assets, and rendered-video lifecycle +- **Evidence:** apps/remotion/package.json — declares an independent Remotion project and render target; apps/remotion/src/Root.tsx:RemotionRoot — declares composition identity, dimensions, frame rate, and duration + +### `fabro-api-client-generation` — TypeScript API Client Generation + +- **Purpose:** Configures, normalizes, and type-checks the generated TypeScript/Axios client for the Fabro HTTP contract. +- **Paths:** `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` +- **Entry points:** `lib/packages/fabro-api-client/package.json:scripts.generate`, `lib/packages/fabro-api-client/scripts/normalize-generated.ts` +- **Owns:** Generator versions and options, output location, normalization, strict compilation, and hand-written generated-shape invariants +- **Depends on:** `fabro-http-api-contract` +- **Evidence:** lib/packages/fabro-api-client/package.json — invokes pinned OpenAPI Generator against the shared YAML and writes src; lib/packages/fabro-api-client/tests/principal-exhaustive.ts — asserts a generated union contract at compile time + +### `public-documentation` — Public Documentation + +- **Purpose:** Owns authored Fabro user documentation, Mintlify presentation, the repository landing page, and published web-screenshot maintenance. +- **Paths:** `README.md`, `docs/public/**`, `docs/internal/updating-web-screenshots.md` +- **Excludes:** `docs/public/api-reference/fabro-api.yaml`, `docs/public/changelog/**`, `docs/public/images/*-workflow.svg`, `docs/public/images/tutorial-*.svg`, `docs/public/images/brave-search-research.svg`, `docs/public/images/how-fabro-works.svg`, `docs/public/images/nlspec-conformance.svg`, `docs/public/images/plan-implement-readme.svg` +- **Entry points:** `README.md`, `docs/public/docs.json`, `docs/public/getting-started/introduction.mdx` +- **Owns:** Mintlify navigation and presentation, public guides and reference prose, curated images and screenshots, syntax definitions, and repository overview +- **Depends on:** `documentation-demo-workflows`, `fabro-cli`, `fabro-http-api-contract`, `public-release-history` +- **Evidence:** docs/public/docs.json — declares the Mintlify theme, navigation, OpenAPI, and changelog surfaces; README.md — links to the published docs and embeds their canonical assets; docs/internal/updating-web-screenshots.md — defines the screenshot capture and verification workflow + +### `public-release-history` — Published Changelog + +- **Purpose:** Preserves and publishes dated user-facing release and change records independently of current reference documentation. +- **Paths:** `docs/public/changelog/**` +- **Entry points:** `docs/public/changelog/2026-07-25.mdx` +- **Owns:** Dated titles, migration warnings, feature summaries, and historical behavior notes +- **Depends on:** `public-documentation` +- **Evidence:** docs/public/docs.json — gives the changelog its own top-level tab and enumerates every page; docs/public/changelog/2026-07-25.mdx — is the newest dated release entry at the assessed revision + +### `fabro-http-api-contract` — Fabro HTTP API Contract + +- **Purpose:** Defines the OpenAPI-first wire contract used by the server, generated clients, conformance tests, and published API reference. +- **Paths:** `docs/public/api-reference/fabro-api.yaml` +- **Entry points:** `docs/public/api-reference/fabro-api.yaml` +- **Owns:** HTTP routes, request and response schemas, authentication declarations, and API-facing wire documentation +- **Evidence:** AGENTS.md — identifies the OpenAPI file as the HTTP interface source of truth; lib/foundation/fabro-api/build.rs:main — consumes the contract for Rust generation; lib/apps/fabro-server/tests/it/openapi_conformance.rs — reads it for router conformance + +### `documentation-demo-workflows` — Executable Documentation Demos + +- **Purpose:** Provides runnable workflow definitions, configuration, and prompts used by public tutorials and demonstrations. +- **Paths:** `docs/internal/demo/*.fabro`, `docs/internal/demo/*.toml`, `docs/internal/demo/prompts/**` +- **Entry points:** `docs/internal/demo/01-hello.fabro`, `docs/internal/demo/14-search-imagegen.toml` +- **Owns:** Executable example graphs, the image-generation run configuration, and shared demo prompt text +- **Depends on:** `fabro-cli`, `fabro-sandbox`, `fabro-workflow` +- **Evidence:** docs/public/tutorials/hello-world.mdx — invokes a demo workflow path directly; docs/internal/demo/14-search-imagegen.toml — selects the demo graph, environment, and output assets + +### `internal-engineering-guidance` — Internal Engineering Guidance + +- **Purpose:** Records active repository-wide engineering policies and maintained architecture and runtime contracts. +- **Paths:** `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:** `docs/internal/events-strategy.md`, `docs/internal/testing-strategy.md`, `docs/internal/error-handling-strategy.md` +- **Owns:** Logging, events, testing, migrations, secrets, error handling, React effects, panic, event catalog, LLM resolution, parallelism, and run-file guidance +- **Depends on:** `fabro-cli`, `fabro-config`, `fabro-server`, `fabro-types`, `fabro-web-app`, `fabro-workflow` +- **Evidence:** AGENTS.md — makes the strategy and policy documents mandatory before related changes; docs/internal/events.md — is the maintained serialized event catalog + +### `product-context` — Internal Product Context + +- **Purpose:** Maintains product intent, audience, current shape, success signals, and stable technical and product constraints. +- **Paths:** `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, success metrics, and product-level technical requirements +- **Evidence:** docs/internal/product/current-state.md — identifies itself as a concise current product snapshot; docs/internal/product/technical-requirements.md — records stable constraints for product changes + +### `twin-openai` — OpenAI Protocol Twin + +- **Purpose:** Provides a deterministic OpenAI-compatible HTTP service for black-box and protocol-contract tests. +- **Paths:** `test/twin/openai/**` +- **Entry points:** `test/twin/openai/src/main.rs:main`, `test/twin/openai/src/lib.rs:build_app` +- **Owns:** OpenAI-compatible routes, scenario queues, request logs, deterministic IDs, streaming and failure behavior, admin APIs, and debug UI +- **Depends on:** `fabro-http`, `fabro-static` +- **Evidence:** test/twin/openai/Cargo.toml — declares a fake OpenAI-compatible library and binary; test/twin/openai/src/state.rs:AppState — owns namespaced counters, scenario queues, and request logs + +### `twin-github` — GitHub Protocol Twin + +- **Purpose:** Provides an in-process fake GitHub service with seeded mutable state and temporary Git repositories. +- **Paths:** `test/twin/github/**` +- **Entry points:** `test/twin/github/src/server.rs:TestServer::start`, `test/twin/github/src/server.rs:build_router` +- **Owns:** Fake GitHub App, OAuth, REST, GraphQL, smart-HTTP, repositories, pull requests, releases, projects, tokens, and test keys +- **Depends on:** `fabro-http` +- **Evidence:** test/twin/github/Cargo.toml — declares an independent fake GitHub service; test/twin/github/src/state.rs:AppState — owns the seeded and mutable GitHub-domain state + +### `workflow-test-corpus` — Shared Workflow Compatibility Fixtures + +- **Purpose:** Supplies reusable workflow, compatibility, configuration, prompt, partial, and template inputs to cross-crate tests. +- **Paths:** `test/*.fabro`, `test/attractor/**`, `test/dot-compatibility/**`, `test/templated_inputs/**`, `test/templated_unbound_imported/**`, `test/templated_unbound_partial/**`, `test/templates/**` +- **Entry points:** `test/simple.fabro`, `test/attractor/simple_example.dot`, `test/templates/static_dependencies/workflow.fabro` +- **Owns:** Representative workflow syntax and behavior cases, Attractor compatibility graphs, DOT fixtures, and template dependency trees +- **Evidence:** lib/foundation/fabro-test/src/lib.rs:TestContext::install_fixture — resolves named inputs from the shared test directory; lib/components/fabro-workflow/tests/it/attractor_compat.rs — enumerates the Attractor corpus + +### `documentation-workflow-tests` — Documentation Workflow Conformance + +- **Purpose:** Extracts, curates, validates, preflights, and executes workflow examples and companion files derived from Fabro documentation. +- **Paths:** `test/docs/**` +- **Entry points:** `test/docs/run_tests.sh`, `test/docs/extract_dots.py:main`, `test/docs/CHECKLIST.md` +- **Owns:** Documentation example corpus, extraction and stub generation, validation and execution phases, parallel runner state, and checklist +- **Depends on:** `fabro-cli`, `fabro-workflow`, `public-documentation` +- **Evidence:** test/docs/run_tests.sh — discovers and runs every tracked documentation workflow; test/docs/extract_dots.py:main — extracts complete graphs and creates companion fixtures + +### `swe-bench-evaluation` — SWE-Bench Evaluation Workflow + +- **Purpose:** Generates Fabro patches for SWE-bench Lite, grades them, monitors runs, builds environments, and records normalized summaries. +- **Paths:** `evals/swe-bench/*.py`, `evals/swe-bench/*.fabro`, `evals/swe-bench/*.txt`, `evals/swe-bench/README.md` +- **Entry points:** `evals/swe-bench/run_eval.py:main`, `evals/swe-bench/evaluate_daytona.py:main`, `evals/swe-bench/record_results.py:main` +- **Owns:** Dataset selection, per-instance workflow generation, sandbox specs, subprocess orchestration, patch extraction, grading, monitoring, and scoreboard schema +- **Depends on:** `fabro-cli`, `fabro-sandbox`, `fabro-workflow` +- **Evidence:** evals/swe-bench/README.md — defines the generate, evaluate, and record lifecycle; evals/swe-bench/run_eval.py:run_instance — creates per-instance Fabro inputs and invokes the CLI + +### `repository-development-policy` — Repository Development Policy + +- **Purpose:** Defines workspace, dependency, formatting, lint, test, version-control, contributor, and coding-agent development contracts. +- **Paths:** `.cargo/**`, `.config/**`, `.gitattributes`, `.gitignore`, `AGENTS.md`, `CONTRIBUTING.md`, `Cargo.toml`, `package.json`, `bunfig.toml`, `clippy.toml`, `rustfmt.toml` +- **Entry points:** `Cargo.toml:[workspace]`, `package.json:workspaces`, `AGENTS.md` +- **Owns:** Workspace membership and policy, tool aliases, test profiles, lints and formatting, tracked path treatment, contributor workflow, and agent instructions +- **Depends on:** `fabro-build-tooling` +- **Evidence:** Cargo.toml — declares Rust workspace members, dependencies, lints, and profiles; .cargo/config.toml — exposes cargo dev and repository test policy; AGENTS.md — defines architectural and workflow instructions + +### `repository-ci` — Pull-Request and Branch CI + +- **Purpose:** Runs branch and pull-request validation for Rust and TypeScript and configures GitHub Actions static validation. +- **Paths:** `.github/workflows/rust.yml`, `.github/workflows/typescript.yml`, `.github/zizmor.yml` +- **Entry points:** `.github/workflows/rust.yml`, `.github/workflows/typescript.yml` +- **Owns:** Path triggers, formatting, linting, generated-doc checks, tests, E2E modes, TypeScript checks, builds, concurrency, and workflow-lint policy +- **Depends on:** `fabro-api-client-generation`, `fabro-build-tooling`, `fabro-web-app`, `public-documentation`, `repository-development-policy`, `twin-openai` +- **Evidence:** .github/workflows/rust.yml — runs Rust formatting, lint, generated-document, workspace test, and twin E2E jobs; .github/workflows/typescript.yml — checks and builds the Bun workspace and embedded SPA + +### `release-distribution-automation` — Release and Package Publication + +- **Purpose:** Cuts nightly releases and publishes CLI archives, GitHub Releases, multi-architecture images, attestations, and Homebrew formulas. +- **Paths:** `.github/workflows/nightly.yml`, `.github/workflows/release.yml`, `installer/**` +- **Entry points:** `.github/workflows/nightly.yml`, `.github/workflows/release.yml`, `installer/fabro.rb.template` +- **Owns:** Nightly tag creation, release matrix, archives and checksums, attestations, GitHub Releases, image publication, and Homebrew channels +- **Depends on:** `container-packaging-and-deployment`, `fabro-build-tooling`, `fabro-cli`, `fabro-web-app`, `repository-development-policy` +- **Evidence:** .github/workflows/release.yml — packages target matrices and publishes releases, images, and formulas; installer/fabro.rb.template — defines platform archives, checksums, installation, and smoke tests + +### `container-packaging-and-deployment` — Container Packaging and Deployment + +- **Purpose:** Packages Fabro as a runtime container and defines local, production, Tailscale, and split-web Compose deployments. +- **Paths:** `.dockerignore`, `.env.example`, `Dockerfile`, `docker-compose*.yaml`, `docker/**` +- **Entry points:** `Dockerfile`, `docker/entrypoint.sh`, `docker-compose.yaml` +- **Owns:** Container image layout, runtime packages and user, storage and Docker socket handoff, preflight checks, proxy behavior, Compose topology, volumes, ports, and health checks +- **Depends on:** `fabro-build-tooling`, `fabro-cli`, `fabro-server`, `fabro-web-app` +- **Evidence:** Dockerfile — consumes the architecture-specific staged binary and installs the runtime entrypoint; docker-compose.yaml — defines the primary image, state, socket, port, and health-check contract + +### `fabro-repository-automation` — Fabro-Native Repository Automation + +- **Purpose:** Configures Fabro's development environment and named workflow graphs, prompts, permissions, and project defaults for repository work. +- **Paths:** `.fabro/Dockerfile`, `.fabro/project.toml`, `.fabro/workflows/**` +- **Excludes:** `.fabro/workflows/goal/workflow.svg` +- **Entry points:** `.fabro/project.toml`, `.fabro/workflows/implement-plan/workflow.fabro`, `.fabro/workflows/smoke/workflow.fabro` +- **Owns:** Repository pull-request defaults, Daytona development environment, named workflow catalog, local prompts, GitHub permissions, and maintenance commands +- **Depends on:** `fabro-build-tooling`, `fabro-cli`, `fabro-config`, `fabro-github`, `fabro-graphviz`, `fabro-sandbox`, `fabro-workflow`, `repository-development-policy` +- **Evidence:** .fabro/project.toml — selects the repository environment, resources, lifecycle, labels, and pull-request defaults; .fabro/workflows/implement-plan/workflow.fabro — invokes repository Cargo and Bun verification and build tooling + +### `coding-agent-automation` — Repository Coding-Agent Automation + +- **Purpose:** Supplies repository-local review prompts, documentation and changelog skills, edit hooks, and an image-generation helper to coding agents. +- **Paths:** `.ai/prompts/**`, `.claude/settings.json`, `.claude/skills/**`, `bin/agent/**` +- **Excludes:** `.claude/skills/*/watermark` +- **Entry points:** `.ai/prompts/code-review-fast.md`, `.claude/skills/changelog/SKILL.md`, `.claude/skills/docs/SKILL.md`, `bin/agent/imagegen` +- **Owns:** Code-review orchestration, changelog and documentation maintenance, post-edit formatting hook, and agent image-generation command +- **Depends on:** `public-documentation`, `public-release-history` +- **Evidence:** .ai/prompts/code-review-deep-1.md — begins the multi-stage review artifact pipeline; .claude/skills/docs/SKILL.md — defines the code-to-public-documentation update workflow; .claude/settings.json — registers the repository post-edit Rust formatting hook + +## Exclusions and Unmapped Code + +- `lib/packages/fabro-api-client/src/**` — Generated TypeScript/Axios output written by the package's pinned OpenAPI Generator command; generated headers and .openapi-generator metadata corroborate the output boundary. +- `apps/marketing/.vercel/**` — Vercel CLI link metadata whose own README identifies it as automatically created local project/team state. +- `lib/apps/fabro-spa/assets/**` — Placeholder for ignored embedded-SPA build output; repository instructions and .gitignore identify the directory as generated. +- `docs/brainstorms/**`, `docs/ideation/**`, `docs/plans/**`, `docs/superpowers/plans/**`, `docs/superpowers/specs/**`, `docs/internal/cargo-target-apfs-churn-plan.md`, `docs/internal/cli-workflow-coupling-audit.md`, `docs/internal/event-schema-competitive-analysis.md`, `docs/internal/fabro-event-schema-v2-proposal.md`, `docs/internal/mcp-server-qa-test-plan.md`, `docs/internal/plan-events-as-source-of-truth-follow-ups.md`, `docs/internal/plan-events-as-source-of-truth.md`, `docs/internal/slow-test-opportunities-2026-04-07.md` — Point-in-time brainstorms, implementation plans, audits, research, handoffs, and superseded proposals rather than maintained source contracts. +- `docs/internal/demo/*.svg`, `docs/internal/demo/*.png`, `docs/public/images/*-workflow.svg`, `docs/public/images/tutorial-*.svg`, `docs/public/images/brave-search-research.svg`, `docs/public/images/how-fabro-works.svg`, `docs/public/images/nlspec-conformance.svg`, `docs/public/images/plan-implement-readme.svg` — Graphviz-generated SVG and PNG renderings whose executable or documentation graph sources remain assigned. +- `docs/internal/licenses/**` — Vendored third-party Graphviz license text rather than Fabro source. +- `evals/swe-bench/scoreboard/**` — Committed evaluation records generated by record_results.py, not executable evaluation source. +- `.fabro/skills/rust-style-guide/**` — Vendored policy payload copied from the brynary/rust-style-guide repository at a recorded commit. +- `Cargo.lock`, `bun.lock` — Machine-maintained dependency resolution snapshots consumed in locked or frozen mode. +- `.claude/skills/*/watermark` — Generated progress-state commit SHAs overwritten by the owning skill workflows. +- `.fabro/project.toml.bak` — Stale backup of the canonical .fabro/project.toml configuration. +- `.fabro/workflows/goal/workflow.svg`, `.github/assets/**` — Non-runtime workflow illustration and unreferenced pull-request review screenshots. +- `CLAUDE.md`, `install.sh`, `install.md` — Tracked symlink aliases whose canonical targets are assigned elsewhere, avoiding duplicate assessment of identical content. +- `LICENSE.md` — Repository legal text rather than an implementation or documentation component. +- `docs/internal/assets/brand/github-header-v2-mesh.png` — unmapped +- `docs/internal/assets/brand/github-header-v2-mesh.svg` — unmapped +- `docs/internal/assets/brand/logo/logotype-black.svg` — unmapped +- `docs/internal/assets/brand/logo/logotype.svg` — unmapped +- `docs/internal/assets/brand/logo/symbol-black.svg` — unmapped +- `docs/internal/assets/brand/logo/symbol.svg` — unmapped +- `docs/internal/assets/brand/palette-lockups.svg` — unmapped +- `docs/internal/assets/brand/palette-mockup-icons.svg` — unmapped +- `docs/internal/assets/brand/palette-mockup.svg` — unmapped +- `docs/internal/assets/brand/palette.png` — unmapped +- `docs/internal/assets/brand/palette.svg` — unmapped +- `docs/internal/assets/brand/social-card.html` — unmapped +- `docs/internal/assets/brand/social-card.png` — unmapped +- `docs/internal/assets/brand/twitter-card-v0.176.1.html` — unmapped +- `docs/internal/assets/brand/twitter-card-v0.176.1.png` — unmapped + +## Open Questions + +- Should the currently unreferenced docs/internal/assets brand collateral be assigned to a maintained brand component, or remain explicitly unmapped until an ownership and update workflow is identified? +- Should the first-run browser installer become a separate component if its route and state lifecycle gains an independent entry point, rather than remaining inside fabro-web-app? +- Should fabro-workflow eventually split run-operation/materialization ownership from pipeline execution if those facades acquire independent state and public contracts? diff --git a/.chisel/cartography/work/docs.md b/.chisel/cartography/work/docs.md new file mode 100644 index 000000000..482b37bea --- /dev/null +++ b/.chisel/cartography/work/docs.md @@ -0,0 +1,238 @@ +# 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/.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`. diff --git a/.chisel/cartography/work/ops.md b/.chisel/cartography/work/ops.md new file mode 100644 index 000000000..ef4b6c16a --- /dev/null +++ b/.chisel/cartography/work/ops.md @@ -0,0 +1,461 @@ +# 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 ` 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//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 ` as resolving + `.fabro/workflows//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/**`? diff --git a/.chisel/cartography/work/review.md b/.chisel/cartography/work/review.md new file mode 100644 index 000000000..e71fa8395 --- /dev/null +++ b/.chisel/cartography/work/review.md @@ -0,0 +1,198 @@ +# 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. diff --git a/.chisel/cartography/work/rust-apps.md b/.chisel/cartography/work/rust-apps.md new file mode 100644 index 000000000..473455896 --- /dev/null +++ b/.chisel/cartography/work/rust-apps.md @@ -0,0 +1,216 @@ +# 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. diff --git a/.chisel/cartography/work/rust-components.md b/.chisel/cartography/work/rust-components.md new file mode 100644 index 000000000..64f672a17 --- /dev/null +++ b/.chisel/cartography/work/rust-components.md @@ -0,0 +1,391 @@ +# 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. diff --git a/.chisel/cartography/work/rust-foundation.md b/.chisel/cartography/work/rust-foundation.md new file mode 100644 index 000000000..088542416 --- /dev/null +++ b/.chisel/cartography/work/rust-foundation.md @@ -0,0 +1,389 @@ +# 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. diff --git a/.chisel/cartography/work/tests-evals.md b/.chisel/cartography/work/tests-evals.md new file mode 100644 index 000000000..7b66d5825 --- /dev/null +++ b/.chisel/cartography/work/tests-evals.md @@ -0,0 +1,332 @@ +# 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? diff --git a/.chisel/cartography/work/validate-render.mjs b/.chisel/cartography/work/validate-render.mjs new file mode 100644 index 000000000..33f1e4174 --- /dev/null +++ b/.chisel/cartography/work/validate-render.mjs @@ -0,0 +1,271 @@ +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.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`); diff --git a/.chisel/cartography/work/web.md b/.chisel/cartography/work/web.md new file mode 100644 index 000000000..0441611e4 --- /dev/null +++ b/.chisel/cartography/work/web.md @@ -0,0 +1,305 @@ +# 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.