scriptoriumadmin/fabro
1
0
Fork 0
mirror of https://github.com/fabro-sh/fabro.git synced 2026-09-05 08:10:39 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10
fabro/.chisel/cartography/work/rust-apps.md
Bryan Helmkamp 6bb6b5efcc
Add codebase cartography map
2026-07-27 10:15:42 -04:00

14 KiB
Raw Permalink Blame History

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:

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:

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.