34578d39c6
Move src/ → apps/server/ and packages/web/ → apps/web/ to adopt standard monorepo conventions (apps/ for runnable apps, packages/ for reusable libraries). Update all config files, shared package imports, test fixtures, and documentation to reflect new paths. Key fixes: - Update workspace config to ["apps/*", "packages/*"] - Update tsconfig.json rootDir/include for apps/server/ - Add apps/web/** to vitest exclude list - Update drizzle.config.ts schema path - Fix ensure-schema.ts migration path detection (3 levels up in dev, 2 levels up in dist) - Fix tests/integration/cli-server.test.ts import paths - Update packages/shared imports to apps/server/ paths - Update all docs/ files with new paths
159 lines
5.6 KiB
Markdown
159 lines
5.6 KiB
Markdown
# CLI & Configuration
|
|
|
|
`apps/server/cli/` — CLI commands, `apps/server/config/` — workspace configuration, `apps/server/bin/` — entry point.
|
|
|
|
## Entry Point
|
|
|
|
`apps/server/bin/cw.ts` — hashbang entry that imports and runs the CLI.
|
|
|
|
## CLI Framework
|
|
|
|
Uses **Commander.js** for command parsing.
|
|
|
|
## Global Flags
|
|
|
|
- `-s, --server` — Start coordination server in foreground
|
|
- `-p, --port <number>` — Server port (default: 3847, env: `CW_PORT`)
|
|
- `-d, --debug` — Enable debug mode (archive agent workdirs before cleanup)
|
|
|
|
## Commands
|
|
|
|
### System
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `cw init` | Create `.cwrc` workspace file in current directory |
|
|
| `cw start` | Start coordination server (see Server Wiring below) |
|
|
| `cw stop` | Stop running server (reads PID file, sends signal) |
|
|
| `cw status` | Query server health endpoint |
|
|
| `cw id [-n count]` | Generate nanoid(s) offline |
|
|
|
|
### Agent Management (`cw agent`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `spawn <prompt> --task <id> [--name] [--provider] [--initiative] [--cwd]` | Spawn agent |
|
|
| `stop <name>` | Stop running agent |
|
|
| `delete <name>` | Delete agent, clean workdir/branches/logs |
|
|
| `list` | List all agents with status |
|
|
| `get <name>` | Agent details (ID, task, session, worktree, status) |
|
|
| `resume <name> <answers>` | Resume with JSON answers or single string |
|
|
| `result <name>` | Get execution result |
|
|
|
|
### Task Management (`cw task`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `list --parent\|--phase\|--initiative <id>` | List tasks with counts |
|
|
| `get <taskId>` | Task details |
|
|
| `status <taskId> <status>` | Update status |
|
|
|
|
### Dispatch (`cw dispatch`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `queue <taskId>` | Queue task for dispatch |
|
|
| `next` | Dispatch next available task |
|
|
| `status` | Show queue status |
|
|
| `complete <taskId>` | Mark task complete |
|
|
|
|
### Initiative Management (`cw initiative`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `create <name> [--project <ids...>]` | Create initiative |
|
|
| `list [-s status]` | List initiatives |
|
|
| `get <id>` | Initiative details |
|
|
| `phases <initiativeId>` | List phases |
|
|
|
|
### Architect (`cw architect`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `discuss <initiativeId> [-c context]` | Start discussion agent |
|
|
| `plan <initiativeId> [-s summary]` | Start plan agent |
|
|
| `detail <phaseId> [-t taskName] [-c context]` | Detail phase into tasks |
|
|
|
|
### Phase (`cw phase`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `add-dependency --phase <id> --depends-on <id>` | Add dependency edge |
|
|
| `dependencies <phaseId>` | List dependencies |
|
|
| `queue <phaseId>` | Queue approved phase |
|
|
| `dispatch` | Dispatch next phase |
|
|
| `queue-status` | Show phase queue |
|
|
|
|
### Merge & Coordination (`cw merge`, `cw coordinate`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `merge queue <taskId>` | Queue task for merge |
|
|
| `merge status` | Show merge queue |
|
|
| `merge next` | Show next mergeable task |
|
|
| `coordinate [-t branch]` | Process all ready merges (default: main) |
|
|
|
|
### Messages (`cw message`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `list [--agent <id>] [--status <s>]` | List messages |
|
|
| `read <messageId>` | Read full message |
|
|
| `respond <messageId> <response>` | Respond to message |
|
|
|
|
### Projects (`cw project`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `register --name <n> --url <u>` | Register git repo |
|
|
| `list` | List projects |
|
|
| `delete <id>` | Delete project |
|
|
|
|
### Preview Deployments (`cw preview`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `start --initiative <id> --project <id> --branch <branch> [--phase <id>]` | Start Docker preview |
|
|
| `stop <previewId>` | Stop and clean up preview |
|
|
| `list [--initiative <id>]` | List active previews |
|
|
| `status <previewId>` | Get preview status with service details |
|
|
|
|
### Inter-Agent Conversation (`cw listen`, `cw ask`, `cw answer`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `listen --agent-id <id> [--poll-interval <ms>] [--timeout <ms>]` | Poll for pending questions, print JSON, exit |
|
|
| `ask <question> --from <agentId> [--agent-id\|--phase-id\|--task-id <target>] [--poll-interval <ms>] [--timeout <ms>]` | Ask question, block until answered, print answer |
|
|
| `answer <answer> --conversation-id <id>` | Answer a pending conversation |
|
|
|
|
All three commands output JSON for programmatic agent consumption.
|
|
|
|
### Accounts (`cw account`)
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `add [--provider] [--email] [--token]` | Auto-discover, manually register, or register with setup token |
|
|
| `list` | Show accounts with exhaustion status |
|
|
| `remove <id>` | Remove account |
|
|
| `refresh` | Clear expired exhaustion markers |
|
|
|
|
## Server Wiring
|
|
|
|
The CLI is the composition root. It creates concrete implementations and passes them as `contextDeps`:
|
|
|
|
```
|
|
ServerContextDeps = Omit<TrpcAdapterOptions, 'eventBus' | 'serverStartedAt' | 'processCount'>
|
|
```
|
|
|
|
This includes all repositories, managers, and the credential manager. The server adds `eventBus`, `serverStartedAt`, and `processCount` at startup.
|
|
|
|
## Workspace Configuration
|
|
|
|
`apps/server/config/` module:
|
|
|
|
### .cwrc File
|
|
JSON file at workspace root that marks a `cw` workspace:
|
|
```json
|
|
{ "version": 1 }
|
|
```
|
|
|
|
### findWorkspaceRoot()
|
|
Walks up directory tree looking for `.cwrc` file. Returns the directory containing it, or throws if not found.
|
|
|
|
### Schema
|
|
Currently `{ version: 1 }` — extend with new top-level keys as needed.
|
|
|
|
### Files
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `types.ts` | CwrcConfig type definition |
|
|
| `cwrc.ts` | findWorkspaceRoot(), readCwrc(), writeCwrc() |
|
|
| `index.ts` | Public API exports |
|