crashlabs/huskies
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 26 Wiki Activity

chore: regenerate STACK.md source map from module doc-comments

Browse Source 
Walked server/src/, frontend/src/, and crates/, extracting each module's
//! doc-comment to build a directory-level source map. One row per
directory + one row per top-level file.

Replaces the hand-written stopgap from 5d6757dd with content auto-derived
from the codebase, so it stays useful as decomposes happen — the
descriptions come from mod.rs, not from my recollection of where things
live.

Still a stopgap until 819 (auto-generated source-map-gen) lands and gets
wired into the agent spawn path, but the content is closer to what 819
will produce.
This commit is contained in:
dave
2026-04-28 15:50:29 +00:00
parent bf17fc14af
commit bb779a0b0f
1 changed files with 122 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.huskies/specs/tech/STACK.md
+122 -135
View File
@@ -32,154 +32,141 @@ website/ — Static marketing/docs site
## Source Map ## Source Map
### Backend roots One row per directory or top-level file. Descriptions are pulled from the module's `//!` doc-comment where present. **Use this to know where to look — do not re-discover the codebase via grep.**
| Path | Purpose |
|------|---------|
| `server/src/main.rs` | Binary entry; CLI parsing; server startup |
| `server/src/config/` | `project.toml` parsing |
| `server/src/state.rs` | Global mutable session state |
| `server/src/store.rs` | JSON-backed KV store for settings |
| `server/src/gateway.rs` | Multi-project gateway mode (route builder, MCP proxy) |
| `server/src/agent_mode.rs` | Headless build-agent mode |
| `server/src/services.rs` | Top-level service registry / wiring |
| `server/src/workflow.rs` | Cross-cutting workflow helpers |
### Agents ### Top-level backend files (`server/src/`)
| Path | Purpose |
|------|---------|
| `server/src/agents/mod.rs` | Agent types and orchestration root |
| `server/src/agents/pool/` | Coder/QA/mergemaster pool, auto-assign, lifecycle, retry |
| `server/src/agents/pool/auto_assign/` | Auto-assigner: scans pipeline, spawns agents on free slots |
| `server/src/agents/pool/pipeline/` | Stage transitions, completion, merge orchestration |
| `server/src/agents/runtime/` | Per-provider runtimes: `claude_code.rs`, `gemini.rs`, `openai.rs` |
| `server/src/agents/merge/` | Squash-merge mechanics, conflict detection |
| `server/src/agents/pty.rs` | PTY pseudo-terminal spawning + output streaming |
| `server/src/agents/lifecycle.rs` | Stage transitions and item movement |
| `server/src/agents/gates.rs` | Quality-gate runner |
| `server/src/agents/session_store.rs` | Per-agent session history |
| `server/src/agents/token_usage.rs` | Per-agent token cost ledger |
### CRDT + persistence | File | Purpose |
| Path | Purpose |
|------|---------| |------|---------|
| `server/src/crdt_state/` | CRDT primitives — `lww_maps.rs`, `state.rs`, `read.rs`, `write.rs`, `ops.rs`, `types.rs`, `presence.rs`, `gateway_config.rs` | | `server/src/agent_log.rs` | Agent log persistence — reads and writes JSONL agent event logs to disk. |
| `server/src/crdt_sync/` | WebSocket replication; `rpc.rs` holds the **read-RPC registry** | | `server/src/agent_mode.rs` | Headless build-agent mode for distributed, rendezvous-based story processing. |
| `server/src/crdt_sync/server/` | Sync-server endpoint, keepalive | | `server/src/cli.rs` | Command-line argument parsing for the huskies binary. |
| `server/src/crdt_snapshot/` | Snapshot persistence | | `server/src/crdt_wire.rs` | CRDT wire codec — serialization format for `SignedOp` sync messages between nodes. |
| `server/src/pipeline_state/` | Typed pipeline state machine + projections | | `server/src/gateway.rs` | Multi-project gateway — entrypoint wiring and route tree. When `huskies --gateway` is used, the server starts in gateway mode. B… |
| `server/src/db/mod.rs` | `content_store`, shadow writes, op persistence | | `server/src/gateway_relay.rs` | Gateway relay task — pushes project status events to the gateway via WebSocket. When `gateway_url` is configured in `project.tom… |
| `server/src/log_buffer.rs` | Bounded in-memory ring buffer for server log output. Use the [`slog!`] macro (INFO), [`slog_warn!`] (WARN), or [`slog_error!`] (… |
| `server/src/main.rs` | Huskies server — entry point, CLI argument parsing, and server startup. |
| `server/src/mesh.rs` | Peer mesh discovery — supplementary CRDT sync connections between build agents. When mesh discovery is enabled, a build agent pe… |
| `server/src/node_identity.rs` | Node identity — Ed25519 keypair foundation for distributed huskies. Each huskies node has a stable identity derived from an Ed25… |
| `server/src/rebuild.rs` | Server rebuild and restart logic shared between the MCP tool and Matrix bot command. |
| `server/src/services.rs` | Shared services bundle — common state threaded through HTTP handlers and chat transports. `Services` bundles the fields that eve… |
| `server/src/state.rs` | Session state — global mutable state shared across the server (project root, cancellation). |
| `server/src/store.rs` | Key-value store — JSON-backed persistent storage for user settings and preferences. |
| `server/src/workflow.rs` | Workflow module: test result tracking and acceptance evaluation. |
### HTTP / WS routes ### Backend modules (`server/src/`)
| Path | Purpose |
|------|---------|
| `server/src/http/mod.rs` | Top-level route registration |
| `server/src/http/ws.rs` | Top-level WebSocket dispatcher |
| `server/src/http/events.rs` | Event push endpoint |
| `server/src/http/agents/` | Agent REST + tests |
| `server/src/http/gateway/` | Gateway routes — `rest.rs`, `websocket.rs`, `mcp.rs`, `jsonrpc.rs` |
| `server/src/http/mcp/` | MCP tool handlers (agent_tools, story_tools, merge_tools, qa_tools, status_tools, git_tools, wizard_tools, dispatch.rs) |
| `server/src/http/workflow/` | Story-creation workflow endpoints (`bug_ops.rs`, `test_results.rs`) |
| `server/src/http/anthropic.rs` | Anthropic API proxy |
| `server/src/http/oauth.rs` | OAuth flows |
| `server/src/http/bot_command.rs` | Bot command dispatch |
| `server/src/http/bot_config.rs` | Bot config save/get |
| `server/src/http/wizard.rs` | Setup wizard endpoint |
### Chat (bot)
| Path | Purpose | | Path | Purpose |
|------|---------| |------|---------|
| `server/src/chat/mod.rs` | Chat module root | | `server/src/` | |
| `server/src/chat/commands/` | Slash commands — `status.rs`, `backlog.rs`, `run_tests.rs`, `depends.rs`, `freeze.rs`, `unblock.rs`, `move_story.rs`, `assign.rs`, `loc.rs`, `cost.rs`, `help.rs`, etc. | | `server/src/agents/` | Agent subsystem — types, configuration, and orchestration for coding agents. |
| `server/src/chat/commands/mod.rs` | Command dispatch | | `server/src/agents/merge/` | Merge operations — rebases agent work onto master and runs post-merge validation. |
| `server/src/chat/transport/matrix/` | Matrix bot | | `server/src/agents/merge/squash/` | Squash-merge orchestration: rebase agent work onto master and run post-merge gates. |
| `server/src/chat/transport/slack/` | Slack bot | | `server/src/agents/pool/` | Agent pool — manages the set of active agents across all pipeline stages. |
| `server/src/chat/transport/whatsapp/` | WhatsApp Business API | | `server/src/agents/pool/auto_assign/` | Auto-assign submodules: wires focused sub-files and re-exports public items. |
| `server/src/chat/transport/discord/` | Discord bot | | `server/src/agents/pool/auto_assign/watchdog/` | Watchdog task: detects orphaned agents, enforces turn/budget limits, and triggers auto-assign. |
| `server/src/chat/test_helpers.rs` | `write_item_with_content` and other CRDT-seeding test helpers | | `server/src/agents/pool/auto_assign/watchdog/tests/` | Shared test helpers for the watchdog module. |
| `server/src/agents/pool/pipeline/` | Pipeline operations — stage advancement, completion handling, and merge orchestration. |
### Domain services (one folder per concern) | `server/src/agents/pool/pipeline/advance/` | Pipeline advance — moves stories forward through pipeline stages after agent completion. |
| Path | Purpose | | `server/src/agents/pool/pipeline/completion/` | Agent completion handling — processes exit results and triggers pipeline advancement. |
|------|---------| | `server/src/agents/pool/start/` | Agent start — spawns a new agent process in a worktree for a given story. |
| `server/src/service/agents/` | Agent listing + selection | | `server/src/agents/runtime/` | Agent runtimes — pluggable backends (Claude Code, Gemini, OpenAI) for running agents. |
| `server/src/service/events/` | Event store + buffer | | `server/src/chat/` | Transport abstraction for chat platforms. The [`ChatTransport`] trait defines a platform-agnostic interface for sending and edit… |
| `server/src/service/gateway/` | Gateway business logic | | `server/src/chat/commands/` | Bot-level command registry shared by all chat transports. Commands registered here are handled directly by the bot without invok… |
| `server/src/service/git_ops/` | git status/diff/add/commit primitives | | `server/src/chat/transport/` | Chat transports — pluggable backends (Matrix, Slack, WhatsApp, Discord) for bot messaging. |
| `server/src/service/merge/` | Merge orchestration | | `server/src/chat/transport/discord/` | Discord Bot integration. Provides: - [`DiscordTransport`] — a [`ChatTransport`] that sends messages via the Discord REST API (`/… |
| `server/src/service/notifications/` | Notification dispatch | | `server/src/chat/transport/matrix/` | Matrix bot integration for Story Kit. When a `.huskies/bot.toml` file is present with `enabled = true`, the server spawns a Matr… |
| `server/src/service/qa/` | QA lifecycle | | `server/src/chat/transport/matrix/bot/` | Matrix bot — sub-modules for the Matrix chat bot implementation. |
| `server/src/service/story/` | Story CRUD + front matter | | `server/src/chat/transport/matrix/bot/messages/` | Matrix message handler — processes incoming room messages and dispatches commands. |
| `server/src/service/timer/` | Timer schedule | | `server/src/chat/transport/matrix/config/` | Matrix transport configuration — deserialization of `bot.toml` Matrix settings. |
| `server/src/service/wizard/` | Setup wizard state machine | | `server/src/chat/transport/slack/` | Slack Bot API integration. Provides: - [`SlackTransport`] — a [`ChatTransport`] that sends messages via the Slack Web API (`api.… |
| `server/src/service/ws/` | WebSocket message dispatch + inbound RPC routing | | `server/src/chat/transport/slack/commands/` | Slack incoming message dispatch and slash command handling. |
| `server/src/service/oauth/` | OAuth flow + PKCE | | `server/src/chat/transport/whatsapp/` | WhatsApp Business API integration. Provides: - [`WhatsAppTransport`] — a [`ChatTransport`] that sends messages via the Meta Grap… |
| `server/src/service/file_io/` | Filesystem read/write helpers | | `server/src/chat/transport/whatsapp/commands/` | WhatsApp command handling — processes incoming WhatsApp messages as bot commands. |
| `server/src/service/shell/` | Shell command execution + path-guard | | `server/src/config/` | Project configuration — parses `project.toml` for agents, components, and server settings. |
| `server/src/service/anthropic/` | Anthropic API client | | `server/src/crdt_snapshot/` | CRDT snapshot compaction with cross-node coordination. This module implements full CRDT state snapshots for compacting the op jo… |
| `server/src/service/bot_command/` | Bot command core logic | | `server/src/crdt_state/` | CRDT state layer — manages pipeline state as a conflict-free replicated document backed by SQLite. The CRDT document is the prim… |
| `server/src/service/diagnostics/` | Server diagnostics | | `server/src/crdt_sync/` | CRDT sync — WebSocket-based replication of pipeline state between huskies nodes. WebSocket-based CRDT sync layer for replicating… |
| `server/src/service/pipeline/` | Pipeline-level service helpers | | `server/src/crdt_sync/server/` | Server-side `/crdt-sync` WebSocket handler. |
| `server/src/service/project/` | Project loading and selection | | `server/src/db/` | SQLite storage layer — content store, shadow writes, and CRDT op persistence. |
| `server/src/service/settings/` | Settings persistence + validation | | `server/src/http/` | HTTP server — module declarations for all REST, MCP, WebSocket, and SSE endpoints. |
| `server/src/service/status/` | Status text formatting | | `server/src/http/agents/` | HTTP agent endpoints — thin adapters over `service::agents`. Each handler: extracts payload → calls `service::agents::X` → shape… |
| `server/src/service/common/` | Cross-cutting service helpers | | `server/src/http/gateway/` | Gateway HTTP handlers — thin transport shells for the gateway service. Each handler calls `service::gateway::*` for business log… |
| `server/src/http/mcp/` | HTTP MCP server module. |
### LLM | `server/src/http/mcp/agent_tools/` | MCP agent tools — start, stop, wait, list, and inspect agents via MCP. |
| Path | Purpose | | `server/src/http/mcp/diagnostics/` | MCP diagnostic tools — server logs, CRDT dump, version, line counting, story movement. |
|------|---------| | `server/src/http/mcp/shell_tools/` | MCP shell tools — run commands, execute tests, and stream output via MCP. This file is a thin adapter: it deserialises MCP paylo… |
| `server/src/llm/providers/` | `anthropic.rs`, `ollama.rs` | | `server/src/http/mcp/story_tools/` | MCP story tools — create, update, move, and manage stories, bugs, refactors, and spikes via MCP. This module is a thin adapter:… |
| `server/src/llm/chat/` | LLM chat session (`run.rs`, `tools.rs`) | | `server/src/http/mcp/story_tools/story/` | Story creation, listing, update, and lifecycle MCP tools. |
| `server/src/llm/oauth.rs` | LLM OAuth flow | | `server/src/http/mcp/tools_list/` | `tools/list` MCP method — returns the static schema for every tool the server exposes. |
| `server/src/llm/prompts.rs` | Prompt templates | | `server/src/http/workflow/` | Workflow helpers — shared story/bug file operations used by HTTP and MCP handlers. |
| `server/src/http/workflow/story_ops/` | Story operations — creates, updates, and manages acceptance criteria in story files. |
### IO, watcher, worktrees | `server/src/io/` | I/O subsystem — filesystem, shell, search, onboarding, and story metadata operations. |
| Path | Purpose | | `server/src/io/fs/` | Filesystem I/O — module declarations and re-exports for file operations. |
|------|---------| | `server/src/io/fs/scaffold/` | Project scaffolding — creates the `.huskies/` directory structure and default files. |
| `server/src/io/fs/` | Project file paths + scaffold | | `server/src/io/fs/scaffold/detect/` | Stack detection — inspect the project root for marker files and emit TOML `[[component]]` entries plus `script/build\|lint\|test`… |
| `server/src/io/watcher/` | Filesystem watcher for `.huskies/work/` and `project.toml` | | `server/src/io/watcher/` | Filesystem watcher for `.huskies/project.toml` and `.huskies/agents.toml`. Watches config files for changes and broadcasts a [`W… |
| `server/src/io/story_metadata.rs` | Story front-matter parsing/writing — `parse_front_matter`, `set_front_matter_field`, `write_*_in_content` setters | | `server/src/llm/` | LLM subsystem — chat orchestration, prompts, OAuth, and provider integrations. |
| `server/src/io/onboarding.rs` | First-run onboarding | | `server/src/llm/chat/` | LLM chat — orchestrates multi-turn conversations with tool-calling LLM providers. |
| `server/src/io/wizard.rs` | Wizard IO | | `server/src/llm/providers/` | LLM providers — module declarations for Anthropic, Claude Code, and Ollama backends. |
| `server/src/io/search.rs` | Repo search | | `server/src/llm/providers/claude_code/` | Claude Code provider — runs Claude Code CLI in a PTY and parses structured output. |
| `server/src/io/test_helpers.rs` | Generic IO test helpers | | `server/src/pipeline_state/` | Typed pipeline state machine (story 520). Replaces the stringly-typed CRDT views with strict Rust enums so that impossible state… |
| `server/src/worktree/` | Git worktree create/remove + git ops | | `server/src/service/` | Service layer — domain logic extracted from HTTP handlers. Each sub-module follows the conventions documented in `docs/architect… |
| `server/src/service/agents/` | Agent service — public API for the agent domain. This module orchestrates calls to `io.rs` (side effects) and the pure topic mod… |
### Utilities | `server/src/service/anthropic/` | Anthropic service — public API for Anthropic API-key management and model listing. Exposes functions to check, store, and use th… |
| Path | Purpose | | `server/src/service/bot_command/` | Bot command service — domain logic for dispatching slash commands. Extracted from `http/bot_command.rs` so that argument parsing… |
|------|---------| | `server/src/service/common/` | Shared pure helpers used by multiple service modules. All sub-modules here are pure (no I/O, no side effects). Any helper that d… |
| `server/src/rebuild.rs` | Server rebuild + restart | | `server/src/service/diagnostics/` | Diagnostics service — server logs, CRDT dump, permission management, and story movement. Extracted from `http/mcp/diagnostics.rs… |
| `server/src/agent_log.rs` | JSONL agent event logs | | `server/src/service/events/` | Events service — public API for the events domain. This module re-exports the pure buffer types from `buffer.rs` and the side-ef… |
| `server/src/log_buffer.rs` | In-memory log buffer | | `server/src/service/file_io/` | File I/O service — public API for filesystem and shell operations. Exposes functions for reading, writing, and listing files sco… |
| `server/src/mesh.rs` | Mesh networking | | `server/src/service/gateway/` | Gateway service — domain logic for the multi-project gateway. Follows the conventions in `docs/architecture/service-modules.md`:… |
| `server/src/node_identity.rs` | Node identity | | `server/src/service/git_ops/` | Git operations service — worktree path validation and git command execution. Extracted from `http/mcp/git_tools.rs` following th… |
| `server/src/gateway_relay.rs` | Gateway relay | | `server/src/service/merge/` | Merge service — domain logic for merging agent work to master. Extracted from `http/mcp/merge_tools.rs` following the convention… |
| `server/src/service/notifications/` | Notifications service — pipeline-event fan-out to chat transports. Subscribes to [`WatcherEvent`] broadcasts and posts human-rea… |
### Frontend | `server/src/service/notifications/io/` | I/O side of the notifications service. This is the **only** file inside `service/notifications/` that may perform side effects:… |
| Path | Purpose | | `server/src/service/oauth/` | OAuth service — domain logic for the Anthropic OAuth 2.0 PKCE flow. Extracts business logic from `http/oauth.rs` following the c… |
|------|---------| | `server/src/service/pipeline/` | Pipeline service — shared pipeline-domain logic. Contains pure functions for parsing and aggregating pipeline status data. Used… |
| `frontend/src/api/rpc.ts` | **Shared read-RPC client** over `/ws` — `rpcCall<T>(method, params)` | | `server/src/service/project/` | Project service — public API for the project domain. Exposes functions to open, close, query, and manage known projects. HTTP ha… |
| `frontend/src/api/agents.ts` | Agent listing + streaming (uses `rpcCall`) | | `server/src/service/qa/` | QA service — domain logic for requesting, approving, and rejecting QA reviews. Extracted from `http/mcp/qa_tools.rs` following t… |
| `frontend/src/api/gateway.ts` | Multi-project gateway client | | `server/src/service/settings/` | Settings service — domain logic for project settings and editor configuration. Extracts business logic from `http/settings.rs` f… |
| `frontend/src/api/client.ts` | HTTP client base | | `server/src/service/shell/` | Shell service — command safety, path sandboxing, and output helpers. Extracted from `http/mcp/shell_tools.rs` following the conv… |
| `frontend/src/components/` | React UI components (Chat, AgentPanel, WorkItemDetailPanel, etc.) | | `server/src/service/status/` | Status broadcaster — unified pipeline-event fan-out for all consumers. [`StatusBroadcaster`] lives on the [`crate::services::Ser… |
| `frontend/src/components/selection/` | Selection-related components | | `server/src/service/story/` | Story service — domain logic for creating, updating, and managing pipeline work items. Extracted from `http/mcp/story_tools.rs`… |
| `frontend/src/hooks/` | React hooks (`useChatWebSocket`, etc.) | | `server/src/service/timer/` | Timer service — deferred agent start via one-shot timers. Provides [`TimerStore`] for persisting timers to `.huskies/timers.json… |
| `frontend/src/utils/` | Utility helpers | | `server/src/service/wizard/` | Wizard service — domain logic for the multi-step project setup wizard. Follows the conventions from `docs/architecture/service-m… |
| `server/src/service/ws/` | WebSocket service — domain logic for real-time pipeline updates, chat, and permission prompts. This module extracts the business… |
| `server/src/worktree/` | Git worktree management — creates, lists, and removes worktrees for agent isolation. |
### Crates ### Crates
| Path | Purpose | | Path | Purpose |
|------|---------| |------|---------|
| `crates/bft-json-crdt/src/` | Core CRDT library — JSON CRDT, lists, maps, registers | | `crates/bft-json-crdt/benches/` | |
| `crates/bft-json-crdt/bft-crdt-derive/src/` | Derive macros | | `crates/bft-json-crdt/bft-crdt-derive/src/` | |
| `crates/bft-json-crdt/src/` | |
| `crates/bft-json-crdt/tests/` | |
### Canonical examples (when adding new things, copy these patterns) ### Frontend (`frontend/src/`)
- **New CRDT collection (LWW-map):** see `server/src/crdt_state/lww_maps.rs`
- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs` (e.g. `handle_active_agents_list`); call from frontend with `rpcCall("method.name")` | Path | Purpose |
- **Migrate HTTP route → CRDT op:** delete the route from `gateway.rs` / `http/*`, add operation to `service/<area>/`, write through `crdt_state/` |------|---------|
- **New front-matter field:** add to `StoryMetadata` and `FrontMatter` in `io/story_metadata.rs`, plus a `write_<name>_in_content` helper | `frontend/src/` | |
- **New service module:** copy structure of `server/src/service/agents/` (`mod.rs` + `io.rs` + `selection.rs`) | `frontend/src/api/` | |
- **New chat command:** add file under `server/src/chat/commands/` and register in `chat/commands/mod.rs::dispatch_command` | `frontend/src/components/` | |
| `frontend/src/components/selection/` | |
| `frontend/src/hooks/` | |
| `frontend/src/utils/` | |
### Canonical patterns (copy these when adding new things)
- **New CRDT LWW-map collection:** see `server/src/crdt_state/lww_maps.rs`
- **New read-RPC handler:** register in `server/src/crdt_sync/rpc.rs`; call from frontend via `rpcCall<T>("method.name")` from `frontend/src/api/rpc.ts`
- **Migrate HTTP route → CRDT:** delete from `gateway.rs` / `http/*`, add op to `service/<area>/`, write through `crdt_state/`
- **New front-matter field:** add to `StoryMetadata` and `FrontMatter` in `io/story_metadata.rs` plus a `write_<name>_in_content` helper
- **New service module:** copy `service/agents/` structure (`mod.rs` + `io.rs` + `selection.rs`)
- **New chat command:** add a file under `chat/commands/` and register in `chat/commands/mod.rs::dispatch_command`
- **New auto-assigner predicate:** add to `agents/pool/auto_assign/story_checks.rs`, wire in `auto_assign/auto_assign.rs` - **New auto-assigner predicate:** add to `agents/pool/auto_assign/story_checks.rs`, wire in `auto_assign/auto_assign.rs`
- **Test setup with CRDT seeding:** use `crate::db::write_item_with_content(story_id, stage, content)` — never `fs::write` to `.huskies/work/{stage}/` - **CRDT-seeding test helper:** `crate::db::write_item_with_content(story_id, stage, content)` — do not `fs::write` to `.huskies/work/{stage}/`
## Quality Gates ## Quality Gates
All enforced by `script/test`: All enforced by `script/test`: