mirror of
https://github.com/penpot/penpot.git
synced 2026-08-01 19:06:18 +00:00
16dc83616a
* 🐳 Split devenv compose for parallel workspaces Move shared services into an infra compose file and keep the main devenv container plus Valkey in a separate compose file driven by defaults.env. Parameterize host-side ports, container names, source path, and runtime env while keeping container-internal ports fixed for same-origin proxying. Make tmux startup idempotent, add attach-devenv for the live instance, move shared MinIO user setup to infra startup, and let exporter scripts load backend _env.local overrides. Co-authored-by: Codex <codex@openai.com> * 🐳 Run parallel devenv instances against shared infra Add support for running N parallel devenv instances under separate compose projects sharing Postgres, MinIO, mailer, and LDAP. Each instance has its own main container, Valkey, source checkout, tmux session, and host port range offset by 10000 (3449 -> 13449 -> 23449, etc.). ./manage.sh run-devenv-agentic --n-instances N reconciles the running set to exactly {ws0..ws(N-1)}: missing instances are created (workspace sync from the live repo via git ls-files + per-instance env-file generation under docker/devenv/instances/ + detached tmux startup), surplus instances are stopped highest-first via compose down (never -v), already-running instances are left untouched. ws0 binds the live repo at PWD; ws1+ are scratch clones under ~/.penpot/penpot_workspaces/. Backend workers (enable-backend-worker) are gated on PENPOT_BACKEND_WORKER in backend/scripts/_env; ws1+ overlays disable them so async-task notifications stay bound to a single Valkey Pub/Sub instance. Compose helpers wrap docker compose with env -i so per-instance overlay --env-file actually overrides defaults.env -- without the strip, the shell env from sourcing defaults.env at startup would shadow the overlay (Compose gives shell precedence over --env-file). Other: - Drop network aliases (- main, - redis); use container_name for cross-container DNS so multiple instances on the shared network don't fight over the same DNS name. - Pin volume names via name: (PENPOT_*_VOLUME) so volumes survive project renames; ws0 keeps the pre-existing physical names (penpotdev_*). - Remove cross-project depends_on from main.yml (postgres/minio-setup now live in penpotdev-infra); manage.sh ensure-infra-up docker-waits on the minio-setup one-shot. - Strict arg parsing in run-devenv / run-devenv-agentic; --n-instances 0 rejected. - Remove unused Host-matched server block from the Caddyfile. Memory mem:devenv/core and developer docs updated. Co-authored-by: Codex <codex@openai.com> * ✨ Document and stabilise the parallel-workspace CLI; wire AI agents Improve parallel-workspaces developer CLI, and add an opt-in layer that lets four AI coding agents (Claude Code, opencode, VS Code Copilot, OpenAI Codex CLI) drive a specific workspace through a single launcher command. Parallel-workspace semantics ---------------------------- each run-devenv-agentic call brings up one wsN; --ws N (integer; default 0) targets a specific workspace and auto-starts ws0 first when N>=1 so the worker invariant holds. --sync is forbidden on ws0 and re-seeds the workspace from the live repo for ws1+. Stop semantics mirror the start invariant -- ws0 is the last to stop, shared infra stops with it, --all walks every instance highest-first. The worker policy section explains why workers run only on ws0 (Postgres FOR UPDATE SKIP LOCKED is safe across many workers but the cron dedup primitive is best-effort, and :telemetry / :audit-log-archive are not idempotent). Per-instance Valkey Pub/Sub isolation, msgbus topology, and the "async task notifications miss ws1+ tabs" caveat are stated explicitly. The mem:prod-infra/core memory captures the same external-services and task-queue / Pub-Sub topology in agent-readable form, and mem:backend/core and mem:critical-info now cross-link it so backend work surfaces the horizontal-scaling constraints from the start. AI coding agent integration --------------------------- New top-level .devenv/ directory holds committed templates (templates/{claude-code,opencode,vscode}.json and templates/codex.toml, each with \${PENPOT_MCP_PORT} and \${SERENA_MCP_PORT} placeholders) plus committed shared entries (matching shared/* files for Playwright, the only workspace-independent server we ship today). ./manage.sh start-coding-agent <claude|opencode|vscode|codex> [--ws N] launches the chosen client against one workspace. It cd's into the target's directory (the live repo for ws0; workspace-path "wsN" for ws1+) and refuses to launch unless (a) the binary is on PATH, (b) the workspace directory exists for ws1+, and (c) the instance is up (devenv-main-running) -- the MCP servers only exist while the devenv is running. The agentic-devenv guide is restructured around this Quick start path, with a per-client table and a Manual configuration fallback for clients we don't cover. Co-Authored-By: Codex <codex@openai.com> Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * ♻️ Scope the shadow devtools to the dev build --------- Co-authored-by: Codex <codex@openai.com> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
134 lines
6.5 KiB
Markdown
134 lines
6.5 KiB
Markdown
# `.devenv/` — Per-Workspace AI-Client MCP Configs
|
|
|
|
This directory carries the pieces needed to point an AI coding agent
|
|
(currently Claude Code, opencode, VS Code Copilot, and the OpenAI Codex CLI)
|
|
at the MCP servers running inside the parallel devenv instance the developer
|
|
is currently working in. Every parallel workspace (`ws0`, `ws1`, …) has its
|
|
own copy because the Penpot MCP and Serena MCP host ports are
|
|
workspace-specific.
|
|
|
|
## Layout
|
|
|
|
```
|
|
.devenv/
|
|
README.md
|
|
scripts/
|
|
merge-mcp-config.py # generator helper invoked by manage.sh
|
|
shared/ # committed; workspace-independent entries
|
|
claude-code.json # Playwright — same for every workspace
|
|
opencode.json
|
|
vscode.json
|
|
codex.toml
|
|
templates/ # committed; entries with ${...} port placeholders
|
|
claude-code.json # Penpot MCP, Serena MCP — port is the only diff
|
|
opencode.json
|
|
vscode.json
|
|
codex.toml
|
|
mcp/ # gitignored; written by manage.sh per workspace
|
|
claude-code.json # loaded via Claude Code's --mcp-config flag
|
|
opencode.json # loaded via OPENCODE_CONFIG env var
|
|
```
|
|
|
|
One more file is generated outside `.devenv/`, in the directory VS Code itself
|
|
auto-discovers (gitignored):
|
|
|
|
```
|
|
.vscode/mcp.json # auto-loaded by GitHub Copilot in VS Code
|
|
```
|
|
|
|
Codex is the exception: it has no way to load an MCP config from an arbitrary
|
|
path, and its only project-level config file (`.codex/config.toml`) is one a
|
|
developer may already own. So we do **not** write a file for Codex at all —
|
|
`start-coding-agent codex` injects our servers as `-c` command-line overrides
|
|
built fresh from `shared/codex.toml` + `templates/codex.toml` at launch.
|
|
|
|
* **`shared/`** holds MCP entries that don't depend on the workspace — the
|
|
browser-driving Playwright server today, plus any other workspace-independent
|
|
servers we add later. Same content in every workspace, so it's a static
|
|
checked-in file.
|
|
* **`templates/`** holds the workspace-specific entries (Penpot MCP, Serena
|
|
MCP) with `${PENPOT_MCP_PORT}` and `${SERENA_MCP_PORT}` placeholders. The
|
|
placeholders are resolved per-workspace from the port-base constants in
|
|
`manage.sh`.
|
|
* **`mcp/`** (Claude Code, opencode) is the result of merging `shared/` with
|
|
the port-substituted `templates/`. `manage.sh` writes these on every
|
|
`run-devenv-agentic` pass. Gitignored, dedicated paths with no developer
|
|
content — never edit by hand, your edits will be overwritten on the next
|
|
reconcile.
|
|
* **`.vscode/mcp.json`** is the same merge, but written to the path VS Code
|
|
auto-discovers. Because on `ws0` that path *is* the live repo's own file, the
|
|
reconcile **deep-merges** into it: any servers you added yourself are kept,
|
|
and only the entries we manage (`penpot`, `serena-devenv`, `playwright`) are
|
|
(re)written to the current ports. On `ws1+` the file doesn't exist yet, so it
|
|
is created from scratch.
|
|
* **`scripts/merge-mcp-config.py`** is the generator. Its `json` mode does the
|
|
JSON deep-merge (with `--merge-into-existing` for the VS Code path); its
|
|
`codex-args` mode prints the `-c` assignments for Codex. `manage.sh`'s
|
|
`_merge-mcp-config-json` helper is a thin shim over the former, and
|
|
`start-coding-agent` calls the latter directly. Run
|
|
`python3 .devenv/scripts/merge-mcp-config.py --help` for the CLI.
|
|
|
|
## Launching a coding agent
|
|
|
|
The easiest path is the wrapper command, which knows the right flags per
|
|
client, `cd`'s into the target workspace, and refuses to launch unless the
|
|
target instance is running and its MCP config has been generated:
|
|
|
|
```bash
|
|
# Default target is ws0 (the live repo).
|
|
./manage.sh start-coding-agent claude [...args to forward]
|
|
./manage.sh start-coding-agent opencode [...args to forward]
|
|
./manage.sh start-coding-agent vscode [...args to forward to 'code']
|
|
./manage.sh start-coding-agent codex [...args to forward]
|
|
|
|
# Target a parallel workspace with --ws N. N is an integer (non-negative);
|
|
# 'main', 'ws1' and similar spellings are rejected.
|
|
./manage.sh start-coding-agent claude --ws 1
|
|
./manage.sh start-coding-agent opencode --ws 2
|
|
```
|
|
|
|
Equivalents by hand (run from inside the workspace directory):
|
|
|
|
```bash
|
|
claude --mcp-config .devenv/mcp/claude-code.json
|
|
OPENCODE_CONFIG=.devenv/mcp/opencode.json opencode
|
|
code "$PWD" # VS Code auto-discovers .vscode/mcp.json
|
|
# Codex: pass our servers as -c overrides (no config file is written).
|
|
codex $(python3 .devenv/scripts/merge-mcp-config.py --format codex-args \
|
|
.devenv/shared/codex.toml .devenv/templates/codex.toml \
|
|
| sed 's/^/-c /')
|
|
```
|
|
|
|
`start-coding-agent codex` does the `-c` wiring for you (and resolves the
|
|
workspace's ports first). Because our servers arrive as command-line
|
|
overrides, no "trusted project" prompt is involved for them — that prompt only
|
|
gates Codex's own `.codex/config.toml`, which we never write.
|
|
|
|
## Overriding our entries
|
|
|
|
Both the auto-discovered configs and the launcher-loaded configs sit *on top
|
|
of* the developer's global config (with varying precedence rules). All four
|
|
clients offer escape hatches for shadowing entries we ship:
|
|
|
|
* **Claude Code** — `claude mcp add --scope local …` installs a private entry
|
|
that overrides the one in `mcp/claude-code.json`. Local scope wins.
|
|
* **opencode** — drop an `opencode.json` at the repo root with the override
|
|
entries you need. opencode's precedence chain is *global → `OPENCODE_CONFIG`
|
|
→ project*, so the project file always wins. The root `opencode.json` is
|
|
gitignored on purpose, since these overrides are personal.
|
|
* **VS Code Copilot** — the reconcile deep-merges into `.vscode/mcp.json`, so
|
|
any servers you add there yourself are preserved (only `penpot`,
|
|
`serena-devenv` and `playwright` are rewritten). To shadow one of *ours*,
|
|
put an entry under the same name in your VS Code user-profile MCP config —
|
|
it is loaded alongside the workspace file and wins.
|
|
* **Codex CLI** — our servers arrive as `-c` overrides, which are Codex's
|
|
highest-precedence layer, so they win over a same-named `[mcp_servers.<name>]`
|
|
in your `~/.codex/config.toml` or a project `.codex/config.toml`. To override
|
|
one of ours, append your own `-c` after the client name — extra args are
|
|
forwarded after ours and the later `-c` wins, e.g.
|
|
`./manage.sh start-coding-agent codex -- -c 'mcp_servers.penpot.url="…"'`.
|
|
|
|
See `docs/technical-guide/developer/agentic-devenv.md` for the broader
|
|
client-configuration story (browser remote debugging, AI-client config
|
|
schemas, manual setup for unsupported clients).
|