Add improved development environment with backend in Docker and front…#330
Add improved development environment with backend in Docker and front…#330zakstam wants to merge 13 commits intocoleam00:mainfrom
Conversation
…end locally - Created dev.bat script to run backend services in Docker and frontend locally - Added docker-compose.backend.yml for backend-only Docker setup - Updated package.json to run frontend on port 3737 - Fixed api.ts to use default port 8181 instead of throwing error - Script automatically stops production containers to avoid port conflicts - Provides instant HMR for frontend development
|
@coleam00 I would appreciate it if this is merged as soon as possible 🙏. There are no breaking changes. |
|
@zaksnet Thanks for this contribution! I really appreciate the work you put into setting up the development environment and its something that was on my list of things to do as well. To keep things consistent across the project, we're standardizing on Makefiles for environment setup. Would you be open to converting this to a Makefile, or would you prefer if I handle the conversion? I can provide a starting template if that would help if needed |
|
Sounds good @Wirasm, for as long as it solves the problem I'm in for it! Make files sound like a reasonable choice. I will work on an initial implementation. |
|
@zaksnet sounds good, when you have made the change from bat to make i will quickly test it and merge this in! |
… for cross-platform support and enhanced commands
WalkthroughIntroduces a root Makefile with development/testing targets, adopts Docker Compose profiles, updates frontend ports/env handling, adds an environment validation script, revises README to a Make-centered workflow, adjusts UI API URL resolution and Vite Docker detection/port config, updates frontend Dockerfile, tweaks UI error text, adds /logs to .gitignore, and makes MCP container resolution dynamic. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
actor Dev as Developer
participant MK as Makefile
participant DC as docker-compose
participant FE as Frontend (Vite)
participant BE as Backend Services
rect rgb(245,248,255)
note over Dev,MK: Hybrid Mode (make dev)
Dev->>MK: make check
MK->>MK: run node check-env.js
MK->>DC: compose --profile backend up -d
MK->>FE: npm run dev (port=ARCHON_UI_PORT||3737)
FE->>BE: Proxy API to archon-server:<VITE_ARCHON_SERVER_PORT||8181>
end
rect rgb(244,253,245)
note over Dev,MK: Full Docker Mode (make dev-docker)
Dev->>MK: make dev-docker
MK->>DC: compose --profile full up -d
DC->>FE: frontend on 3737
DC->>BE: backend services up
FE->>BE: API calls via service network
end
sequenceDiagram
autonumber
participant API as MCPServerManager
participant DOCK as Docker API
participant MCP as archon-mcp (container)
note over API: Initialization / Status Check
API->>API: _resolve_container()
API->>DOCK: find container "archon-mcp"
alt found
DOCK-->>API: container ref
API->>API: cache name/ref
else not found
DOCK-->>API: none
API-->>API: container=None, status=not_found
end
note over API,MCP: On status request
API->>API: _get_container_status()
alt ref missing or NotFound
API->>API: _resolve_container() retry
end
API-->>API: return stable status + container_status
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Poem
✨ Finishing Touches
🧪 Generate unit tests
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
|
I have tested this with windows and wsl (ubuntu) and everything works @Wirasm |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
README.md (1)
264-315: Document VITE_ variables required by the UI when ports/hostname change in hybrid mode.*Users who change
ARCHON_SERVER_PORT/HOSTin the root.envneed to mirror that to the UI (Vite) in hybrid dev. Without it, the UI will still default to8181.Append this note under “Configuring Custom Ports & Hostname”:
+> Note for Hybrid Development (frontend local, backend in Docker) +> +> If you change backend host/port in the root `.env`, also create/update `archon-ui-main/.env` so the UI can reach the backend: +> +> ```bash +> # archon-ui-main/.env +> VITE_API_URL= http://$HOST:$ARCHON_SERVER_PORT # strongest override +> # or, if you prefer constructing from window.location with a custom port: +> VITE_ARCHON_SERVER_PORT=$ARCHON_SERVER_PORT +> # optional host override (rarely needed; defaults to window.location.hostname) +> VITE_ARCHON_SERVER_HOST=$HOST +> ``` +> +> Alternatively, keep UI calls relative to `/api` and configure a Vite dev proxy to the backend.I can add a short “Troubleshooting: UI can’t reach API on custom port” section if you want.
🧹 Nitpick comments (12)
archon-ui-main/package.json (1)
7-7: Dev server change is fine; consider using the local vite binary and env-driven port/host.
- Using
--hostwithout a value binds to 0.0.0.0, which is likely intended for LAN testing. Good.- Minor: prefer the local
vitebinary overnpx viteto avoid version drift and the npx spawn overhead.- Optional: the README advertises configurable UI ports via
.env, but this hardcodes3737. Either pass the port from Make (recommended—see Makefile comment) or read it invite.config.ts.Apply either of these diffs:
Option A — use local vite:
- "dev": "npx vite --port 3737 --host", + "dev": "vite --port 3737 --host",Option B — keep script minimal and move configurability to vite.config.ts (recommended for cross‑platform):
- In
vite.config.ts(new or existing), load env and set server host/port:// vite.config.ts import { defineConfig, loadEnv } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig(({ mode }) => { const env = loadEnv(mode, process.cwd(), ''); const port = Number(env.ARCHON_UI_PORT || 3737); const host = env.HOST ? env.HOST : true; // true -> 0.0.0.0 return { plugins: [react()], server: { port, host }, }; });Then you can simplify the script to:
- "dev": "npx vite --port 3737 --host", + "dev": "vite",archon-ui-main/src/config/api.ts (1)
23-26: Allow host override via VITE_ARCHON_SERVER_HOST and update documentationTo ensure full configurability of the API URL (especially in hybrid or non-default setups), let’s add an optional host override in
getApiUrl()and clearly document all VITE-prefixed environment variables in the README.• archon-ui-main/src/config/api.ts
– Replace the hard-codedwindow.location.hostnamewith an override fromVITE_ARCHON_SERVER_HOST.
• README.md
– Under “Configuration” (or wherever you describe environment variables), add a note that if users deviate from the defaults (port 8181 or current host), they must define one of:
• VITE_API_URL
• VITE_ARCHON_SERVER_PORT
• VITE_ARCHON_SERVER_HOST
inarchon-ui-main/.env.Suggested code change in
src/config/api.ts:// Fallback: build URL from current host const protocol = window.location.protocol; - const host = window.location.hostname; + const host = import.meta.env.VITE_ARCHON_SERVER_HOST || window.location.hostname; // Try VITE_ prefixed env var first, then fallback to default const port = import.meta.env.VITE_ARCHON_SERVER_PORT || '8181'; return `${protocol}//${host}:${port}`;docker-compose.backend.yml (3)
31-34: Mounting the Docker socket in the server container is a large attack surface.Binding
/var/run/docker.sockgrants root-equivalent control over the host Docker daemon. If hot-reload is your only goal, it isn’t needed—uvicorn --reloadwith mounted source is sufficient.Apply this diff to drop the socket mount:
volumes: - - /var/run/docker.sock:/var/run/docker.sock - ./python/src:/app/src # Hot reload for Python - ./python/tests:/app/testsIf you still need it for a specific dev workflow, gate it behind an env flag:
volumes: - - /var/run/docker.sock:/var/run/docker.sock + - ${MOUNT_DOCKER_SOCK:-}:/var/run/docker.sock…and document
MOUNT_DOCKER_SOCK=/var/run/docker.sockonly for trusted machines.
35-40: Healthcheck is fine; consider more generous start_period for first build.Initial dependency download + migration may exceed 20s on cold builds. Bumping
start_periodto ~45–60s reduces false negatives.- start_period: 20s + start_period: 60s
107-109: Add trailing newline at EOF to appease linters.YAML linter flagged “no new line character at the end of file.”
README.md (2)
76-88: Keep “Agents” status consistent (Compose already includes it).Docs say “Agents (coming soon!)” but
docker-compose.backend.ymldefines and startsbackend-agents. Align the wording.- - **Agents (coming soon!)**: AI operations and streaming (Port: 8052) + - **Agents**: AI operations and streaming (Port: 8052)
96-108: Quick Command Reference rendering issues and minor grammar nits.The table renders correctly but the grammar lints stem from missing punctuation before/after the table in some Markdown renderers. Adding blank lines above/below tables typically resolves noisy linters.
Makefile (5)
4-4: Declare missing PHONY targets and add a conventional ‘all’ target.
restartand pattern targets likelogs-%should be PHONY.- Conventional
alltarget helps tooling.
This also addresses the checkmake warnings.-.PHONY: help dev dev-hybrid dev-docker prod build test clean clean-confirm deep-clean deep-clean-confirm stop logs status install check-env +.PHONY: \ + all help \ + dev dev-hybrid dev-docker prod build \ + test test-frontend test-backend test-coverage \ + clean clean-confirm deep-clean deep-clean-confirm \ + stop stop-prod logs logs-% status restart \ + install check-frontend-deps check-env \ + backend frontend \ + lint-frontend lint-backend typecheck format pre-commit \ + health watch-backend watch-mcp watch-agents \ + shell-backend shell-mcp migrate backup-db + +all: help
81-87: Use env-aware UI URL in messages.Reflect
.envoverrides in the output.- @echo "UI available at: http://localhost:3737" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "UI available at: http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737}"Apply similarly in the
prodtarget.
111-127: Backend tests rely on ‘uv’; add a soft check or fallback for new contributors.A quick guard improves DX on machines without
uv.test-backend: @echo "Running backend tests..." - @cd python && uv run pytest + @cd python && (command -v uv >/dev/null 2>&1 && uv run pytest || python -m pytest)
192-198: Status output: use env-aware UI URL.- @echo "Check http://localhost:3737 for frontend status" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "Check http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737} for frontend status"
224-230: Health endpoint hints: print env-aware URLs for copy-paste.- @echo "API Server: http://localhost:8181/health" - @echo "MCP Server: http://localhost:8051/health" - @echo "Agents Service: http://localhost:8052/health" - @echo "Frontend: http://localhost:3737" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "API Server: http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}/health"; \ + echo "MCP Server: http://$${HOST:-localhost}:$${ARCHON_MCP_PORT:-8051}/health"; \ + echo "Agents Service: http://$${HOST:-localhost}:$${ARCHON_AGENTS_PORT:-8052}/health"; \ + echo "Frontend: http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737}"
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (5)
Makefile(1 hunks)README.md(5 hunks)archon-ui-main/package.json(1 hunks)archon-ui-main/src/config/api.ts(1 hunks)docker-compose.backend.yml(1 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
{python/**/*.py,archon-ui-main/src/**/*.{ts,tsx,js,jsx}}
📄 CodeRabbit inference engine (CLAUDE.md)
{python/**/*.py,archon-ui-main/src/**/*.{ts,tsx,js,jsx}}: Remove dead code immediately; do not keep legacy/unused functions
Avoid comments that reference change history (e.g., LEGACY, CHANGED, REMOVED); keep comments focused on current functionality
Files:
archon-ui-main/src/config/api.ts
🧠 Learnings (1)
📚 Learning: 2025-08-21T11:22:33.541Z
Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T11:22:33.541Z
Learning: Applies to .env : Require SUPABASE_URL and SUPABASE_SERVICE_KEY in the .env file; optionally OPENAI_API_KEY, LOGFIRE_TOKEN, LOG_LEVEL
Applied to files:
README.md
🪛 YAMLlint (1.37.1)
docker-compose.backend.yml
[error] 109-109: no new line character at the end of file
(new-line-at-end-of-file)
🪛 markdownlint-cli2 (0.17.2)
README.md
46-46: Link fragments should be valid
(MD051, link-fragments)
🪛 LanguageTool
README.md
[grammar] ~83-~83: There might be a mistake here.
Context: ...starts all core microservices in Docker: - Server: Core API and business logic (P...
(QB_NEW_EN)
[grammar] ~96-~96: There might be a mistake here.
Context: ... website ### 🚀 Quick Command Reference | Command | Description | |---------|----...
(QB_NEW_EN)
[grammar] ~98-~98: There might be a mistake here.
Context: ...and Reference | Command | Description | |---------|-------------| | make dev |...
(QB_NEW_EN)
[grammar] ~99-~99: There might be a mistake here.
Context: ... Description | |---------|-------------| | make dev | Start hybrid dev environm...
(QB_NEW_EN)
[grammar] ~100-~100: There might be a mistake here.
Context: ...nt (backend in Docker, frontend local) | | make prod | Start production environ...
(QB_NEW_EN)
[grammar] ~101-~101: There might be a mistake here.
Context: ...production environment (all in Docker) | | make install | Install all dependenc...
(QB_NEW_EN)
[grammar] ~102-~102: There might be a mistake here.
Context: ...ke install| Install all dependencies | |make test| Run all tests | |make ...
(QB_NEW_EN)
[grammar] ~103-~103: There might be a mistake here.
Context: ...encies | | make test | Run all tests | | make stop | Stop all services | | `m...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...ts | | make stop | Stop all services | | make logs | View service logs | | `m...
(QB_NEW_EN)
[grammar] ~105-~105: There might be a mistake here.
Context: ...es | | make logs | View service logs | | make status | Check service status |...
(QB_NEW_EN)
[grammar] ~106-~106: There might be a mistake here.
Context: ...| make status | Check service status | | make help | Show all available comma...
(QB_NEW_EN)
[grammar] ~135-~135: There might be a mistake here.
Context: ...ing.
(QB_NEW_EN)
[grammar] ~338-~338: There might be a mistake here.
Context: ...nt Modes #### Hybrid Mode (Recommended) Best for active development with instant...
(QB_NEW_EN)
[grammar] ~349-~349: There might be a mistake here.
Context: ...t Docker rebuilds #### Full Docker Mode For testing production-like environment:...
(QB_NEW_EN)
[grammar] ~357-~357: There might be a mistake here.
Context: ...es rebuild) #### Manual Service Control Start individual services: ```bash make ...
(QB_NEW_EN)
🪛 checkmake (0.2.2)
Makefile
[warning] 200-200: Target "restart" should be declared PHONY.
(phonydeclared)
[warning] 7-7: Target body for "help" exceeds allowed length of 5 (27).
(maxbodylength)
[warning] 136-136: Target body for "clean" exceeds allowed length of 5 (14).
(maxbodylength)
[warning] 4-4: Missing required phony target "all"
(minphony)
🔇 Additional comments (3)
README.md (1)
318-334: Great developer UX section. Minor polish: cross-reference “make help” earlier.The Quick Commands list is clear and matches the Makefile. No action required—just noting the good alignment.
Makefile (2)
98-103: Nice: defensive downing of both compose projects before dev.This avoids stale networks/ports. No change requested.
200-201: Declare restart as PHONY (and it’s a handy alias).Change already covered by the PHONY expansion above. No further action.
…update test commands for frontend and backend
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
README.md (2)
42-47: Add Node.js and Python/uv to prerequisites.The workflow runs the frontend locally with npm and installs backend deps with uv. Please list these explicitly to prevent setup failures.
Apply this diff to extend Prerequisites:
### Prerequisites - [Docker Desktop](https://www.docker.com/products/docker-desktop/) - [Supabase](https://supabase.com/) account (free tier or local Supabase both work) - [OpenAI API key](https://platform.openai.com/api-keys) (Gemini and Ollama are supported too!) - [Make](https://www.gnu.org/software/make/) (see [Installing Make](#installing-make) below) +- [Node.js 18+ and npm](https://nodejs.org/) (frontend dev server, tests, lint) +- [Python 3.11+](https://www.python.org/) and [uv](https://github.com/astral-sh/uv) (backend tests/linting locally; optional in Hybrid Mode)
83-90: Doc-code mismatch in Hybrid Mode:.envports aren’t applied to the local frontendThe README states that “Ports are configurable in your .env as well,” but the
dev-hybridMakefile target (Makefile:55–58) only starts the backend via Docker and doesn’t export theARCHON_SERVER_HOSTorARCHON_SERVER_PORT(asVITE_ARCHON_SERVER_HOST/VITE_ARCHON_SERVER_PORT) into Vite. As a result, changing those variables in .env has no effect on the frontend during local development, contradicting the documentation (README.md:83–90).Locations to address:
- Makefile (lines 55–58): no
export VITE_ARCHON_SERVER_HOST/VITE_ARCHON_SERVER_PORTbefore running Vite- README.md (lines 83–90): claims ports are configurable in Hybrid Mode
Options for fixing:
- Wire through env vars: Modify
dev-hybridto export the VITE-prefixed variables, e.g.:dev-hybrid: stop-prod check-env check-frontend-deps @echo "Starting hybrid development environment..." @echo "Backend services in Docker, Frontend running locally"
@export VITE_ARCHON_SERVER_HOST=$${ARCHON_SERVER_HOST}@export VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT} @docker-compose -p archon-backend -f docker-compose.backend.yml up -d --build
- Amend the docs: Clarify in README.md that custom ports only apply when all services—including the UI—run in Docker (e.g. under
make dev-docker), and Hybrid Mode uses the default host/port.Please let me know which approach you’d like implemented, or if you’d prefer a combination of both.
♻️ Duplicate comments (2)
README.md (1)
366-378: Replace subdirectory commands with top-level Make targets.To keep UX consistent and avoid requiring users to cd into subfolders, prefer Make targets you already expose. The optional direct commands can stay as alternates.
# Frontend tests make test-frontend -cd archon-ui-main && npm run test:coverage +make test-coverage # (Frontend coverage) @@ # Backend tests make test-backend -# (Optional) run directly via uv -cd python && uv run pytest +# (Optional) run directly via uv) +# cd python && uv run pytestMakefile (1)
55-77: Hybrid dev: honor env-configured ports and pass them to Vite.Make the console output and frontend launch reflect .env overrides; export VITE_* so the UI hits the right API.
dev-hybrid: stop-prod check-env check-frontend-deps @echo "Starting hybrid development environment..." @echo "Backend services in Docker, Frontend running locally" @docker-compose -p archon-backend -f docker-compose.backend.yml up -d --build @echo "" @echo "=====================================================" @echo "Development Environment Ready!" @echo "=====================================================" @echo "" @echo "Backend Services in Docker:" - @echo " API Server: http://localhost:8181" - @echo " MCP Server: http://localhost:8051" - @echo " Agents Service: http://localhost:8052" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo " API Server: http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"; \ + echo " MCP Server: http://$${HOST:-localhost}:$${ARCHON_MCP_PORT:-8051}"; \ + echo " Agents Service: http://$${HOST:-localhost}:$${ARCHON_AGENTS_PORT:-8052}"; @echo "" @echo "Starting frontend server..." @echo "" @echo "Commands (in another terminal):" @echo " make logs - View all logs" @echo " make stop - Stop everything" @echo " make status - Check service status" @echo "" - @cd archon-ui-main && npm run dev + @set -a; [ -f .env ] && . ./.env; set +a; \ + cd archon-ui-main && \ + VITE_ARCHON_SERVER_HOST=$${HOST:-localhost} \ + VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT:-8181} \ + npm run dev
🧹 Nitpick comments (9)
README.md (3)
96-108: Tweak Quick Command table to include coverage and clarity.Since a top-level test-coverage target exists (frontend), add it here to keep guidance consistent.
| `make test` | Run all tests | +| `make test-coverage` | Frontend tests with coverage | | `make stop` | Stop all services |
311-315: Prefer Make targets for consistency.You already provide a restart target. Recommend referencing it here so users don’t mix raw docker-compose with Make.
-1. Restart Docker containers: `docker-compose down && docker-compose up -d` +1. Restart services: `make restart`
135-166: Install instructions: add Node and uv installation pointers.You have great Make install steps. Add brief pointers for Node and uv to match the new prerequisites and reduce friction on Windows/WSL.
### Windows ```bash # Option 1: Using Chocolatey choco install make +# Install Node.js +choco install nodejs-lts +# Install uv (optional for hybrid; useful for backend tests/lint) +powershell -Command "irm https://astral.sh/uv/install.ps1 | iex" # Option 2: Using Scoop scoop install make +scoop install nodejs-lts +# uv via PowerShell: +powershell -Command "irm https://astral.sh/uv/install.ps1 | iex" # Option 3: Using WSL2 wsl --install # Then in WSL: sudo apt-get install make +# And: sudo apt-get install -y nodejs npm python3 python3-pip +# uv: curl -LsSf https://astral.sh/uv/install.sh | sh</blockquote></details> <details> <summary>Makefile (6)</summary><blockquote> `4-4`: **Declare missing PHONY targets (and add “all” alias).** Several targets aren’t listed, and tools warn about minphony/all/restart. Adding these reduces surprising rebuilds when files named like targets exist. ```diff -.PHONY: help dev dev-hybrid dev-docker prod build test clean clean-confirm deep-clean deep-clean-confirm stop logs status install check-env +.PHONY: \ + all help \ + dev dev-hybrid dev-docker prod backend frontend \ + build install check-env stop stop-prod restart \ + test test-frontend test-backend test-coverage \ + logs logs-% status health watch-backend watch-mcp watch-agents \ + lint-frontend lint-backend typecheck format pre-commit \ + clean clean-confirm deep-clean deep-clean-confirm \ + shell-backend shell-mcp migrate backup-db + +all: help
79-91: Full Docker messaging: make it env-aware (UI port).If ARCHON_UI_PORT is changed, the printed URL is wrong.
dev-docker: @@ - @echo "UI available at: http://localhost:3737" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "UI available at: http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737}" @@ prod: @@ - @echo "UI available at: http://localhost:3737" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "UI available at: http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737}"
196-202: Status message: avoid hardcoded UI port.Keep the output consistent with .env overrides.
- @echo "Check http://localhost:3737 for frontend status" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "Check http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737} for frontend status"
228-234: Health URLs: use configured host/ports.This aligns the health target with the doc promise that ports are configurable.
health: @echo "Checking service health..." - @echo "API Server: http://localhost:8181/health" - @echo "MCP Server: http://localhost:8051/health" - @echo "Agents Service: http://localhost:8052/health" - @echo "Frontend: http://localhost:3737" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "API Server: http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}/health"; \ + echo "MCP Server: http://$${HOST:-localhost}:$${ARCHON_MCP_PORT:-8051}/health"; \ + echo "Agents Service: http://$${HOST:-localhost}:$${ARCHON_AGENTS_PORT:-8052}/health"; \ + echo "Frontend: http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737}"
187-194: Nice: logs/logs-% targets for backend.Targets are straightforward and scoped to the backend compose project. Consider documenting that UI logs aren’t included here when running full Docker mode.
114-126: Tests wiring looks good; consider adding backend coverage target.You have a frontend coverage target; if backend coverage is desired, add a companion for pytest-cov and reference it in README.
# Run backend tests test-backend: @echo "Running backend tests..." @cd python && uv run pytest + +# Run backend tests with coverage (requires pytest-cov in backend deps) +test-backend-coverage: + @echo "Running backend tests with coverage..." + @cd python && uv run pytest --cov=src --cov-report=term-missing
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (2)
Makefile(1 hunks)README.md(5 hunks)
🧰 Additional context used
🧠 Learnings (2)
📚 Learning: 2025-08-21T11:22:33.541Z
Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T11:22:33.541Z
Learning: Applies to .env : Require SUPABASE_URL and SUPABASE_SERVICE_KEY in the .env file; optionally OPENAI_API_KEY, LOGFIRE_TOKEN, LOG_LEVEL
Applied to files:
MakefileREADME.md
📚 Learning: 2025-08-21T11:22:33.541Z
Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T11:22:33.541Z
Learning: Applies to archon-ui-main/test/** : Place frontend tests under archon-ui-main/test/
Applied to files:
README.md
🪛 checkmake (0.2.2)
Makefile
[warning] 7-7: Target body for "help" exceeds allowed length of 5 (27).
(maxbodylength)
[warning] 140-140: Target body for "clean" exceeds allowed length of 5 (14).
(maxbodylength)
[warning] 4-4: Missing required phony target "all"
(minphony)
[warning] 204-204: Target "restart" should be declared PHONY.
(phonydeclared)
🪛 markdownlint-cli2 (0.17.2)
README.md
46-46: Link fragments should be valid
(MD051, link-fragments)
🪛 LanguageTool
README.md
[grammar] ~83-~83: There might be a mistake here.
Context: ...starts all core microservices in Docker: - Server: Core API and business logic (P...
(QB_NEW_EN)
[grammar] ~96-~96: There might be a mistake here.
Context: ... website ### 🚀 Quick Command Reference | Command | Description | |---------|----...
(QB_NEW_EN)
[grammar] ~98-~98: There might be a mistake here.
Context: ...and Reference | Command | Description | |---------|-------------| | make dev |...
(QB_NEW_EN)
[grammar] ~99-~99: There might be a mistake here.
Context: ... Description | |---------|-------------| | make dev | Start hybrid dev environm...
(QB_NEW_EN)
[grammar] ~100-~100: There might be a mistake here.
Context: ...nt (backend in Docker, frontend local) | | make prod | Start production environ...
(QB_NEW_EN)
[grammar] ~101-~101: There might be a mistake here.
Context: ...production environment (all in Docker) | | make install | Install all dependenc...
(QB_NEW_EN)
[grammar] ~102-~102: There might be a mistake here.
Context: ...ke install| Install all dependencies | |make test| Run all tests | |make ...
(QB_NEW_EN)
[grammar] ~103-~103: There might be a mistake here.
Context: ...encies | | make test | Run all tests | | make stop | Stop all services | | `m...
(QB_NEW_EN)
[grammar] ~104-~104: There might be a mistake here.
Context: ...ts | | make stop | Stop all services | | make logs | View service logs | | `m...
(QB_NEW_EN)
[grammar] ~105-~105: There might be a mistake here.
Context: ...es | | make logs | View service logs | | make status | Check service status |...
(QB_NEW_EN)
[grammar] ~106-~106: There might be a mistake here.
Context: ...| make status | Check service status | | make help | Show all available comma...
(QB_NEW_EN)
[grammar] ~135-~135: There might be a mistake here.
Context: ...ing.
(QB_NEW_EN)
[grammar] ~338-~338: There might be a mistake here.
Context: ...nt Modes #### Hybrid Mode (Recommended) Best for active development with instant...
(QB_NEW_EN)
[grammar] ~349-~349: There might be a mistake here.
Context: ...t Docker rebuilds #### Full Docker Mode For testing production-like environment:...
(QB_NEW_EN)
[grammar] ~357-~357: There might be a mistake here.
Context: ...es rebuild) #### Manual Service Control Start individual services: ```bash make ...
(QB_NEW_EN)
| # Verify required env vars exist - using Node.js for cross-platform compatibility | ||
| check-env: | ||
| @node -e "const fs=require('fs'); if(!fs.existsSync('.env')){console.error('ERROR: .env file not found! Create one from .env.example');process.exit(1);} const env=fs.readFileSync('.env','utf8'); const missing=[]; if(!env.includes('SUPABASE_URL=')){missing.push('SUPABASE_URL');} if(!env.includes('SUPABASE_SERVICE_KEY=')){missing.push('SUPABASE_SERVICE_KEY');} if(missing.length>0){console.error('ERROR: Missing required env vars: '+missing.join(', '));process.exit(1);} console.log('Environment OK: SUPABASE_URL and SUPABASE_SERVICE_KEY found.');" | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Make env check robust and fail early if Node is missing.
The current check-env passes when variables are present but empty or commented out. Also, it assumes Node is available. Tighten both.
check-env:
- @node -e "const fs=require('fs'); if(!fs.existsSync('.env')){console.error('ERROR: .env file not found! Create one from .env.example');process.exit(1);} const env=fs.readFileSync('.env','utf8'); const missing=[]; if(!env.includes('SUPABASE_URL=')){missing.push('SUPABASE_URL');} if(!env.includes('SUPABASE_SERVICE_KEY=')){missing.push('SUPABASE_SERVICE_KEY');} if(missing.length>0){console.error('ERROR: Missing required env vars: '+missing.join(', '));process.exit(1);} console.log('Environment OK: SUPABASE_URL and SUPABASE_SERVICE_KEY found.');"
+ @node -v >/dev/null 2>&1 || { echo "ERROR: Node.js is required for check-env. Please install Node 18+."; exit 1; }
+ @node -e "const fs=require('fs'); const path='.env'; \
+if(!fs.existsSync(path)){ console.error('ERROR: .env not found. Copy .env.example to .env'); process.exit(1);} \
+const lines=fs.readFileSync(path,'utf8').split(/\r?\n/).filter(l=>!l.trim().startsWith('#')); \
+const kv=Object.fromEntries(lines.map(l=>l.split('=').map(s=>s.trim())).filter(a=>a.length>=2)); \
+const need=['SUPABASE_URL','SUPABASE_SERVICE_KEY']; \
+const missing=need.filter(k=>!(k in kv) || !kv[k]); \
+if(missing.length){ console.error('ERROR: Missing required env vars: '+missing.join(', ')); process.exit(1);} \
+console.log('Environment OK: SUPABASE_URL and SUPABASE_SERVICE_KEY found.');"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| # Verify required env vars exist - using Node.js for cross-platform compatibility | |
| check-env: | |
| @node -e "const fs=require('fs'); if(!fs.existsSync('.env')){console.error('ERROR: .env file not found! Create one from .env.example');process.exit(1);} const env=fs.readFileSync('.env','utf8'); const missing=[]; if(!env.includes('SUPABASE_URL=')){missing.push('SUPABASE_URL');} if(!env.includes('SUPABASE_SERVICE_KEY=')){missing.push('SUPABASE_SERVICE_KEY');} if(missing.length>0){console.error('ERROR: Missing required env vars: '+missing.join(', '));process.exit(1);} console.log('Environment OK: SUPABASE_URL and SUPABASE_SERVICE_KEY found.');" | |
| # Verify required env vars exist - using Node.js for cross-platform compatibility | |
| check-env: | |
| @node -v >/dev/null 2>&1 || { echo "ERROR: Node.js is required for check-env. Please install Node 18+."; exit 1; } | |
| @node -e "const fs=require('fs'); const path='.env'; \ | |
| if(!fs.existsSync(path)){ console.error('ERROR: .env not found. Copy .env.example to .env'); process.exit(1);} \ | |
| const lines=fs.readFileSync(path,'utf8').split(/\r?\n/).filter(l=>!l.trim().startsWith('#')); \ | |
| const kv=Object.fromEntries(lines.map(l=>l.split('=').map(s=>s.trim())).filter(a=>a.length>=2)); \ | |
| const need=['SUPABASE_URL','SUPABASE_SERVICE_KEY']; \ | |
| const missing=need.filter(k=>!(k in kv) || !kv[k]); \ | |
| if(missing.length){ console.error('ERROR: Missing required env vars: '+missing.join(', ')); process.exit(1);} \ | |
| console.log('Environment OK: SUPABASE_URL and SUPABASE_SERVICE_KEY found.');" |
🤖 Prompt for AI Agents
In Makefile around lines 47 to 50, the make target check-env currently assumes
Node exists and only checks for substrings so it can miss empty or commented
variables; update the target to first verify Node is installed and fail
immediately if not, then read and parse .env robustly by ignoring comment lines
and whitespace, extracting key=value pairs, and ensuring SUPABASE_URL and
SUPABASE_SERVICE_KEY are present and have non-empty values (not just present as
commented or empty strings); on any failure emit a clear error and exit
non-zero.
This commit enhances the development workflow by replacing the separate docker-compose.backend.yml file with Docker Compose profiles, fixing critical service discovery issues, and adding comprehensive developer tooling through an improved Makefile system. Key improvements: - Replace docker-compose.backend.yml with cleaner profile approach - Fix service discovery by maintaining consistent container names - Fix port mappings (3737:3737 instead of 3737:5173) - Add make doctor for environment validation - Fix port configuration and frontend HMR - Improve error handling with .SHELLFLAGS in Makefile - Add comprehensive port configuration via environment variables - Simplify make dev-local to only run essential services - Add logging directory creation for local development - Document profile strategy in docker-compose.yml These changes provide three flexible development modes: - Hybrid mode (default): Backend in Docker, frontend local with HMR - Docker mode: Everything in Docker for production-like testing - Local mode: API server and UI run locally Co-authored-by: Zak Stam <zaksnet@users.noreply.github.com>
- Resolved Dockerfile conflict: kept our version with --host in package.json - Resolved README conflicts: kept hybrid development mode documentation
The stop command now explicitly specifies all profiles to ensure all containers are stopped regardless of how they were started.
- Changed 'make lint' to 'make lint-frontend' and 'make lint-backend' - Removed non-existent 'make logs-server' command - Added 'make watch-mcp' and 'make watch-agents' commands - All documented make commands now match what's available in Makefile
- Create robust environment validation script (check-env.js) that properly parses .env files - Fix Docker healthcheck port mismatch (5173 -> 3737) - Remove hard-coded port flags from package.json to allow environment configuration - Fix Docker detection logic using /.dockerenv instead of HOSTNAME - Normalize container names to lowercase (archon-server, archon-mcp, etc.) - Improve stop-local command with port-based fallback for process killing - Fix API configuration fallback chain to include VITE_PORT - Fix Makefile shell variable expansion using runtime evaluation - Update .PHONY targets with comprehensive list - Add --profile flags to Docker Compose commands in README - Add VITE_ARCHON_SERVER_PORT to docker-compose.yml - Add Node.js 18+ to prerequisites - Use dynamic ports in Makefile help messages - Add lint alias combining frontend and backend linting - Update .env.example documentation - Scope .gitignore logs entry to /logs/ Co-Authored-By: Claude <noreply@anthropic.com>
- Add dynamic container name resolution with three-tier strategy - Support environment variables for custom container names - Add service discovery labels to docker-compose services - Update BackendStartupError with correct container name references
- Update environment variable names to use VITE_ prefix that matches production code - Fix MCP client service tests to use singleton instance export - Update default behavior tests to expect fallback to port 8181 - All 77 frontend tests now pass
Replace aggressive kill -9 with targeted process termination: - Filter processes by command name (node/vite/python/uvicorn) before killing - Use graceful SIGTERM instead of SIGKILL - Add process verification to avoid killing Docker-related processes - Improve logging with descriptive step messages
- Reduced Makefile from 344 lines (43 targets) to 83 lines (8 essential targets) - Removed unnecessary environment variables (*_CONTAINER_NAME variables) - Fixed Windows compatibility by removing Unix-specific commands - Added security fixes to check-env.js (path validation) - Simplified MCP container discovery to use fixed container names - Fixed 'make stop' to properly handle Docker Compose profiles - Updated documentation to reflect simplified workflow - Restored original .env.example with comprehensive Supabase key documentation This addresses all critical issues from code review: - Cross-platform compatibility ✅ - Security vulnerabilities fixed ✅ - 81% reduction in complexity ✅ - Maintains all essential functionality ✅ All tests pass: Frontend (77/77), Backend (267/267)
- Split test command into test-fe and test-be for targeted testing - Split lint command into lint-fe and lint-be for targeted linting - Keep original test and lint commands that run both - Update help text with new commands for better developer experience
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (2)
Makefile (2)
24-28: Guard uv; offer pip fallback and clearer UX.install fails on systems without uv. Provide a soft check and fallback to pip as previously discussed.
Apply this diff:
install: @echo "Installing dependencies..." @cd archon-ui-main && npm install - @cd python && uv sync + @cd python && if command -v uv >/dev/null 2>&1; then \ + echo "Using uv to sync Python deps..."; \ + uv sync; \ + else \ + echo "WARN: 'uv' not found. Falling back to pip. (Install uv for faster, reproducible sync)"; \ + python3 -m pip install -U pip || true; \ + test -f requirements.txt && python3 -m pip install -r requirements.txt || echo "No requirements.txt found"; \ + fi @echo "✓ Dependencies installed"
39-46: Export backend port/host to Vite and print env-aware URLs in hybrid mode.Hybrid dev should pass VITE_ARCHON_SERVER_PORT (and optional host) to the UI so getApiUrl() resolves correctly when ports/host are customized via .env. Echo should reflect actual values, not hardcoded defaults.
Apply this diff:
dev: check @echo "Starting hybrid development..." @echo "Backend: Docker | Frontend: Local with hot reload" - @docker-compose --profile backend up -d --build - @echo "Backend running at http://localhost:8181" + @$(COMPOSE) --profile backend up -d --build + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "Backend running at http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}" @echo "Starting frontend..." - @cd archon-ui-main && npm run dev + @cd archon-ui-main && \ + VITE_ARCHON_SERVER_PORT=$${ARCHON_SERVER_PORT:-8181} \ + VITE_ARCHON_SERVER_HOST=$${HOST:-} \ + npm run dev
🧹 Nitpick comments (31)
archon-ui-main/src/components/BackendStartupError.tsx (2)
31-31: Broaden guidance: include CLI path and align naming with Make/compose backend fileUsers working outside Docker Desktop will benefit from CLI instructions. Also, since this PR standardizes container names (archon-*) and introduces a backend-only compose file, the guidance should reflect:
- the canonical container name archon-server
- the backend-only compose file when applicable
- the Make-based workflow (now preferred)
Apply this diff to extend the help text:
- Check the <span className="text-red-400 font-bold">Archon API server</span> container logs in Docker Desktop for detailed error information. + Check the <span className="text-red-400 font-bold">Archon API server</span> logs for detailed error information. + <span className="ml-1">You can use Docker Desktop or the CLI.</span>- <p>3. Look for the Archon server container (typically named <span className="text-red-400 font-semibold">archon-server</span> or similar)</p> + <p>3. Look for the Archon server container (typically named <span className="text-red-400 font-semibold">archon-server</span>)</p> + <p className="mt-2">CLI alternatives:</p> + <code className="block p-2 bg-black/70 rounded text-red-100 font-mono text-xs"> + docker compose logs -f archon-server + </code> + <code className="block mt-1 p-2 bg-black/70 rounded text-red-100 font-mono text-xs"> + docker compose -f docker-compose.backend.yml logs -f archon-server + </code>Also applies to: 36-36
49-56: Offer Make-based recovery path to match the new workflowThis PR moves dev orchestration to a Makefile. Mirror that here so newcomers follow the standardized path first, with compose as a fallback.
If your Makefile defines targets for recreating backend services, consider:
- <code className="block mt-2 p-2 bg-black/70 rounded text-red-100 font-mono text-sm"> - docker compose down && docker compose up -d - </code> + <div className="space-y-1"> + <code className="block mt-2 p-2 bg-black/70 rounded text-red-100 font-mono text-sm"> + make backend-recreate + </code> + <p className="text-red-300 text-xs">or, using Docker Compose directly:</p> + <code className="block p-2 bg-black/70 rounded text-red-100 font-mono text-sm"> + docker compose -f docker-compose.backend.yml down && docker compose -f docker-compose.backend.yml up -d + </code> + </div>Please confirm the exact Make target names; if different, I can tailor the snippet.
archon-ui-main/Dockerfile (1)
21-25: Update Dockerfile to Node 20 LTS, clarify port/host source, and run as non-root• Upgrade the base image from Node 18 (EOL) to Node 20 LTS for ongoing security patches and ecosystem support
• Clarify that the exposed port comes fromvite.config.ts(default 3737), notpackage.json
• Drop root privileges by switching to the built-innodeuser before starting the serverFile:
archon-ui-main/Dockerfile-FROM node:18-alpine +FROM node:20-alpine -# Expose the port configured in package.json (3737) -EXPOSE 3737 +# Expose the port used by Vite (configured in vite.config.ts, default 3737) +EXPOSE 3737 -# Start Vite dev server (already configured with --port 3737 --host in package.json) -CMD ["npm", "run", "dev"] +# Drop privileges for runtime +USER node +# Start Vite dev server (host/port are configured in vite.config.ts) +CMD ["npm", "run", "dev"]archon-ui-main/vite.config.ts (2)
18-18: Docker detection: add a resilient fallback or allow explicit overrideRelying only on DOCKER_ENV or /.dockerenv may miss certain runtimes (some container runtimes omit /.dockerenv). Consider allowing an explicit override or adding a lightweight cgroup check.
-import { existsSync, mkdirSync } from 'fs'; +import { existsSync, mkdirSync, readFileSync } from 'fs'; @@ - const isDocker = process.env.DOCKER_ENV === 'true' || existsSync('/.dockerenv'); + const isDocker = + process.env.DOCKER_ENV === 'true' || + existsSync('/.dockerenv') || + (() => { + try { + if (process.platform === 'win32') return false; + const c = readFileSync('/proc/1/cgroup', 'utf8'); + return /docker|containerd|kubepods/.test(c); + } catch { + return false; + } + })();Please validate in your Docker Compose dev container that DOCKER_ENV=true is set; that should make detection deterministic.
281-281: Port parsing: guard against NaN and octal quirksparseInt without a radix can behave oddly, and NaN should fall back cleanly.
- port: parseInt(process.env.ARCHON_UI_PORT || env.ARCHON_UI_PORT || '3737'), // Use configurable port + port: Number(process.env.ARCHON_UI_PORT ?? env.ARCHON_UI_PORT) || 3737, // Use configurable portcheck-env.js (5)
11-14: Harden path check: use path.relative to avoid false positives (Windows, symlinks)startsWith(projectRoot) can misbehave on case-insensitive filesystems and with symlinks. Use path.relative for a robust containment check.
-if (!envPath.startsWith(projectRoot)) { +const rel = path.relative(projectRoot, envPath); +if (rel.startsWith('..') || path.isAbsolute(rel)) { console.error('Security error: Invalid .env path'); process.exit(1); }
18-21: Cross-platform copy hintWindows users may not have cp. Offer an alternative or point to the Makefile target if present.
- console.error('Copy .env.example to .env and add your credentials:'); - console.error(' cp .env.example .env'); + console.error('Copy .env.example to .env and add your credentials:'); + console.error(process.platform === 'win32' + ? ' copy .env.example .env (PowerShell: Copy-Item .env.example .env)' + : ' cp .env.example .env'); + console.error('Or run: make init (if available)');
28-37: .env parsing: accept “export VAR=…” and trim inline commentsSome teams include export prefixes or end-of-line comments. Small parsing tweaks improve robustness.
-envContent.split('\n').forEach(line => { +envContent.split('\n').forEach(line => { const trimmed = line.trim(); if (!trimmed || trimmed.startsWith('#')) return; - - const [key, ...valueParts] = trimmed.split('='); + const sanitized = trimmed.replace(/^export\s+/, ''); + // Drop inline comments not within quotes + const withoutInline = sanitized.replace(/\s+#.*$/, ''); + const [key, ...valueParts] = withoutInline.split('='); if (key) { const value = valueParts.join('=').trim().replace(/^["']|["']$/g, ''); envVars[key.trim()] = value; } });
56-64: Tighten URL validation with scheme checkEnsure https scheme for SUPABASE_URL to avoid accidental http usage.
try { - new URL(envVars['SUPABASE_URL']); + const u = new URL(envVars['SUPABASE_URL']); + if (u.protocol !== 'https:') { + throw new Error('SUPABASE_URL must use https'); + } } catch (e) { console.error('ERROR: SUPABASE_URL is not a valid URL'); console.error(` Found: ${envVars['SUPABASE_URL']}`); console.error(' Expected format: https://your-project.supabase.co'); process.exit(1); }
66-71: Consider a stronger key sanity checkIf feasible, guard against clearly invalid keys (e.g., service anon keys) to catch a common misconfig earlier.
-if (envVars['SUPABASE_SERVICE_KEY'].length < 10) { +const svcKey = envVars['SUPABASE_SERVICE_KEY']; +if (!svcKey || svcKey.length < 10 || /anon/i.test(svcKey)) { console.error('ERROR: SUPABASE_SERVICE_KEY appears to be invalid (too short)'); console.error(' Please check your Supabase project settings'); process.exit(1); }python/src/server/api_routes/mcp_api.py (4)
65-80: Container “resolution” is still hard-coded; allow env override and label/name fallbackDespite the method name, this only fetches archon-mcp. Make it resilient:
- Allow override via env ARCHON_MCP_CONTAINER_NAME.
- Fallback to matching by name prefix or compose labels to survive renames.
def _resolve_container(self): - """Simple container resolution - just use fixed name.""" - if not self.docker_client: - return None - - try: - # Simple: Just look for the fixed container name - container = self.docker_client.containers.get("archon-mcp") - self.container_name = "archon-mcp" - mcp_logger.info("Found MCP container") - return container - except NotFound: - mcp_logger.warning("MCP container not found - is it running?") - self.container_name = "archon-mcp" - return None + """Resolve MCP container by explicit env name, then by common patterns.""" + if not self.docker_client: + return None + import os + target = os.getenv("ARCHON_MCP_CONTAINER_NAME", "archon-mcp") + try: + container = self.docker_client.containers.get(target) + self.container_name = target + mcp_logger.info(f"Found MCP container: name={self.container_name}") + return container + except NotFound: + # Fallback: try common patterns (compose service or name contains) + try: + for c in self.docker_client.containers.list(all=True): + names = (c.name,) + tuple(getattr(c, "names", []) or ()) + labels = c.labels or {} + if ( + any(target in n for n in names) or + labels.get("com.docker.compose.service") == target or + labels.get("io.archon.role") == "mcp" + ): + self.container_name = c.name + mcp_logger.info(f"Resolved MCP container via fallback: name={self.container_name}") + return c + except Exception as e: + mcp_logger.warning(f"Error scanning containers for MCP: {e}") + mcp_logger.warning(f"MCP container not found (target={target}) - is it running?") + self.container_name = target + return NoneNote: add an env var to docker-compose so override is easy.
85-88: Preserve stack traces in logsUse exc_info=True so failures during Docker client init aren’t opaque.
- except Exception as e: - mcp_logger.error(f"Failed to initialize Docker client: {str(e)}") + except Exception as e: + mcp_logger.error(f"Failed to initialize Docker client: {e}", exc_info=True) self.docker_client = None
439-487: Log reader robustness: handle container recreation mid-streamMinor: if the container is recreated, the cached self.container may go stale. On StopIteration/error, try one re-resolve to resume tails without manual user action.
except StopIteration: - break + # Try to re-resolve once (container may have been recreated) + try: + self.container = self._resolve_container() + if self.container: + log_generator = self.container.logs(stream=True, follow=True, tail=20) + continue + except Exception: + pass + break
167-175: Use Docker Compose v2 syntax in the user-facing error messageUpdate the CLI hint in python/src/server/api_routes/mcp_api.py to use the v2 “docker compose” command:
- File: python/src/server/api_routes/mcp_api.py, line 174
- "message": f"MCP container {self.container_name} not found. Run docker-compose up -d archon-mcp", + "message": f"MCP container {self.container_name} not found. Run: docker compose up -d archon-mcp",While this PR touches only the Python API route, a quick scan (
rg -nP 'docker-?compose') shows other references in your docs and Makefile. You may choose to batch-update those in a follow-up for full consistency.archon-ui-main/test/config/api.test.ts (5)
44-64: Good coverage for default port behavior; consider asserting the fallback log.Test correctly verifies the 8181 default when no port envs are present. Optionally, assert the console.info fallback message to guard regressions in developer feedback.
Apply this diff to validate the log:
it('should use default port 8181 when no port environment variables are set in development', async () => { + const infoSpy = vi.spyOn(console, 'info').mockImplementation(() => {}); // Development mode without any port variables @@ const { getApiUrl } = await import('../../src/config/api'); expect(getApiUrl()).toBe('http://localhost:8181'); + expect(infoSpy).toHaveBeenCalledWith('[Archon] Using default ARCHON_SERVER_PORT: 8181'); + infoSpy.mockRestore(); });
18-25: Restore global window.location between tests to avoid cross-test leaks.afterEach restores env but not window.location; future tests reassign it, but an explicit restore is safer and avoids subtle leaks.
Apply this diff:
beforeEach(() => { // Save original environment originalEnv = { ...import.meta.env }; + // Snapshot original window.location + (globalThis as any).__origLocation = window.location; // Clear the module cache to ensure fresh imports vi.resetModules(); }); afterEach(() => { // Restore original environment @@ Object.assign(import.meta.env, originalEnv); + // Restore original window.location + if ((globalThis as any).__origLocation) { + Object.defineProperty(window, 'location', { + value: (globalThis as any).__origLocation, + writable: true, + }); + delete (globalThis as any).__origLocation; + } });
138-166: Add negative/edge cases to port validation loop.Currently validates common numeric ports only. Add a few edge cases to harden behavior (stringy inputs, leading zeros, out-of-range). Even if getApiUrl() doesn’t enforce numeric ports, tests can assert that it at least returns a well-formed URL or document intended behavior.
Example additions:
const testCases = [ { port: '80', expected: 'http://localhost:80' }, @@ { port: '65535', expected: 'http://localhost:65535' }, + // Edge cases + { port: '0008181', expected: 'http://localhost:0008181' }, // stringly input preserved + { port: 'not-a-port', expected: 'http://localhost:not-a-port' }, // current behavior: no validation + // If you choose to validate, update expected and add validation in getApiUrl() ];If you plan to enforce numeric range in getApiUrl(), I can provide a small validator and migrate these expectations accordingly.
184-191: Consolidate error assertion for missing ARCHON_MCP_PORT.Two separate calls assert different substrings. Prefer a single call that asserts both substrings to avoid double execution and to improve clarity.
Apply this diff:
- await expect(mcpClientService.createArchonClient()).rejects.toThrow('ARCHON_MCP_PORT environment variable is required'); - await expect(mcpClientService.createArchonClient()).rejects.toThrow('Default value: 8051'); + await expect(mcpClientService.createArchonClient()).rejects.toThrow(/ARCHON_MCP_PORT environment variable is required[\s\S]*Default value: 8051/);
193-205: Align MCP test with new API URL logic and clean up fetch mocking.
- getApiUrl() now keys on VITE_ARCHON_SERVER_PORT; setting ARCHON_SERVER_PORT here has no effect in the browser build. Set VITE_ARCHON_SERVER_PORT to match the scenario.
- Use a spy for fetch and restore it after the test to avoid leaking mocks into other tests.
Apply this diff:
it('should use ARCHON_MCP_PORT when set', async () => { (import.meta.env as any).ARCHON_MCP_PORT = '9051'; - (import.meta.env as any).ARCHON_SERVER_PORT = '8181'; + (import.meta.env as any).VITE_ARCHON_SERVER_PORT = '8181'; @@ - // Mock the API call - global.fetch = vi.fn().mockResolvedValue({ + // Mock the API call + const fetchSpy = vi.spyOn(global, 'fetch' as any).mockResolvedValue({ ok: true, json: async () => ({ id: 'test-id', name: 'Archon', transport_type: 'http', connection_status: 'connected' }) } as any); @@ try { await mcpClientService.createArchonClient(); @@ } catch (error) { @@ } + fetchSpy.mockRestore(); });Optionally, also assert the full base URL using getApiUrl() to catch future port/host regressions.
Also applies to: 206-216, 217-236
Makefile (3)
48-54: Make full-Docker output env-aware and use detected Compose CLI.Avoid hardcoded ports so docs and output remain truthful when .env changes.
Apply this diff:
dev-docker: check @echo "Starting full Docker environment..." - @docker-compose --profile full up -d --build + @$(COMPOSE) --profile full up -d --build @echo "✓ All services running" - @echo "Frontend: http://localhost:3737" - @echo "API: http://localhost:8181" + @set -a; [ -f .env ] && . ./.env; set +a; \ + echo "Frontend: http://$${HOST:-localhost}:$${ARCHON_UI_PORT:-3737}"; \ + echo "API: http://$${HOST:-localhost}:$${ARCHON_SERVER_PORT:-8181}"
56-60: Simplify stop to bring everything down regardless of profile.Multiple --profile flags are unnecessary for down. Also use the detected COMPOSE CLI.
Apply this diff:
stop: @echo "Stopping all services..." - @docker-compose --profile backend --profile frontend --profile full down + @$(COMPOSE) down @echo "✓ Services stopped"
1-6: Satisfy checkmake “minphony” by adding an ‘all’ alias and keep help default.Not critical, but easy to appease the linter.
Apply this diff:
-.PHONY: help dev dev-docker stop test test-fe test-be lint lint-fe lint-be clean install check +.PHONY: all help dev dev-docker stop test test-fe test-be lint lint-fe lint-be clean install check +all: helpAlso applies to: 99-99
docker-compose.yml (3)
3-3: Remove trailing spaces to satisfy yamllint.There’s trailing whitespace on Line 3.
Apply this diff:
-# - "frontend": Starts only the frontend UI service +# - "frontend": Starts only the frontend UI service
35-37: Security note: Docker socket mount grants root-equivalent host access.Mounting /var/run/docker.sock is powerful; acceptable for local dev, but avoid in production or gate behind an opt-in flag/profile.
If you expect users to run “full” beyond dev, consider:
- Ship a separate profile (e.g., mcp-docker-sock) or
- Document the risk prominently in README under Troubleshooting/Deployment.
21-31: Optional: Add restart policies for a smoother dev experience.Not required, but restart: unless-stopped improves resilience during local Docker restarts.
Example:
services: archon-server: @@ ports: - "${ARCHON_SERVER_PORT:-8181}:${ARCHON_SERVER_PORT:-8181}" + restart: unless-stopped @@ archon-mcp: @@ ports: - "${ARCHON_MCP_PORT:-8051}:${ARCHON_MCP_PORT:-8051}" + restart: unless-stopped @@ archon-agents: @@ ports: - "${ARCHON_AGENTS_PORT:-8052}:${ARCHON_AGENTS_PORT:-8052}" + restart: unless-stopped @@ frontend: @@ ports: - "${ARCHON_UI_PORT:-3737}:3737" + restart: unless-stoppedAlso applies to: 76-90, 121-130, 151-157
README.md (6)
71-71: Fix Windows-style path separator.Use forward slashes for cross-platform clarity.
Apply this diff:
-OPTIONAL: If you want to enable the reranking RAG strategy, uncomment lines 20-22 in `python\requirements.server.txt`. This will significantly increase the size of the Archon Server container which is why it's off by default. +OPTIONAL: If you want to enable the reranking RAG strategy, uncomment lines 20-22 in `python/requirements.server.txt`. This will significantly increase the size of the Archon Server container which is why it's off by default.
75-86: Recommend running make check before starting services; reflect both Compose CLIs.Small UX win: surface environment/tooling issues up front. Also, prefer “docker compose” (v2) while keeping the current command as an alternative.
Apply this diff:
4. **Start Services** (choose one): - **Full Docker Mode (Recommended for Normal Archon Usage)** + **Full Docker Mode (Recommended for Normal Archon Usage)** + First, verify your environment: + ```bash + make check + ``` ```bash - docker-compose --profile full up --build -d + docker compose --profile full up --build -d # or make dev-docker ```
126-128: Prefer “docker compose” (v2) in reset instructions.Stays current with modern Docker tooling.
Apply this diff:
- docker-compose --profile full up -d + docker compose --profile full up -d
138-156: Stabilize the “Installing Make” anchor to satisfy MD lint.The MD linter flagged invalid fragments. Adding an explicit HTML anchor guarantees the heading slug regardless of emoji handling.
Apply this diff:
-## 🛠️ Installing Make +<a id="installing-make"></a> +## 🛠️ Installing Make
382-390: Prefer “docker compose logs” and add backend/agents services to the examples.Minor modernization and completeness.
Apply this diff:
```bash -# View logs using Docker Compose directly -docker-compose logs -f # All services -docker-compose logs -f archon-server # API server -docker-compose logs -f archon-mcp # MCP server -docker-compose logs -f archon-ui # Frontend +# View logs using Docker Compose directly +docker compose logs -f # All services +docker compose logs -f archon-server # API server +docker compose logs -f archon-mcp # MCP server +docker compose logs -f archon-agents # Agents service +docker compose logs -f archon-ui # Frontend--- `432-437`: **Clarify port override guidance to match frontend behavior.** Since getApiUrl() reads VITE_ARCHON_SERVER_PORT in dev, remind users to set it alongside ARCHON_SERVER_PORT when running the UI locally. The current text says this implicitly; consider adding a short example: ```diff - For custom ports, ensure both `ARCHON_SERVER_PORT` and `VITE_ARCHON_SERVER_PORT` are set + - For custom ports, ensure both `ARCHON_SERVER_PORT` (backend) and `VITE_ARCHON_SERVER_PORT` (frontend dev) are set, e.g.: + ``` + ARCHON_SERVER_PORT=8282 + VITE_ARCHON_SERVER_PORT=8282 + ```
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (11)
.gitignore(1 hunks)Makefile(1 hunks)README.md(7 hunks)archon-ui-main/Dockerfile(1 hunks)archon-ui-main/src/components/BackendStartupError.tsx(1 hunks)archon-ui-main/src/config/api.ts(1 hunks)archon-ui-main/test/config/api.test.ts(5 hunks)archon-ui-main/vite.config.ts(2 hunks)check-env.js(1 hunks)docker-compose.yml(4 hunks)python/src/server/api_routes/mcp_api.py(3 hunks)
✅ Files skipped from review due to trivial changes (1)
- .gitignore
🚧 Files skipped from review as they are similar to previous changes (1)
- archon-ui-main/src/config/api.ts
🧰 Additional context used
📓 Path-based instructions (7)
{python/**/*.py,archon-ui-main/src/**/*.{ts,tsx,js,jsx}}
📄 CodeRabbit inference engine (CLAUDE.md)
{python/**/*.py,archon-ui-main/src/**/*.{ts,tsx,js,jsx}}: Remove dead code immediately; do not keep legacy/unused functions
Avoid comments that reference change history (e.g., LEGACY, CHANGED, REMOVED); keep comments focused on current functionality
Files:
archon-ui-main/src/components/BackendStartupError.tsxpython/src/server/api_routes/mcp_api.py
archon-ui-main/src/components/**
📄 CodeRabbit inference engine (CLAUDE.md)
Place reusable UI components in archon-ui-main/src/components/
Files:
archon-ui-main/src/components/BackendStartupError.tsx
archon-ui-main/test/**
📄 CodeRabbit inference engine (CLAUDE.md)
Place frontend tests under archon-ui-main/test/
Files:
archon-ui-main/test/config/api.test.ts
python/src/{server,mcp,agents}/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
python/src/{server,mcp,agents}/**/*.py: Fail fast on service startup failures, missing configuration, database connection issues, auth failures, critical dependency outages, and invalid data that would corrupt state
External API calls should use retry with exponential backoff and ultimately fail with a clear, contextual error message
Error messages must include context (operation being attempted) and relevant IDs/URLs/data for debugging
Preserve full stack traces in logs (e.g., Python logging with exc_info=True)
Use specific exception types; avoid catching broad Exception unless re-raising with context
Never signal failure by returning None/null; raise a descriptive exception instead
Files:
python/src/server/api_routes/mcp_api.py
python/src/server/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
python/src/server/**/*.py: For batch processing and background tasks, continue processing but log detailed per-item failures and return both successes and failures
Do not crash the server on a single WebSocket event failure; log the error and continue serving other clients
Files:
python/src/server/api_routes/mcp_api.py
python/**/*.py
📄 CodeRabbit inference engine (CLAUDE.md)
python/**/*.py: Target Python 3.12 with a 120-character line length
Use Ruff for linting and Mypy for type checking before commit
Files:
python/src/server/api_routes/mcp_api.py
python/src/server/**
📄 CodeRabbit inference engine (CLAUDE.md)
Keep FastAPI application code under python/src/server/ (routes in api_routes/, services in services/, main in main.py)
Files:
python/src/server/api_routes/mcp_api.py
🧠 Learnings (2)
📚 Learning: 2025-08-21T11:22:33.541Z
Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T11:22:33.541Z
Learning: Applies to .env : Require SUPABASE_URL and SUPABASE_SERVICE_KEY in the .env file; optionally OPENAI_API_KEY, LOGFIRE_TOKEN, LOG_LEVEL
Applied to files:
check-env.jsREADME.mdMakefile
📚 Learning: 2025-08-21T11:22:33.541Z
Learnt from: CR
PR: coleam00/Archon#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-21T11:22:33.541Z
Learning: Applies to archon-ui-main/test/** : Place frontend tests under archon-ui-main/test/
Applied to files:
README.md
🧬 Code graph analysis (1)
archon-ui-main/test/config/api.test.ts (1)
archon-ui-main/src/config/api.ts (1)
getApiUrl(9-31)
🪛 markdownlint-cli2 (0.17.2)
README.md
49-49: Link fragments should be valid
(MD051, link-fragments)
426-426: Link fragments should be valid
(MD051, link-fragments)
🪛 LanguageTool
README.md
[grammar] ~85-~85: There might be a mistake here.
Context: ...starts all core microservices in Docker: - Server: Core API and business logic (P...
(QB_NEW_EN)
[grammar] ~98-~98: There might be a mistake here.
Context: ... website ### 🚀 Quick Command Reference | Command | Description ...
(QB_NEW_EN)
[grammar] ~138-~138: There might be a mistake here.
Context: ...ing.
(QB_NEW_EN)
[grammar] ~278-~278: There might be a mistake here.
Context: ... following ports: - archon-ui: 3737 - archon-server: 8181 - archon-mcp: ...
(QB_NEW_EN)
[grammar] ~279-~279: There might be a mistake here.
Context: ...hon-ui**: 3737 - archon-server: 8181 - archon-mcp: 8051 - archon-agents: ...
(QB_NEW_EN)
[grammar] ~280-~280: There might be a mistake here.
Context: ...on-server**: 8181 - archon-mcp: 8051 - archon-agents: 8052 - archon-docs:...
(QB_NEW_EN)
[grammar] ~281-~281: There might be a mistake here.
Context: ...on-mcp**: 8051 - archon-agents: 8052 - archon-docs: 3838 (optional) ### Chan...
(QB_NEW_EN)
[grammar] ~330-~330: There might be a mistake here.
Context: ...hostname and MCP port ## 🔧 Development ### Quick Start ```bash # Install dependenci...
(QB_NEW_EN)
[grammar] ~360-~360: There might be a mistake here.
Context: ...e - make dev-docker For all services in Docker environment: - All services run...
(QB_NEW_EN)
[grammar] ~394-~394: There might be a mistake here.
Context: ...you make changes. ## 🔍 Troubleshooting ### Common Issues and Solutions #### Port Co...
(QB_NEW_EN)
[grammar] ~452-~452: There might be a mistake here.
Context: ...'re running in hybrid mode (make dev) for best HMR experience - Backend: Chec...
(QB_NEW_EN)
🪛 checkmake (0.2.2)
Makefile
[warning] 5-5: Missing required phony target "all"
(minphony)
[warning] 7-7: Target body for "help" exceeds allowed length of 5 (14).
(maxbodylength)
[warning] 39-39: Target body for "dev" exceeds allowed length of 5 (6).
(maxbodylength)
[warning] 88-88: Target body for "clean" exceeds allowed length of 5 (9).
(maxbodylength)
🪛 YAMLlint (1.37.1)
docker-compose.yml
[error] 3-3: trailing spaces
(trailing-spaces)
🔇 Additional comments (3)
archon-ui-main/test/config/api.test.ts (2)
66-83: LGTM: honors VITE_ARCHON_SERVER_PORT in dev.Expectation matches getApiUrl()’s new Vite env behavior.
85-102: LGTM: https + custom host scenario is covered.Covers protocol/host composition in dev mode.
docker-compose.yml (1)
160-163: No changes required: curl is already installed in the UI imageThe healthcheck in
docker-compose.ymlusescurl, andarchon-ui-main/Dockerfilealready installs it:
- archon-ui-main/Dockerfile (line 7):
RUN apk add --no-cache python3 make g++ git curlSince
curlis present, the existing healthcheck will work as expected.
| check: | ||
| @echo "Checking environment..." | ||
| @node check-env.js | ||
| @echo "Checking Docker..." | ||
| @docker --version > /dev/null 2>&1 && echo "✓ Docker installed" || echo "✗ Docker not found" | ||
| @docker-compose --version > /dev/null 2>&1 && echo "✓ Docker Compose installed" || echo "✗ Docker Compose not found" | ||
|
|
There was a problem hiding this comment.
🛠️ Refactor suggestion
Make “check” fail fast and support both “docker compose” and “docker-compose”.
Currently prints missing tools but continues, and only checks docker-compose. Detect either CLI and abort early if missing; also verify Node presence before running check-env.js.
Apply this diff (adds COMPOSE detection too; see next comment):
+COMPOSE ?= $(shell command -v docker-compose >/dev/null 2>&1 && echo docker-compose || echo "docker compose")
+
# Check environment
check:
@echo "Checking environment..."
- @node check-env.js
+ @node -v >/dev/null 2>&1 || { echo "✗ Node.js not found (require Node 18+)."; exit 1; }
+ @node check-env.js
@echo "Checking Docker..."
- @docker --version > /dev/null 2>&1 && echo "✓ Docker installed" || echo "✗ Docker not found"
- @docker-compose --version > /dev/null 2>&1 && echo "✓ Docker Compose installed" || echo "✗ Docker Compose not found"
+ @docker --version > /dev/null 2>&1 || { echo "✗ Docker not found"; exit 1; }
+ @$(COMPOSE) version > /dev/null 2>&1 || { echo "✗ Docker Compose not found"; exit 1; }
+ @echo "✓ Environment OK"📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| check: | |
| @echo "Checking environment..." | |
| @node check-env.js | |
| @echo "Checking Docker..." | |
| @docker --version > /dev/null 2>&1 && echo "✓ Docker installed" || echo "✗ Docker not found" | |
| @docker-compose --version > /dev/null 2>&1 && echo "✓ Docker Compose installed" || echo "✗ Docker Compose not found" | |
| COMPOSE ?= $(shell command -v docker-compose >/dev/null 2>&1 && echo docker-compose || echo docker compose) | |
| # Check environment | |
| check: | |
| @echo "Checking environment..." | |
| @node -v >/dev/null 2>&1 || { echo "✗ Node.js not found (require Node 18+)."; exit 1; } | |
| @node check-env.js | |
| @echo "Checking Docker..." | |
| @docker --version > /dev/null 2>&1 || { echo "✗ Docker not found"; exit 1; } | |
| @$(COMPOSE) version > /dev/null 2>&1 || { echo "✗ Docker Compose not found"; exit 1; } | |
| @echo "✓ Environment OK" |
🤖 Prompt for AI Agents
In Makefile around lines 31 to 37, the "check" target currently prints missing
tools but continues and only checks for docker-compose; update it to fail fast
by first verifying Node (node --version) before running check-env.js, then
verify Docker (docker --version) and detect Docker Compose by checking for
either "docker compose" (docker compose version) or "docker-compose --version";
if any required tool is missing print a clear error and exit with non-zero
status immediately so make stops. Ensure success messages are printed when tools
are present and that the target returns non-zero on failure.
|
Thank you for this contribution, i will close this PR and i have implemented this in #435 Closing this when the other PR is merged, i attributed your contribution and built on top of this branch @zaksnet |
|
merged #435, closing this! |
…0#330) DRY fix - extracts duplicate JWT parsing logic to shared utility: - Create lib/jwtUtils.ts with proper base64url decoding (RFC 4648) - Update chat/send/route.ts to use shared ownerFromJwt - Update chat/messages/route.ts to use shared ownerFromJwt - Add component parameter for contextual error logging The shared implementation fixes base64url encoding by replacing '-' with '+' and '_' with '/' before decoding, and handles padding correctly per RFC 4648. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: Codex Agent <codex-agent@example.com> Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
- Add IDOR vulnerability details with affected routes (PR coleam00#329) - Expand JWT base64url decoding with RFC 4648 details (PR coleam00#330) - Add structured logging for Loki/Promtail integration (PR coleam00#331) - Add post-refactoring cleanup pattern - Add Observability checklist section - Mark completed action items with PR/commit references 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
) * Investigate issue #330: Wire up baseBranch config * Fix: Wire up baseBranch config option for worktree creation (#330) worktree.baseBranch was defined in repo config but ignored by WorktreeProvider, so worktree sync always used the auto-detected default branch. Changes: - load repo config once during worktree creation and reuse for sync/copy - plumb configured baseBranch through syncWorkspaceBeforeCreate and git.syncWorkspace - update git/worktree tests to exercise configured override and fallback handling Fixes #330 * Archive investigation for issue #330 * fix: Make configured base branch errors fatal with actionable messages When worktree.baseBranch is configured in .archon/config.yaml and the branch doesn't exist, users should get a clear error message explaining how to fix it - not a silent fallback to the default branch. Changes: - Reorder syncWorkspace to fetch before checkout (handles remote-only branches) - Add actionable error when configured branch not found on remote - Add actionable error when configured branch can't be checked out - Make WorktreeProvider re-throw configured branch errors (not non-fatal) - Add tests for invalid configured branch scenarios - Update docs to explain baseBranch behavior and error handling * chore: Remove duplicate investigation artifact (already in completed/)
…#330) (coleam00#334) * Investigate issue coleam00#330: Wire up baseBranch config * Fix: Wire up baseBranch config option for worktree creation (coleam00#330) worktree.baseBranch was defined in repo config but ignored by WorktreeProvider, so worktree sync always used the auto-detected default branch. Changes: - load repo config once during worktree creation and reuse for sync/copy - plumb configured baseBranch through syncWorkspaceBeforeCreate and git.syncWorkspace - update git/worktree tests to exercise configured override and fallback handling Fixes coleam00#330 * Archive investigation for issue coleam00#330 * fix: Make configured base branch errors fatal with actionable messages When worktree.baseBranch is configured in .archon/config.yaml and the branch doesn't exist, users should get a clear error message explaining how to fix it - not a silent fallback to the default branch. Changes: - Reorder syncWorkspace to fetch before checkout (handles remote-only branches) - Add actionable error when configured branch not found on remote - Add actionable error when configured branch can't be checked out - Make WorktreeProvider re-throw configured branch errors (not non-fatal) - Add tests for invalid configured branch scenarios - Update docs to explain baseBranch behavior and error handling * chore: Remove duplicate investigation artifact (already in completed/)
…#330) (coleam00#334) * Investigate issue coleam00#330: Wire up baseBranch config * Fix: Wire up baseBranch config option for worktree creation (coleam00#330) worktree.baseBranch was defined in repo config but ignored by WorktreeProvider, so worktree sync always used the auto-detected default branch. Changes: - load repo config once during worktree creation and reuse for sync/copy - plumb configured baseBranch through syncWorkspaceBeforeCreate and git.syncWorkspace - update git/worktree tests to exercise configured override and fallback handling Fixes coleam00#330 * Archive investigation for issue coleam00#330 * fix: Make configured base branch errors fatal with actionable messages When worktree.baseBranch is configured in .archon/config.yaml and the branch doesn't exist, users should get a clear error message explaining how to fix it - not a silent fallback to the default branch. Changes: - Reorder syncWorkspace to fetch before checkout (handles remote-only branches) - Add actionable error when configured branch not found on remote - Add actionable error when configured branch can't be checked out - Make WorktreeProvider re-throw configured branch errors (not non-fatal) - Add tests for invalid configured branch scenarios - Update docs to explain baseBranch behavior and error handling * chore: Remove duplicate investigation artifact (already in completed/)
2 participants
Summary
Improves the development experience by creating a hybrid setup where Python backend services run in Docker while the frontend runs locally, providing instant HMR and
faster iteration cycles.
Changes Made
dev.batscript that orchestrates the development environment startupdocker-compose.backend.ymlfor running only backend services in DockerType of Change
Affected Services
Testing
Test Evidence