diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile new file mode 100644 index 0000000000..620a5483ce --- /dev/null +++ b/.devcontainer/Dockerfile @@ -0,0 +1,153 @@ +# syntax=docker/dockerfile:1 + +# Base image: Microsoft's TypeScript+Node devcontainer image. It works on both +# linux/amd64 and linux/arm64, gets monthly security patches, and ships the +# non-root `node` user (UID 1000, i.e. user ID 1000), zsh + Oh My Zsh, eslint +# global, and the `gh` CLI. +# +# We pin the image by digest, not by tag. That way a silent upstream retag can't +# change the build under us. This matches the Dockerfile.cli / +# gitnexus/Dockerfile.test convention and issue #1451. +# +# We pin it as a bare `name@digest` with NO `:tag` prefix on purpose. The +# production Dockerfiles use plain `docker build`, but this one is built by +# `@devcontainers/cli` / the VS Code Dev Containers resolver. That resolver's +# image-name parser rejects the combined `name:tag@sha256:...` form. +# +# The digest below is for the `1-22-bookworm` tag. It is the multi-arch +# manifest-list digest, so it still picks the right platform. To refresh it when +# bumping the readable tag, run: +# docker buildx imagetools inspect \ +# mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm \ +# --format '{{json .Manifest.Digest}}' +FROM mcr.microsoft.com/devcontainers/typescript-node@sha256:7c2e711a4f7b02f32d2da16192d5e05aa7c95279be4ce889cff5df316f251c1d + +# Build args. We deliberately set no version defaults here. devcontainer.json +# `build.args` is the single source of truth for versions. A standalone +# `docker build .devcontainer/` (for example, a CI smoke test) must pass each +# version with --build-arg. Without a default, the build fails loudly instead of +# silently drifting from the version pinned in devcontainer.json. +ARG CLAUDE_CODE_VERSION +ARG CODEX_VERSION +# Cursor is pinned by version plus a per-arch tarball sha256 hash. The install +# step below verifies that hash. All three values live in devcontainer.json +# build.args. They follow the same rule as the others: one source of truth, and +# no default so the build fails loudly if a value is missing. +ARG CURSOR_VERSION +ARG CURSOR_SHA256_X64 +ARG CURSOR_SHA256_ARM64 +# Bun is installed via the official remote script (bun.sh/install), pinned by +# version. UNLIKE Cursor and the npm packages, this install path runs an +# UNVERIFIED remote script — there is no tarball-hash check. Chosen explicitly +# at request time over the pin-by-sha256 alternative for install-script +# simplicity. To harden later, switch to a pinned tarball + per-arch sha256 in +# the Cursor style (release artifacts at github.com/oven-sh/bun/releases). +ARG BUN_VERSION +ARG TZ=UTC +ARG USERNAME=node + +# Copy the build-only ARGs into runtime ENV so shells and lifecycle scripts can +# read them. We deliberately do not set CLAUDE_CONFIG_DIR here. Its one true +# value lives in devcontainer.json `containerEnv`, and the runtime value wins +# anyway. +ENV CLAUDE_CODE_VERSION=${CLAUDE_CODE_VERSION} \ + CODEX_VERSION=${CODEX_VERSION} \ + CURSOR_VERSION=${CURSOR_VERSION} \ + BUN_VERSION=${BUN_VERSION} \ + BUN_INSTALL=/home/${USERNAME}/.bun \ + TZ=${TZ} \ + DEVCONTAINER=true \ + NODE_OPTIONS=--max-old-space-size=4096 \ + POWERLEVEL9K_DISABLE_GITSTATUS=true + +# Native build toolchain that gitnexus/postinstall needs. It compiles +# tree-sitter native bindings, the vendored Dart/Proto/Swift grammars, and the +# @ladybugdb/core N-API addon (a native Node add-on). python3, make, and g++ are +# required. This mirrors the apt block in the existing Dockerfile.cli / +# gitnexus/Dockerfile.test images. +RUN apt-get update \ + && apt-get install -y --no-install-recommends \ + python3 make g++ git curl ca-certificates bash unzip \ + && rm -rf /var/lib/apt/lists/* + +# Create and chown the named-volume mount points (~/.npm, ~/.local, +# /commandhistory) up front. That way an empty volume inherits `node:node` +# ownership the first time it is mounted. The three CLI config dirs (~/.claude, +# ~/.codex, ~/.cursor) are bind-mounted from the host instead. A bind mount +# completely hides the image-side ownership, so those paths need no chown here. +RUN mkdir -p \ + /home/${USERNAME}/.npm \ + /home/${USERNAME}/.local/bin \ + /commandhistory \ + && chown -R ${USERNAME}:${USERNAME} \ + /home/${USERNAME}/.npm \ + /home/${USERNAME}/.local \ + /commandhistory + +USER ${USERNAME} + +# Install Claude Code and the Codex CLI globally, as the `node` user. The base +# image sets /usr/local/share/npm-global as the npm-global prefix and makes the +# `npm` group writable by `node`. So `npm install -g` works without sudo. Both +# versions come from build args. To upgrade, bump them in devcontainer.json and +# rebuild. +RUN npm install -g \ + @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION} \ + @openai/codex@${CODEX_VERSION} + +# Install the Cursor CLI. It is pinned and hash-verified, and we run no remote +# script. The cursor.com/install script just detects os/arch, downloads a +# versioned tarball from +# downloads.cursor.com/lab////agent-cli-package.tar.gz, +# extracts it, and symlinks `agent`/`cursor-agent` into ~/.local/bin. We do that +# ourselves against a PINNED version plus a per-arch sha256 hash. So the build +# runs no unverified remote code. This matches how we pin the base image and npm +# packages by digest (issue #1451). The download is fail-closed: if the hash +# does not match, the build aborts. +# +# To bump: set CURSOR_VERSION and both CURSOR_SHA256_* in devcontainer.json +# build.args. Get each arch's hash with: +# curl -fSL https://downloads.cursor.com/lab//linux//agent-cli-package.tar.gz | sha256sum +# +# TARGETARCH is the per-platform build arg that BuildKit sets automatically. It +# must be (re)declared in this stage to be visible. When the build is a +# non-BuildKit `docker build`, TARGETARCH is unset, so we fall back to `dpkg +# --print-architecture`. +ARG TARGETARCH +RUN set -eux; \ + arch="${TARGETARCH:-$(dpkg --print-architecture)}"; \ + case "$arch" in \ + amd64) cursor_arch=x64; cursor_sha="${CURSOR_SHA256_X64}";; \ + arm64) cursor_arch=arm64; cursor_sha="${CURSOR_SHA256_ARM64}";; \ + *) echo "unsupported architecture for Cursor: $arch" >&2; exit 1;; \ + esac; \ + url="https://downloads.cursor.com/lab/${CURSOR_VERSION}/linux/${cursor_arch}/agent-cli-package.tar.gz"; \ + curl -fSL --retry 3 --max-time 120 -o /tmp/cursor.tgz "$url"; \ + echo "${cursor_sha} /tmp/cursor.tgz" | sha256sum -c -; \ + dir="/home/${USERNAME}/.local/share/cursor-agent/versions/${CURSOR_VERSION}"; \ + install -d "$dir" "/home/${USERNAME}/.local/bin"; \ + tar --strip-components=1 -xzf /tmp/cursor.tgz -C "$dir"; \ + test -x "$dir/cursor-agent"; \ + ln -sf "$dir/cursor-agent" "/home/${USERNAME}/.local/bin/agent"; \ + ln -sf "$dir/cursor-agent" "/home/${USERNAME}/.local/bin/cursor-agent"; \ + rm -f /tmp/cursor.tgz + +# Install Bun via the official remote installer, pinned by version. The first +# positional arg to `bash` is the release tag (`bun-vX.Y.Z`), so a specific +# version is fetched even though the install script itself is downloaded fresh +# on every build. NOTE: this is the ONE remote script we run unverified in +# this image — Cursor and the base image are pinned by sha256/digest. Hardening +# path: switch to a pinned tarball + per-arch sha256 in the Cursor style +# (artifacts at github.com/oven-sh/bun/releases). `BUN_INSTALL` is set in ENV +# above so the binary lands at a known path regardless of any rc-file edits +# the installer makes (which we ignore — we own the shell rc files). +RUN set -eux; \ + curl -fsSL --retry 3 --max-time 120 https://bun.sh/install \ + | bash -s "bun-v${BUN_VERSION}"; \ + test -x "${BUN_INSTALL}/bin/bun" + +# Put ~/.local/bin and Bun's bin dir on PATH for interactive shells and +# lifecycle scripts. ~/.local/bin is where Cursor's installer drops the `agent` +# and `cursor-agent` symlinks; ${BUN_INSTALL}/bin is where the Bun installer +# drops `bun` / `bunx`. +ENV PATH=/home/${USERNAME}/.local/bin:${BUN_INSTALL}/bin:${PATH} diff --git a/.devcontainer/README.md b/.devcontainer/README.md new file mode 100644 index 0000000000..8817c1773e --- /dev/null +++ b/.devcontainer/README.md @@ -0,0 +1,364 @@ +# GitNexus Devcontainer + +A cross-platform Dev Container that pre-installs Claude Code, OpenAI Codex CLI, Cursor CLI, and Bun alongside the GitNexus native build chain. Supported hosts: **macOS, Linux, Windows 11 (native), and Windows 11 via WSL2.** Windows-native needs a **one-time `HOME` env var setup** — handled automatically by the `initializeCommand` on first run (see [Windows 11 setup](#windows-11-setup)). + +> ### ⚠️ Read this before using it on a work machine +> +> This devcontainer **does not write to your host AI-CLI config.** Your skills, agents, commands, plugins, memory, prompts, and rules are **copied once** from a read-only host stage into a per-container volume on first create; the container edits its own copy and can never write back. So a compromised workspace dependency running in the container **cannot** drop a malicious agent, command, skill, or plugin onto your host for your next host CLI session to load — the write-through vector earlier versions had is closed. Your **credentials** (Claude/Codex/Cursor logins, plus `gh`) likewise stay in per-container volumes and are never written back, and `~/.ssh`, `~/.aws`, `~/.azure`, and `~/.docker` are mounted **read-only**. +> +> What is **still** exposed: the read-only host stages (`/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`) and the read-only credential mounts are all **readable** inside the container. A compromised dependency can therefore READ your host CLI config, memory, SSH/cloud credentials, and GitHub token — and there is **no egress firewall yet**, so it has the network to exfiltrate what it reads. Read-only protects you from tampering and write-back, not from disclosure. +> +> The trade-off of the copy model: host and container config **diverge after first create.** A skill or plugin you add on the host later won't appear in the container until you wipe the config volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). Edits you make inside the container persist across rebuilds but never reach the host. + +## Quick start + +1. Install [Docker Desktop](https://docs.docker.com/desktop/) (Windows/macOS) or Docker Engine (Linux). +2. Install [VS Code](https://code.visualstudio.com/) with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). +3. Install [Node.js](https://nodejs.org/) on the **host** (Node 18+). This is the only host-side toolchain dependency beyond Docker and VS Code — the devcontainer's `initializeCommand` runs `node .devcontainer/ensure-host-config-dirs.cjs` to set up the bind-mount source directories before container create. If you already use Claude Code or another Node-based CLI on the host, you're already set. +4. Open the repo in VS Code → Command Palette → **Dev Containers: Reopen in Container**. +5. Wait for the first build (~3–6 minutes) and `postCreateCommand` to finish installing workspace dependencies. +6. Authenticate the three CLIs once — see [First-time CLI authentication](#first-time-cli-authentication) below. + +## Windows 11 setup + +### Windows-native (one-time setup, then "just works") + +The host bind mounts use `${localEnv:HOME}/.claude` (and `.codex`, `.cursor`, `.ssh`, `.config/git`, `.config/gh`, `.gitconfig`). VS Code resolves `${localEnv:HOME}` by reading its own process env, and Windows doesn't set `HOME` by default — it uses `USERPROFILE`. So the bind mounts can't resolve until you tell Windows to also expose your profile as `HOME`. + +The `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`) handles this automatically: + +1. **First time you Reopen in Container**, the script detects the missing `HOME`, runs `setx HOME "%USERPROFILE%"` (which writes to your user-level Windows env — no admin needed), prints a one-time setup banner, and exits. +2. **Close all VS Code windows** (File → Exit) and reopen. VS Code picks up the new `HOME` at startup. +3. **Reopen in Container again.** The script now sees `HOME=C:\Users\`, skips the setup block, creates the bind-mount source dirs, and Docker brings the container up. + +Subsequent rebuilds work normally with no extra steps. The `HOME` env var is set persistently in your Windows user environment, so it'll be there for every future VS Code session (and any other tool that wants `HOME`). + +If you'd rather set it manually before opening the container: + +```powershell +setx HOME "%USERPROFILE%" +# Close & reopen VS Code +``` + +### Known trade-offs of Windows-native vs WSL2 + +Windows-native works, but Docker Desktop's Windows bind-mount layer has rough edges that WSL2 avoids: + +- **File watchers can miss events.** Vite / jest `--watch` running inside the container watching workspace files mounted from `D:\...` may miss changes — chokidar polling (`CHOKIDAR_USEPOLLING=true`) is the usual workaround. +- **`npm install` is 3-5× slower** through the Windows-to-Linux bind-mount translation than on a WSL2-native filesystem. +- **Permission edge cases.** The husky `.husky/_/h` EPERM class we hit earlier in this PR is specific to Windows-side bind mounts changing UID ownership between container runs. `post-create.sh` clears the cache defensively to keep this from being fatal, but it's still a real source of friction. + +If you hit any of those and want to migrate to WSL2 later, the steps are below. + +### WSL2 (faster, fewer edge cases) + +To clone and open the repo inside WSL2: + +```bash +# 1. Install WSL2 and a Linux distro if you haven't already. +wsl --install -d Ubuntu + +# 2. Enter WSL. +wsl + +# 3. Clone the repo inside your WSL2 home directory. +cd ~ +git clone https://github.com/abhigyanpatwari/GitNexus.git +cd GitNexus + +# 4. Launch VS Code from inside WSL — this opens VS Code attached to the WSL2 +# filesystem, so `${localEnv:HOME}` resolves to the WSL user's home and +# subsequent "Reopen in Container" uses the WSL2-side path. +code . +``` + +Then run **Dev Containers: Reopen in Container**. The workspace will be bind-mounted from `\\wsl$\Ubuntu\home\\GitNexus`, which is fast and gives reliable file-system events. **Make sure Docker Desktop's WSL integration is enabled** for your distro: Docker Desktop → Settings → Resources → WSL Integration → toggle on the distro you cloned into. + +## macOS + +Open the repo folder in VS Code → **Reopen in Container**. The image is multi-arch; on Apple Silicon you'll pull the `linux/arm64` variant automatically. + +## Linux + +Same as macOS — open in VS Code and reopen in container. `updateRemoteUserUID: true` (default) shifts the container's `node` user UID/GID to match your host user, so bind-mounted files stay writable without extra setup. + +## How CLI state flows from your host + +### AI CLIs (Claude Code, Codex, Cursor): copy-once from a read-only host stage + per-container credentials + +The three AI CLIs use a **copy-from-read-only-stage topology**: the host's `~/.` folders (and `~/.claude-mem`) are mounted **read-only** at `/host/.`, and `post-create.sh` copies out of them into per-container named volumes. Credentials, identity, and single config files are copied on **every** create; the shareable subdirs (plugins, skills, agents, memory, commands, prompts, rules) are copied **once** on first create and then owned by the container. Nothing is bind-mounted read-write into the host's CLI config, so the container can never modify your host setup. Session sub-paths overlay the config volume via their own named volumes (Docker mount precedence — more specific path wins). + +| Mount | Source | Target | Mode | Purpose | +| -------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------- | +| Container Claude config dir | _named volume_ `claude-config-${devcontainerId}` | `/home/node/.claude` | rw | Per-container credentials + identity | +| Container Codex config dir | _named volume_ `codex-config-${devcontainerId}` | `/home/node/.codex` | rw | Per-container credentials | +| Container Cursor config dir | _named volume_ `cursor-config-${devcontainerId}` | `/home/node/.cursor` | rw | Per-container credentials | +| Container gh config dir | _named volume_ `gh-config-${devcontainerId}` | `/home/node/.config/gh` | rw | Per-container `gh` auth (`hosts.yml`/`config.yml`) seeded from host stage; in-container login persists | +| **Claude sessions** (overlay on the config volume) | _named volume_ `…-claude-sessions-${devcontainerId}` | `/home/node/.claude/projects` | rw | `--resume` transcripts; survives the `-config` volume wipe — see [Session resume](#session-resume-across-container-recreation) | +| **Codex sessions** | _named volume_ `…-codex-sessions-${devcontainerId}` | `/home/node/.codex/sessions` | rw | `codex resume` rollouts; SQLite index backfills on recreation | +| **Cursor sessions** | _named volumes_ `…-cursor-sessions-${devcontainerId}`, `…-cursor-projects-${devcontainerId}` | `/home/node/.cursor/chats`, `/home/node/.cursor/projects` | rw | `cursor-agent resume` store (best-effort — layout reverse-engineered) | +| **claude-mem store** | _named volume_ `claude-mem-${devcontainerId}` | `/home/node/.claude-mem` | rw | claude-mem's SQLite DB + Chroma vector store; **seeded once** from `/host/.claude-mem`, then container-private — see note below | +| Host Claude state, read-only stage | `$HOME/.claude` | `/host/.claude` | **read-only** | `post-create.sh` reads credentials + identity from here on container-create | +| claude-mem store, read-only stage | `$HOME/.claude-mem` | `/host/.claude-mem` | **read-only** | `post-create.sh` seeds the claude-mem volume from here on first create | +| Host Codex state, read-only stage | `$HOME/.codex` | `/host/.codex` | **read-only** | Same purpose for Codex | +| Host Cursor state, read-only stage | `$HOME/.cursor` | `/host/.cursor` | **read-only** | Same purpose for Cursor | +| **Claude shareable subdirs** | _seeded into the config volume from_ `$HOME/.claude/{plugins/marketplaces,plugins/cache,skills,agents,memory,commands}` | same under `/home/node/.claude/` | n/a (copy) | **Seed-once** copy from the read-only stage; container owns its copy after | +| **Codex shareable subdirs** | _seeded from_ `$HOME/.codex/{plugins,prompts,memories,skills}` | same under `/home/node/.codex/` | n/a (copy) | **Seed-once** copy (whole `plugins/` dir — no path-bearing registry inside it) | +| **Cursor shareable subdirs** | _seeded from_ `$HOME/.cursor/{plugins/marketplaces,plugins/local,rules,commands,agents,skills}` | same under `/home/node/.cursor/` | n/a (copy) | **Seed-once** copy of the Cursor 2.5 plugin/rules/commands surface | + +**What gets seeded once from the host (copy, not bind):** + +- **Claude**: `plugins/marketplaces`, `plugins/cache`, `skills/`, `agents/`, `memory/`, `commands/` +- **Codex**: `plugins/` (whole dir), `prompts/`, `memories/`, `skills/` +- **Cursor**: `plugins/marketplaces`, `plugins/local`, `rules/`, `commands/`, `agents/`, `skills/` + +On the **first** container-create, `post-create.sh` copies each of these out of the read-only `/host/.` stage into the per-container config volume, then writes a `.devcontainer-shareable-seeded` marker. On every later rebuild the marker is present, so the copy is skipped and the container keeps whatever it has accumulated. A plugin/skill/agent you install **inside** the container persists across rebuilds; one you add on the **host** after first create won't appear in the container until you remove the config volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). Nothing here is writable back to the host — `/plugin marketplace add` inside the container installs into the container's own volume copy, not your host `~/./plugins/`. + +**Single config files are copied on container-create, not bind-mounted** — on Docker Desktop Windows a single-file bind is 9p while the named volume is ext4, and atomic config writes (`tmp` → rename onto target) trip EXDEV (this is what caused Codex's `config/batchWrite failed in TUI`). So these are synced from host on rebuild and the container rewrites its own copy until the next rebuild: `settings.json` + `$HOME/.claude.json` (Claude), `config.toml` (Codex), `cli-config.json` + `mcp.json` (Cursor). `hooks.json` (Cursor) is deliberately **not** synced — Cursor hooks execute shell commands, so sharing them would widen the supply-chain attack surface; add it yourself if you want it. + +**Plugin registry files with absolute paths are translated, not copied verbatim** — Claude's `known_marketplaces.json` / `installed_plugins.json` / `plugin-catalog-cache.json` and Cursor's `installed_plugins.json` bake in `C:\Users\…` (Windows) or `/Users/…` (macOS) install paths. `post-create.sh` rewrites those to `/home/node/./plugins/…` and writes the result into the named volume, so plugins resolve inside Linux instead of failing with `cache-miss`. This translation is **also seed-once per CLI** — it runs only for a CLI being seeded that create (`translate-plugin-registries.cjs claude cursor`), so it stays consistent with the seed-once `cache/` copy and won't overwrite a plugin you installed inside the container on a later rebuild. Codex needs no translation — its enablement registry is `config.toml` (git URLs + logical keys, no filesystem paths), so its whole `plugins/` dir is copied as-is. + +**What stays per-container (in the named volume) and is synced from host on container-create:** + +- `.credentials.json` (Claude OAuth tokens), `auth.json` (Codex), `cli-config.json` (Cursor) — credentials +- `~/.claude/.claude.json` (Claude's identity-only file: `userID`, `oauthAccount`, migration tracking) — kept per-container so logging in via container doesn't overwrite host's stored identity + +`post-create.sh` runs on every container-create, copies host's credentials into the volume if present, then container manages refresh from there. Sync is "always overwrite if host has the file, otherwise leave container alone". So: + +- Host has credentials → container starts logged in. +- Host has no credentials → `claude login` / `codex login --device-auth` / `cursor-agent login` inside container; credentials stay in the named volume across rebuilds (volume is keyed by `${devcontainerId}`, stable for the workspace path). +- `claude logout` inside container clears volume credentials only; host is untouched. + +**Why CLAUDE_CONFIG_DIR is intentionally NOT set:** Claude's default `~/.claude` matches the named-volume mount target, so the env var added no behavior — but setting it changed which file Claude reads `hasCompletedOnboarding` from. With it set, Claude reads `$CLAUDE_CONFIG_DIR/.claude.json` (the small identity-only file) and re-onboards every container; without it, Claude reads `$HOME/.claude.json` (copied from the read-only `/host/.claude.json` stage on container-create via `seed-claude-config.cjs`, with `hasCompletedOnboarding: true`). + +**Host CLI config is protected from write-through.** The shareable dirs are copied out of a **read-only** stage into the container's own volume, so a compromised npm package in the workspace dep tree — running inside the container — **cannot** write a malicious agent, command, skill, or plugin back to `~/.claude/`, `~/.codex/`, or `~/.cursor/` on the host. The earlier design bind-mounted these read-write and accepted that write-through as the cost of live sync; this design closes it. An even earlier alternative (read-only stage + symlinks) made `/plugin marketplace add` inside the container fail with EROFS; copying into a writable volume avoids that, because the container writes to its own copy rather than a read-only mount. What a compromised dependency can still do is **read** the read-only host stages (`/host/.`, `/host/.claude-mem`) and the read-only credential mounts and exfiltrate them — there is [no egress firewall yet](#whats-not-included-yet). The cost of the copy model is **divergence**: host edits made after first create don't reach the container until you wipe the config volume and rebuild. + +**Refresh-token divergence between rebuilds.** Container's credentials match host's at container-create time; after that, container manages its own refresh until the next rebuild. Anthropic rotates refresh tokens on every use, so an unattended container that hasn't talked to the API in weeks can hit a silent 401 if the host has refreshed since. Re-run `claude login` inside the container, or rebuild, to recover. + +**claude-mem is seeded once, then container-private.** The [claude-mem](https://github.com/thedotmack/claude-mem) store (`$HOME/.claude-mem` — a multi-GB SQLite DB `claude-mem.db` + `-wal`/`-shm`, plus a Chroma vector store `chroma/chroma.sqlite3` and its HNSW index binaries) is the one shareable-looking folder that is **deliberately not a host bind**, for the same SQLite reason as sessions below: a multi-GB WAL database over the 9p/virtiofs bind risks unreliable `fcntl` locking and corruption — sharply so if claude-mem ran on the host and in the container against the same DB at once. So it gets its own per-container named volume (`claude-mem-${devcontainerId}`), and `post-create.sh` **seeds it once** from the read-only `/host/.claude-mem` stage _only when the volume has no DB yet_. The first container-create copies the host's store in (a one-time copy, possibly several GB); every later rebuild keeps whatever the container accumulated and skips the copy. The container's memory and the host's **diverge from that seed point** — writes do not flow back — which is the price of keeping SQLite off a shared bind. To re-seed from the host's current store, remove the volume (`docker volume rm claude-mem-`) and rebuild. `ensure-host-config-dirs.cjs` creates an empty `~/.claude-mem` on hosts that never installed claude-mem, so the read-only stage bind always resolves; the seed then finds no DB and the container simply starts with empty memory. + +### Session resume across container recreation + +`claude --resume`, `codex resume`, and `cursor-agent resume` all read **local** transcript files. Those live _inside_ each CLI's config dir, which is a per-container named volume — so they already survive an ordinary **Rebuild Container**. What they did _not_ survive were the very things this README tells you to do: `docker volume rm -config-${devcontainerId}` to force a re-login or clear an `EACCES`, a `${devcontainerId}` change, or a full delete-and-recreate. Each of those drops the config volume and takes your session history with it. + +So the resume/transcript directories get their **own** named volumes (mount group 6 in `devcontainer.json`), keyed like the `node_modules` volumes (`${localWorkspaceFolderBasename}-…-${devcontainerId}`) and mounted _over_ the config volume at the session sub-paths: + +| Resume command | Persisted volume → target | What's stored | +| -------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `claude --resume` / `--continue` | `…-claude-sessions-…` → `~/.claude/projects` | `/.jsonl` transcripts + `sessions-index.json`. Container cwd is always `/workspace`, so only that slice is stored. Pure JSONL/JSON — no SQLite. | +| `codex resume` / `resume --last` | `…-codex-sessions-…` → `~/.codex/sessions` | `YYYY/MM/DD/rollout-*.jsonl`. The `state_5.sqlite` thread index stays on the config volume (a single WAL file we don't split out); when it's absent after a recreation, Codex rebuilds it from these rollouts on the next start (a one-time backfill). | +| `cursor-agent resume` / `ls` | `…-cursor-sessions-…` → `~/.cursor/chats`; `…-cursor-projects-…` → `~/.cursor/projects` | `chats/{hash}/{uuid}/store.db` (one SQLite db per session, each in its own dir) + `projects/.../agent-transcripts`. cursor-agent's layout is reverse-engineered, so treat this as best-effort. | + +Because these are **separate** volumes from `-config-${devcontainerId}`, the re-login fix (`docker volume rm claude-config-…`) no longer destroys your sessions — that was the point. + +**Survives:** Rebuild Container, Rebuild Without Cache, a full delete-and-recreate of the container, and the `docker volume rm -config-…` re-login / `EACCES` fix. + +**Does _not_ survive** (same durability tier as the `node_modules` volumes): `docker volume prune`, a `${devcontainerId}` change (moving the checkout to a new path, or switching between Windows-native and WSL2), or moving to a new machine. To deliberately wipe sessions, remove the session volumes too — see [Rebuild / reset](#rebuild--reset). Two checkouts with the **same folder name** on one host would share session volumes only if they also share a `${devcontainerId}`; they don't, so they stay separate. + +**First rebuild after adopting this, one-time:** if a container created _before_ these volumes existed already had sessions on the config volume (`~/.claude/projects`, `~/.codex/sessions`, …), the new empty session volume mounts _over_ that sub-path and **masks** the old content — same Docker-precedence shadowing described for plugins above. The old sessions are hidden, not deleted. To carry them forward once, copy them out of the config volume into the session volume; or just start fresh — new sessions land on the session volume from then on. + +**Why sessions are container-private and not even seeded from the host.** The shareable config dirs are _seeded once_ from the host (you want your skills/agents/plugins in the container). Sessions are deliberately _not_ seeded and never touch the host, because a transcript can contain anything you pasted or the agent read — API keys, file contents, connection strings. Binding or copying them to/from the host would (a) spill that to host disk, (b) add a write-through surface a compromised dependency can reach (there's still [no egress firewall](#whats-not-included-yet)), and (c) leak _every other project's_ transcripts into the container (Codex `sessions/` and Cursor `chats/` aren't project-scoped). Container-private volumes avoid all three while still surviving recreation. And Claude/Codex transcripts embed the container cwd (`/workspace`), so even if you _did_ bind them to the host, the host CLI wouldn't natively `--resume` them — its encoded-cwd folder differs. + +**Opt in to host-shared sessions anyway.** If you want transcripts visible/portable on the host and accept the trade-offs above, uncomment the host-bind block in `devcontainer.json` (just below the group-6 volumes) and add the matching source dirs to `ensure-host-config-dirs.cjs`'s `DIRS` so Docker can resolve the binds. That block scopes Claude to `/workspace`'s encoded subdir to limit the cross-project leak; the Codex and Cursor stores can't be scoped that way, so they expose every project's transcripts. + +### Other host bind mounts + +| Container path | Host source | Mode | Why | +| --------------- | ------------------- | ------------- | -------------------------------------------------------------------------------------- | +| `~/.config/git` | `$HOME/.config/git` | **read-only** | XDG-style git config / ignore / attributes | +| `~/.ssh` | `$HOME/.ssh` | **read-only** | SSH commit signing + git push over SSH | +| `~/.config/gh` | `$HOME/.config/gh` | **copy → volume** | `gh` CLI auth (PR/issue create, checks) — seeded from your host login on create into a per-container volume; in-container `gh auth login` persists across rebuilds and never writes back to the host | +| `~/.docker` | `$HOME/.docker` | **read-only** | Container registry auth + buildx config (inert until you add Docker CLI via a Feature) | +| `~/.aws` | `$HOME/.aws` | **read-only** | AWS CLI / SDK credentials (forward-compat — empty by default) | +| `~/.azure` | `$HOME/.azure` | **read-only** | Azure CLI credentials (forward-compat — empty by default) | + +**Why `ssh`/`aws`/`azure`/`docker` are read-only, and why `gh` is copied into a volume:** `ssh`/`aws`/`azure` are consumed read-only by their clients (the SSH client and the AWS/Azure SDKs only read their credential files), so a one-way mount loses nothing. `docker` _can_ write its own state (`docker login` / buildx write `config.json`), but a read-write host bind would let a compromised in-container dependency rewrite your host `~/.docker/config.json` (point a `credHelper` at an attacker-controlled binary) — a credential-takeover vector. The common case is _reading_ an existing host login, so `docker` stays **read-only**: registry pulls/pushes using your host creds work, only a `docker login` inside the container won't persist back. `gh` used to be read-only for the same reason, but that meant an in-container `gh auth login` had nowhere to write and silently failed. So `gh` now uses the **copy-into-volume** model (the same one the AI-CLI credentials use): the host `~/.config/gh` is a read-only _stage_ at `/host/.config/gh`, and `post-create.sh` copies `hosts.yml`/`config.yml` out of it into the per-container `gh-config` volume on create. The container gets a **writable** copy — `gh auth login` / `gh auth refresh` inside the container now work and persist across rebuilds — while the read-only stage guarantees nothing is ever written back to the host's token. If you want `docker` to behave the same way, give it the same treatment (a `/host/.docker` stage + a docker-config volume + a copy step in `post-create.sh`). + +`~/.gitconfig` is **not** bind-mounted — VS Code's Dev Containers extension auto-copies the host's gitconfig into the container at attach time (this is built-in behavior, not something this devcontainer configures). The bind-mount approach conflicts with that auto-copy mechanism, so we let VS Code own it. The end result is the same: your host's `user.name` / `user.email` are available inside the container. + +If a host source dir doesn't exist when the container is first created, the `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`) creates it empty — so the bind mount always has a valid source. + +### Per-CLI quirks worth knowing + +- **Claude Code on macOS** stores credentials in the system Keychain, not in `~/.claude/.credentials.json`. The sync silently no-ops; run `claude login` inside the container once and the named volume persists it. +- **Codex on macOS / Linux with `cli_auth_credentials_store = "keyring"`** stores auth in the OS keyring (Keychain / Secret Service), so `~/.codex/auth.json` may not exist on host. Same fallback: `codex login --device-auth` inside the container. +- **Cursor CLI inside containers** has [known upstream auth issues](https://forum.cursor.com/t/cursor-agent-authentication-issue-inside-docker/143995) — even with a correctly-synced `cli-config.json`, you may need to re-run `cursor-agent login` inside the container. +- **Stale named volumes from old rebuilds can carry forward.** If you delete and re-create the same workspace, or if a prior container left interim state with a different `userID`, deleting the named volumes before rebuild guarantees a clean sync: `docker volume rm claude-config-${devcontainerId} codex-config-${devcontainerId} cursor-config-${devcontainerId}` (look them up with `docker volume ls | grep -config-`). +- **User-scope MCP servers with absolute host paths won't resolve in-container.** `~/.claude.json` (Claude), `~/.codex/config.toml` (Codex), and `~/.cursor/mcp.json` (Cursor) are copied from host on container-create, so their user-scope `mcpServers` entries come along. But an entry whose `command` is an absolute host path (`C:\tools\foo.exe`, `/usr/local/bin/foo`) points at a binary that doesn't exist in the container — that server silently fails to launch. Only registry/`npx`-based servers (like this repo's `.mcp.json`, which uses `npx -y gitnexus@latest mcp`) and remote/URL servers work unchanged. The path-translation pass only rewrites `*/.​/plugins/*` registry paths, **not** arbitrary `mcpServers` command paths (there's no correct container target for a host-local binary). Install such MCP servers inside the container, or use `npx`/remote ones. +- **Host config is seeded once per devcontainer, then diverges — this now applies to everything.** A `mcpServers` entry, setting, plugin, skill, agent, or command you add **on the host after** the container was created is not visible in the container until you remove the config volume and rebuild. Single config files (`mcpServers`, `settings.json`, …) are copy-on-create; the shareable dirs (plugins/skills/agents/memory/commands/prompts/rules) are copy-on-**first**-create (they persist across ordinary rebuilds and aren't even re-copied). Both diverge from the host after their copy. To pull host-side changes in, wipe the relevant volume and rebuild (see [§ Rebuild / reset](#rebuild--reset)). +- **Plugins/skills/agents installed in-container persist; they do not reach the host.** A `/plugin marketplace add` (or `codex plugin add`, or a new skill/agent) inside the container writes to the container's own config volume and survives ordinary rebuilds. It never appears on the host — the host dirs are read-only sources, not bind targets. To get a plugin onto the host, install it on the host (then wipe + rebuild to seed it into the container). +- **No cross-checkout plugin contention.** Because each container copies plugins into its own per-`${devcontainerId}` volume rather than sharing one host bind source, two containers (or checkouts) installing plugins at the same time no longer interleave git clones/extractions against a shared host dir. Each writes only its own copy. + +### What you still don't have inside the container + +These are commonly-needed CLIs that aren't installed by default — adding them would be follow-up work, not in this PR's scope: + +- **Docker CLI** (for `docker push` / `docker build` from inside the container). Add via `ghcr.io/devcontainers/features/docker-outside-of-docker:1` to the `features` block — `~/.docker/` is already mounted **read-only**, so your host `docker login` state works immediately for pulls/pushes; an in-container `docker login` won't persist to the host (drop `,readonly` on that mount if you need it to). +- **AWS CLI / Azure CLI / gcloud / kubectl** — same pattern: add the matching Feature, the host config dirs already flow through. +- **Private npm registry auth** (`~/.npmrc`) — you don't have a global one on this host. If you ever start using private packages, add `source=${localEnv:HOME}/.npmrc,target=/home/node/.npmrc,type=bind,readonly` to the mounts. + +That means: + +- **Authentication is shared.** If you're already logged in on the host (`claude login`, `codex login`, `cursor-agent login`, `gh auth login`), you're already logged in inside the container. No second login step. +- **Plugins, skills, agents, memory, and commands are seeded from the host once, then container-private.** On first create the container copies your host's plugins/skills/agents/memory/commands (and Codex prompts/memories, Cursor rules) into its own volume. After that they're independent: install or edit inside the container and it stays in the container (persists across rebuilds); add a plugin or agent on the host and the container won't see it until you wipe the config volume and rebuild. Nothing the container does reaches the host. (`settings.json` and the user-scope `~/.claude.json` are copy-on-create the same way; `~/.claude/projects/` is container-local by design.) +- **Git identity comes from the host.** Commits from inside the container use your host's `user.name` / `user.email` — VS Code's Dev Containers extension auto-copies your `~/.gitconfig` into the container at attach time. Any XDG-style config under `~/.config/git/` flows through via the read-only bind mount. To change git identity, edit `~/.gitconfig` on the host (container-side `git config --global` writes to a container-local file that's discarded on rebuild). +- **SSH keys flow through (read-only).** Push over SSH remotes and SSH commit signing work inside the container using your host keys. The mount is read-only so container code can't exfiltrate or modify private keys — agent-perspective, this means you get git operations but the keys stay vendor-side. +- **`gh` auth is shared, and in-container logins persist.** If you're logged in on the host, `gh pr create`, `gh pr checks`, `gh issue create` work inside the container without re-authenticating. If you're not, run `gh auth login` inside the container once — because `gh` config lives in a writable per-container volume (seeded from the host stage), that login persists across rebuilds and never touches the host's token. +- **No per-workspace duplication.** All your devcontainers across all your projects see the same host CLI state, just like all your host shells do. + +The bind mount source directories are guaranteed to exist by the `initializeCommand` (`node .devcontainer/ensure-host-config-dirs.cjs`), which runs on the host before container create. It's a Node script (not a shell one-liner) so the same command works on Windows `cmd.exe` and POSIX shells. It creates the top-level bind-mount source dirs — `~/.claude`, `~/.codex`, `~/.cursor`, `~/.claude-mem`, plus `~/.ssh`, `~/.docker`, `~/.aws`, `~/.azure`, `~/.config/{gh,git}`. It deliberately does **not** pre-create the shareable subdirs (skills/agents/plugins/…): those are no longer bind sources (they're copied out of the whole-`~/.` read-only stage), and pre-creating empty ones would needlessly write into the host of someone who never used that CLI. + +### Trust boundary, concretely + +Host and container share a single trust boundary by design — fine for personal-dev, but the consequence is concrete. Any malicious npm package or `postinstall` script in the workspace dep tree, running inside the container, has direct **read** access to: + +- **Host AI CLI state** — the read-only stage at `/host/.claude`, `/host/.codex`, `/host/.cursor`, `/host/.claude-mem`, which exposes your **entire** host `~/.` tree (credentials, identity, AND the shareable skills/agents/plugins/memory/commands) for _reading_. The container copies what it needs out of this stage; a compromised dep can read all of it. It is read-only, so none of it can be written back +- The **container's own credential snapshots** at `/home/node/.claude/.credentials.json` etc. (copied from host on container-create) +- `~/.claude/memory/` / per-project memory (which may contain user-stored secrets if you've used the `/remember` skill) +- The **current container's own session transcripts** (`~/.claude/projects`, `~/.codex/sessions`, `~/.cursor/chats`/`projects` — the group-6 volumes), which can hold anything pasted into or read during a session. These are container-private (see one-way note below), so this is read access to _this_ container's sessions only, not the host's or other projects' +- Your **`gh` token** (`~/.config/gh`) +- Your **SSH private keys** (`~/.ssh/`) +- Docker registry tokens in **`~/.docker/config.json`** (if you've `docker login`-ed) +- AWS/Azure CLI credentials if you've populated `~/.aws/` or `~/.azure/` + +It does **not** have write-through to the host's CLI config. The shareable dirs are copied out of the read-only stage into the container's own volume, so a compromised in-container dep **cannot** write into your host `~/.claude/{plugins,agents,skills,commands,memory}/`, `~/.codex/{plugins,prompts,memories,skills}/`, or `~/.cursor/{plugins,rules,commands,agents,skills}/`. The persistence vector earlier versions had — drop a malicious auto-loaded agent/command/skill/rule onto the host, have it run in your next **host** session — is closed: there is no writable path from the container to those host folders. (Cursor's `hooks.json` is still additionally withheld from even the _container's_ copy, because hooks fire without an agent invoking them.) The boundary is now one-way for **all** of the host CLI config, not just credentials. + +**What stays one-way (genuinely protected):** everything. Credentials never flow back to host — `.credentials.json` / `auth.json` / `cli-config.json` live only in the per-container named volumes, and the `/host/.` stage they're copied from is mounted **read-only**, so the snapshot can't be overwritten back. The shareable AI-CLI dirs (skills/agents/plugins/memory/commands/prompts/rules) are now copy-on-create from that same read-only stage, so they have the one-way property too — readable for the copy, never writable back. `~/.ssh`, `~/.config/git`, `~/.aws`, `~/.azure`, and **`~/.docker`** are read-only binds with the same property — a compromised dep can _read_ your registry tokens but cannot _rewrite_ them to hijack your future host auth. **`~/.config/gh`** is now a read-only _stage_ copied into a per-container volume, so it keeps that same one-way property: the container reads it once to seed its own writable copy, and the read-only stage means an in-container `gh auth login` can never overwrite your host token. **Session transcripts** live in per-workspace named volumes (mount group 6) and are never seeded from or written back to the host, and the container can't see any _other_ project's transcripts. The opt-in host-bind block in `devcontainer.json` reverses that for sessions only — enable it only if you accept transcripts on host disk; see [Session resume across container recreation](#session-resume-across-container-recreation). + +**The egress firewall is the key compensating control that is still missing.** It's deferred (see "What's not included (yet)" below), so a compromised package currently has unrestricted outbound network to exfiltrate anything in the read list above. Until it lands, treat that read surface as exposed to any code you run in the container — don't use this devcontainer on a machine whose host credentials you couldn't afford to rotate. The isolated-volume setup below removes host AI-CLI config/credentials from that surface entirely. + +**If a workspace dep is ever found compromised**, rotate credentials at the vendor side — local file deletion is insufficient because tokens may have already left: + +- Anthropic: [console.anthropic.com → Settings → Keys](https://console.anthropic.com/settings/keys), revoke the OAuth session under Account +- OpenAI / Codex: [platform.openai.com/api-keys](https://platform.openai.com/api-keys), revoke session under Profile +- Cursor: dashboard → Integrations, rotate API key + revoke CLI session +- GitHub: `gh auth refresh` or revoke the token at github.com/settings/tokens + +For high-trust enterprise environments where the container should not even be able to **read** host CLI state, remove the three read-only stage binds (`/host/.claude`, `/host/.codex`, `/host/.cursor`) — plus `/host/.claude-mem` and `/host/.claude.json` — from `.devcontainer/devcontainer.json`. With no stage to copy from, `post-create.sh`'s seed and credential-sync steps quietly do nothing (their `[ -f ]` / `[ -d ]` guards), and each devcontainer starts with empty, fully isolated config and credentials (Anthropic's reference pattern). You give up seeding your host setup into the container in exchange for removing host config/credentials from the container's read surface entirely; log in inside each container instead. + +## First-time CLI authentication + +Each CLI works either way: + +- **Log in on host first** → the container picks it up automatically on the next rebuild (`sync_from_host` copies the credential file into the named volume during `post-create.sh`). Host stays the source of truth. +- **Log in inside the container** → credentials write to the named volume. They persist across ordinary rebuilds (volume is keyed by `${devcontainerId}`, which is stable for a given workspace folder). The host's credentials are untouched. + +You can mix and match per-CLI. A common setup is "Claude logged in on host, Codex/Cursor logged in inside container". + +### Claude Code + +```bash +claude login +``` + +Opens a browser auth flow. VS Code's port forwarding handles the OAuth callback automatically. After auth, `~/.claude/` is populated and visible from both host and container. The `DISABLE_AUTOUPDATER=1` env var prevents the in-container CLI from auto-updating — rebuild the container to pick up a newer Claude Code. + +### OpenAI Codex CLI + +```bash +codex login --device-auth +``` + +The device-code flow prints a URL and a one-time code. Visit the URL on your host browser, paste the code, and the CLI authenticates without needing a callback listener — this is the most reliable path inside containers. Credentials land in `~/.codex/auth.json` (shared with host). + +`codex login` (browser-callback variant) also works but can be flaky in some headless contexts; prefer `--device-auth`. + +### Cursor CLI + +```bash +cursor-agent login +``` + +Opens a browser auth flow; VS Code's port forwarding handles the callback. Credentials persist in `~/.cursor/cli-config.json` (shared with host). + +Verify any time with `cursor-agent status`. + +## Alternative: API key authentication (CI / headless) + +For non-interactive use (CI runners, automated scripts), all three CLIs accept API keys via env vars: + +| CLI | Env var | Where to get the key | +| ----------- | ------------------- | --------------------------------------------- | +| Claude Code | `ANTHROPIC_API_KEY` | | +| Codex | `OPENAI_API_KEY` | | +| Cursor | `CURSOR_API_KEY` | Cursor dashboard → Integrations | + +These env vars are intentionally **not** injected into the container from the host. `${localEnv:VAR}` resolves an unset host variable to an empty string, and some CLIs (Cursor in particular) treat a set-but-empty key as "use this key" rather than "fall back to stored login" — which would silently break the login flow for everyone who hasn't pre-set the host var. + +To use an API key inside the container, export it in your terminal session: + +```bash +export ANTHROPIC_API_KEY=sk-ant-... +# or OPENAI_API_KEY, or CURSOR_API_KEY +``` + +For persistence across container shells, carry the export via your VS Code [dotfiles repository](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories). VS Code clones the dotfiles repo into the container on attach and runs your install command, so the export lands in `~/.bashrc` / `~/.zshrc` per your own setup — and your API keys stay out of this repo's committed `devcontainer.json`. + +A non-empty API key env var takes precedence over stored login credentials for each CLI. + +## Port forwarding + +| Port | Service | Notes | +| ------ | -------------------------------- | ------------------------------------------------------------------------------------------------------ | +| `5173` | Vite dev server (`gitnexus-web`) | Auto-forwarded with notification | +| `4747` | `gitnexus serve` HTTP API | **Must not be remapped** — `gitnexus-web` hardcodes `http://localhost:4747` as the default backend URL | +| `4173` | Static web (Vite preview) | Silently forwarded | + +VS Code's Ports panel shows forwarded ports once their listener starts. + +## Known gotchas + +- **LadybugDB integration tests may fail in containers** (file-locking, `AGENTS.md` § Testing). Default to `npm run test:unit` inside the container; run integration tests on the host. Tracking issue: documented as a known limitation. +- **Single-writer LadybugDB constraint** (`GUARDRAILS.md` § LadybugDB lock). Don't run `gitnexus analyze` on the host and inside the container against the same `.gitnexus/` directory simultaneously — the second writer will get `database busy`. +- **Native grammar builds add ~30s to first install.** Tree-sitter Dart/Proto/Swift grammars build during `gitnexus`'s `postinstall`. To skip them (loses parsing for those three languages), set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` in your shell or add it to `remoteEnv` and rebuild. +- **`tree-sitter-kotlin` warnings on install** are expected (per `AGENTS.md`). Ignore them. +- **`.mcp.json` works inside the container**: `npx -y gitnexus@latest mcp` resolves cleanly because npm registry is reachable and the workspace bind mount exposes the same `.mcp.json` the host sees. +- **Husky pre-commit fires inside the container** without extra setup. The root `npm install` (run automatically in `postCreateCommand`) installs the hook via `package.json` `prepare`. + +## Rebuild / reset + +- **Rebuild Container** (Command Palette) — re-runs the Dockerfile build and `postCreateCommand` against the existing named volumes (auth, history, **and sessions** persist). +- **Rebuild Container Without Cache** — fresh image layers, same volumes. +- **To force a re-login / clear an `EACCES`** — remove the per-container _config_ volumes and rebuild. As of the session-volume change this **no longer drops your `--resume` history** (sessions are on separate volumes — see [Session resume](#session-resume-across-container-recreation)): + ```bash + docker volume ls | grep -- -config- # the credential / identity volumes + docker volume rm claude-config- codex-config- cursor-config- gh-config- + ``` + ⚠️ Since the shareable dirs are now seeded into the config volume (not bind-mounted), wiping `-config` **also discards any plugin/skill/agent/command you installed _inside_ the container** and re-seeds those dirs from the host on the next rebuild. That is the intended way to pull host-side config changes in, but if you have in-container-only plugins you want to keep, reinstall them after the rebuild (or install them on the host first so the re-seed brings them along). +- **To also wipe session history** (a true clean slate) — remove the session volumes too (`` is your workspace folder name): + ```bash + docker volume ls | grep -E -- '-(sessions|cursor-projects)-' # the group-6 volumes + docker volume rm -claude-sessions- -codex-sessions- \ + -cursor-sessions- -cursor-projects- + ``` + Then rebuild. +- **To re-seed claude-mem from the host** (the container's memory has diverged and you want the host's current store back) — remove the claude-mem volume and rebuild; `post-create.sh` copies the host store in again on the next create: + ```bash + docker volume rm claude-mem- + ``` + +## Bumping CLI versions + +Bump the version pins in `.devcontainer/devcontainer.json` `build.args` and rebuild — all three are real, fail-loud pins. Claude Code installs via `npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}` and Codex via `npm install -g @openai/codex@${CODEX_VERSION}`. **Cursor is pinned too:** bump `CURSOR_VERSION` **and** both `CURSOR_SHA256_X64` / `CURSOR_SHA256_ARM64` together — the Dockerfile downloads the pinned `downloads.cursor.com/lab//linux//agent-cli-package.tar.gz` artifact directly (no remote install script) and fails the build on a sha256 mismatch. Re-hash each arch with `curl -fSL | sha256sum`. To stop Cursor from auto-updating in the running container, don't call `cursor-agent update`. + +## What's not included (yet) + +- **Egress firewall — the most important hardening still outstanding.** The original plan included an opt-in iptables/ipset firewall adapted from Anthropic's reference devcontainer. It was deferred to a follow-up PR — `runArgs` is static in `devcontainer.json`, so toggling NET_ADMIN/NET_RAW capabilities cleanly requires either a separate `devcontainer-firewall.json` profile or an `initializeCommand`-generated overlay. Until it lands, the read surface in [§ Trust boundary](#trust-boundary-concretely) has no network containment — anything readable can be exfiltrated. Track at the project's issue tracker if you need this. +- **Codespaces tuning.** The current config works in Codespaces incidentally (no privileged capabilities, no host-mount assumptions), but isn't actively tested there. +- **Playwright e2e support.** `gitnexus-web`'s `npm run test:e2e` needs Chromium libs that the base image doesn't ship. Use the host for e2e until a Playwright layer is added. + +## Troubleshooting + +| Symptom | Likely cause | Fix | +| -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GitNexus devcontainer one-time Windows setup` banner from `initializeCommand` | First-time Windows-native Reopen-in-Container; `HOME` env var was missing | The script just ran `setx HOME "%USERPROFILE%"` for you. Close ALL VS Code windows (File → Exit) and reopen — see [Windows 11 setup](#windows-11-setup) | +| `bind source path does not exist: /.claude` (or similar) from Docker | Windows-native `HOME` env var is still missing even after one rebuild — `setx` may have failed or VS Code wasn't fully restarted | Run `setx HOME "%USERPROFILE%"` in a Windows shell manually, fully exit VS Code (check Task Manager that no `Code.exe` remains), reopen | +| `EACCES` / `EPERM` writing into `~/.claude`, `~/.codex`, or `~/.cursor` inside the container | Stale state from a previous container with a different effective UID | Move the affected dir aside and let the CLI rebuild it (`mv ~/.claude ~/.claude.bak` and log in again). Long-term: WSL2 setup, which doesn't hit this class of issue | +| `EPERM: operation not permitted, copyfile ... '.husky/_/h'` in `postCreateCommand` | Leftover `.husky/_/` from a previous container run on a Windows-side bind mount | `post-create.sh` already runs `rm -rf .husky/_` defensively. If you hit this on an older config, delete `.husky/_/` on the host and rebuild. Long-term: clone in WSL2 | +| Vite never hot-reloads | Repo cloned on Windows side, not WSL2 | Re-clone inside WSL2 | +| `gitnexus-web` can't reach the backend | `4747` was remapped or backend isn't running | Verify the Ports panel shows `4747` forwarded with no remap; start the backend with `cd gitnexus && npx gitnexus serve` | +| `npm install` fails on tree-sitter-swift / proto / dart | Native build toolchain missing | This shouldn't happen in the devcontainer — verify the apt layer installed `python3 make g++`. If iterating, set `GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1` to skip the vendored grammars | +| Integration tests fail with `database busy` | LadybugDB single-writer constraint | Don't run host-side `gitnexus analyze` while the container is also analyzing the same repo; choose one writer | +| API key env vars not visible inside the container | They are intentionally not auto-propagated from the host (so an empty/stale host var can't silently break `*-login` for everyone else) | `export ANTHROPIC_API_KEY=...` / `OPENAI_API_KEY=...` / `CURSOR_API_KEY=...` inside the container shell, or carry it via your VS Code [dotfiles repo](https://code.visualstudio.com/docs/devcontainers/containers#_personalizing-with-dotfile-repositories) for persistence | +| `git commit` produces commits with empty author | `~/.gitconfig` is missing or empty on the host (VS Code's auto-copy had nothing to copy) | Set `git config --global user.name "Your Name"` and `git config --global user.email "you@example.com"` from the host shell, then rebuild the container | +| `gh: not logged in` inside the container | Not logged in on the host (nothing to seed), or the `gh-config` volume is empty | Just run `gh auth login` **inside the container** — `gh` config lives in a writable per-container volume, so the login persists across rebuilds. (Logging in on the host instead also works: it seeds in on the next container create.) | diff --git a/.devcontainer/devcontainer-lock.json b/.devcontainer/devcontainer-lock.json new file mode 100644 index 0000000000..cdd61126b1 --- /dev/null +++ b/.devcontainer/devcontainer-lock.json @@ -0,0 +1,9 @@ +{ + "features": { + "ghcr.io/devcontainers/features/github-cli:1": { + "version": "1.1.0", + "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671", + "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671" + } + } +} diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000000..a7160c8d58 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,396 @@ +// Devcontainer for GitNexus. It pre-installs Claude Code, the OpenAI Codex +// CLI, and the Cursor CLI, plus the Node.js native build chain. It works on +// macOS, Linux, Windows via WSL2, and Windows native. Windows native needs a +// one-time HOME setup. That setup runs automatically via initializeCommand. +// See .devcontainer/README.md § Windows 11 setup. Open it with the VS Code +// Dev Containers extension. +// +// For first-time setup, auth flows, and troubleshooting, see +// .devcontainer/README.md. +{ + "name": "GitNexus AI CLI Devcontainer", + + "build": { + "dockerfile": "Dockerfile", + "context": ".", + "args": { + "CLAUDE_CODE_VERSION": "2.1.156", + "CODEX_VERSION": "0.134.0", + // Cursor: a pinned version plus one sha256 hash per CPU arch. The + // Dockerfile checks the tarball against the hash at build time, so it + // never runs a remote install script. Bump all three values together. + // Re-hash each arch with: + // curl -fSL https://downloads.cursor.com/lab//linux//agent-cli-package.tar.gz | sha256sum + "CURSOR_VERSION": "2026.05.28-a70ca7c", + "CURSOR_SHA256_X64": "7f8b6a09393e0b84b288cc6952b292fc98d15775f644cc01b0b9aa4f04b268df", + "CURSOR_SHA256_ARM64": "05a0ab361e038729aba25fe7f407531b3e8432912e499d0bffdf1dda0e7833e9", + // Bun: pinned by version. Installed by the official bun.sh/install + // script, which accepts the release tag as its first positional arg + // (`bash -s bun-vX.Y.Z`). UNLIKE Cursor, the install path runs an + // unverified remote script — chosen at request time for simplicity. + // To bump: pick a tag from github.com/oven-sh/bun/releases and update + // this value. + "BUN_VERSION": "1.3.14", + "TZ": "${localEnv:TZ:UTC}" + } + }, + + // Runs on the HOST, not the container, before the container is created. We + // write it as a single string on purpose. The spec treats the single-string + // form as one command that each OS runs its own way. The object form means + // "named parallel tasks", not per-OS dispatch. We run it with Node so the + // same command works in cmd.exe on Windows and in bash/zsh on Linux, macOS, + // and WSL. The script reads `os.homedir()`, which respects $HOME on + // Linux/macOS and %USERPROFILE% on Windows. It then creates the host-side + // bind mount source folders, and it is safe to re-run. Host prerequisite: + // Node on PATH. That is the only host-side tool needed beyond Docker Desktop + // and the VS Code Dev Containers extension. + "initializeCommand": "node .devcontainer/ensure-host-config-dirs.cjs", + + "features": { + "ghcr.io/devcontainers/features/github-cli:1": {} + }, + + "remoteUser": "node", + "updateRemoteUserUID": true, + + "workspaceMount": "source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=delegated", + "workspaceFolder": "/workspace", + + // Mount topology, by group: + // + // 1. AI CLI host config — a READ-ONLY stage at /host/.. On container- + // create, `post-create.sh` COPIES out of it: credentials, identity, and + // single config files (always), plus the shareable subfolders (Claude + // plugins/skills/agents/memory/commands; Codex plugins/prompts/memories/ + // skills; Cursor plugins/rules/commands/agents/skills) ONCE on first create. + // Everything copied lands in the per-container named volume (role 2). It is + // read-only so a container process can NEVER write back to the host — there + // is no read-write bind into the host's CLI config at all. This protects the + // host's on-disk setup: a compromised in-container dependency cannot drop a + // skill, agent, command, or plugin onto the host for the next host session + // to load. The cost is that host and container DIVERGE after the first + // create — host edits don't reach the container until you wipe the config + // volume and rebuild. See README § "Trust boundary, concretely". + // + // 2. AI CLI container config — one named volume per devcontainer. CODEX_HOME + // points here. CLAUDE_CONFIG_DIR is left unset on purpose, so it resolves + // to the default ~/.claude, which is this same path. Credentials, + // identity, and single config files (.credentials.json, + // ~/.claude/.claude.json, settings.json, config.toml, cli-config.json, + // mcp.json) live here with correct Linux permissions. They are NOT + // bind-mounted, because single-file binds break on Docker Desktop Windows + // (the EXDEV error — see the SINGLE-FILE note below). Container-managed + // state (sessions, history, caches, IDE locks) stays separate per + // devcontainer. So two GitNexus checkouts on the same host can't corrupt + // each other. + // + // 3. Other host config — read-only bind mounts for credential and identity + // folders that lack the permission-flattening and onboarding-state + // complications Claude Code has (ssh, aws, azure, git config, plus gh and + // docker). gh and docker are read-only so a compromised dependency can't + // rewrite the GitHub token or the Docker credHelper. See the inline note + // at those mounts. `~/.gitconfig` is not mounted here. VS Code auto-copies + // it separately. + // + // 4. Per-instance state — scoped by `${devcontainerId}`: shell history and + // the npm cache. These survive rebuilds and stay separate between sibling + // instances. + // + // 5. Per-workspace-name AND per-instance state — the workspace `node_modules` + // volumes use both `${localWorkspaceFolderBasename}` (so you can spot them + // in `docker volume ls`) and `${devcontainerId}` (so sibling instances of + // the same repo never collide). This keeps tree-sitter native binaries and + // onnxruntime off the workspace bind mount, which is faster on Windows and + // macOS. + // + // 6. Per-workspace session state — dedicated named volumes for each CLI's + // resume/transcript dirs (Claude projects/, Codex sessions/, Cursor chats/ + // + projects/). Same `${localWorkspaceFolderBasename}` + `${devcontainerId}` + // keying as group 5, but SEPARATE volumes from the group-2 config volumes. + // That separation is the point: the `docker volume rm -config-*` + // re-login / EACCES fix (README § Rebuild/reset) no longer wipes sessions, + // so `claude --resume`, `codex resume`, and `cursor-agent resume` survive a + // rebuild, a full delete-and-recreate, AND that wipe. They overlay the + // config volume at the session sub-paths (Docker precedence: more specific + // path wins). Container-private by design — transcripts can hold pasted + // secrets, and like the group-1 config (read-only stage, copy-once) these + // add NO host write-through surface and leak no other projects' transcripts. + // They do + // NOT survive `docker volume prune`, a `${devcontainerId}` change (moving + // the checkout, WSL vs native), or a new machine — same tier as group 5. + // To make sessions host-visible/portable instead, see the commented + // host-bind block below and README § "Session resume across recreation". + "mounts": [ + // One named volume per container for credentials and identity state. Each + // CLI's real `~/.` config folder lives in a volume. That keeps + // credentials (with correct Linux 600 permissions) and per-container + // session state separate from the host. Logging in inside the container + // and logging in on the host are independent. The bind mounts BELOW these + // volumes override the volume's contents at the paths they cover. Docker + // mount precedence is: the more specific path wins. + "source=claude-config-${devcontainerId},target=/home/node/.claude,type=volume", + "source=codex-config-${devcontainerId},target=/home/node/.codex,type=volume", + "source=cursor-config-${devcontainerId},target=/home/node/.cursor,type=volume", + + // gh CLI config as a per-container named volume, same model as the AI CLI + // configs above: post-create.sh COPIES hosts.yml/config.yml out of the + // read-only /host/.config/gh stage into this volume on container-create. + // The container then owns a WRITABLE copy, so `gh auth login` / + // `gh auth refresh` run INSIDE the container persist across rebuilds — and + // still never write back to the host (the stage is read-only). If the host + // is logged in, that login seeds in; if not, an in-container login sticks. + "source=gh-config-${devcontainerId},target=/home/node/.config/gh,type=volume", + + // claude-mem store. UNLIKE the shareable dirs below (skills/agents/memory), + // this is NOT a host bind. $HOME/.claude-mem is a large, multi-GB SQLite + + // Chroma vector store (claude-mem.db + -wal/-shm, chroma/chroma.sqlite3, HNSW + // index binaries). A read-write host bind would (a) push every byte over the + // 9p/virtiofs share, and (b) expose those SQLite WAL files to unreliable + // fcntl locking across that boundary — with a real corruption risk if + // claude-mem ran on the host and in the container against the same DB at + // once. So it gets its OWN per-container named volume here, same durability + // tier as the config volumes (survives Rebuild Container and a + // delete-and-recreate; keyed by ${devcontainerId}). post-create.sh SEEDS it + // ONCE from the /host/.claude-mem read-only stage when the volume is empty, + // then the container owns its copy — rebuilds never clobber it, and changes + // do NOT flow back to the host. (Container and host memory diverge from the + // seed point on; that is the price of safe SQLite.) Removed by the same + // `docker volume rm` reset flow as the other volumes — see README. + "source=claude-mem-${devcontainerId},target=/home/node/.claude-mem,type=volume", + + // Per-workspace SESSION volumes (mount group 6). These OVERLAY the config + // volumes above at the session sub-paths so "resume my last session" + // survives container recreation the way the seeded config dirs do. + // They are SEPARATE volumes from -config-${devcontainerId}, so the + // README's `docker volume rm -config-${devcontainerId}` re-login fix + // does not touch them. post-create.sh chowns each one explicitly (its + // `find -xdev` stops at the config-volume filesystem boundary and won't + // descend into these). + // + // KEEP IN SYNC: if you add/rename/remove a session sub-path, update all + // three places that name it — (1) the mount line here, (2) the DIRS array + // in post-create.sh (so its chown covers the volume), and (3) the mount + // table + Session-resume section in README.md. + // + // Claude: projects/ holds /.jsonl transcripts plus the + // sessions-index.json that the `/resume` picker reads. The container cwd is + // always /workspace (encodes to the `-workspace` subdir), so this is the + // container's own slice only. Pure JSONL/JSON — no SQLite/WAL, so a volume + // here is clean. `claude --resume` / `--continue` read straight from it. + "source=${localWorkspaceFolderBasename}-claude-sessions-${devcontainerId},target=/home/node/.claude/projects,type=volume", + // Codex: sessions/ holds YYYY/MM/DD/rollout-*.jsonl transcripts. The thread + // index (state_5.sqlite + -wal/-shm) stays at the ~/.codex root on the + // config volume — it is a single WAL file we must NOT split onto a host + // bind. On a recreation that drops the config volume, that index is cleanly + // absent and Codex rebuilds it from these rollout files on the next start + // (backfill). See README for the one-time-rebuild and corruption caveats. + "source=${localWorkspaceFolderBasename}-codex-sessions-${devcontainerId},target=/home/node/.codex/sessions,type=volume", + // Cursor: chats/{hash}/{uuid}/store.db is one SQLite db per session, each in + // its own leaf dir — a DIRECTORY volume keeps each db beside its -wal/-shm + // sidecar, so there is no cross-filesystem single-file hazard. projects/ + // (agent-transcripts) is added too. cursor-agent's on-disk layout is + // community-reverse-engineered (LOW confidence), so this is best-effort; + // keeping it container-private means a wrong guess can't corrupt host state. + "source=${localWorkspaceFolderBasename}-cursor-sessions-${devcontainerId},target=/home/node/.cursor/chats,type=volume", + "source=${localWorkspaceFolderBasename}-cursor-projects-${devcontainerId},target=/home/node/.cursor/projects,type=volume", + // + // OPT-IN: host-shared sessions (like the plugin/skill binds). Uncomment to + // put transcripts on the host — fully visible and portable, but they then + // land on host disk and become a write-through surface for a compromised + // in-container dependency, and the whole-dir binds expose OTHER projects' + // transcripts to the container. Claude is scoped to /workspace's encoded + // subdir to limit that leak; Codex/Cursor stores are not project-scoped, so + // they expose every project. If you enable these, also add the matching + // source dirs to ensure-host-config-dirs.cjs — to its DIRS array (these are + // directory binds), not FILES (which is only for single-file bind sources + // like ~/.claude.json) — so Docker can resolve the binds. Read README + // § "Session resume across recreation" first. + // "source=${localEnv:HOME}/.claude/projects/-workspace,target=/home/node/.claude/projects/-workspace,type=bind", + // "source=${localEnv:HOME}/.codex/sessions,target=/home/node/.codex/sessions,type=bind", + // "source=${localEnv:HOME}/.cursor/chats,target=/home/node/.cursor/chats,type=bind", + // "source=${localEnv:HOME}/.cursor/projects,target=/home/node/.cursor/projects,type=bind", + + // Read-only host stage that post-create.sh copies FROM on container-create. + // It is read-only so a container process can never write back to host CLI + // state — that write-back is the attack vector we block. post-create.sh + // reads two kinds of thing from here: (a) the credential + identity files + // (copied into the volume always), and (b) the shareable dirs — skills, + // agents, plugins, memory, commands, prompts, rules — which it copies into + // the volume ONCE on first create (see step 3/4). Nothing here is bound + // read-write into the container, so the host's on-disk setup is protected. + "source=${localEnv:HOME}/.claude,target=/host/.claude,type=bind,readonly", + "source=${localEnv:HOME}/.codex,target=/host/.codex,type=bind,readonly", + "source=${localEnv:HOME}/.cursor,target=/host/.cursor,type=bind,readonly", + // Read-only host stage for the claude-mem store. post-create.sh COPIES it + // into the claude-mem named volume on first create (seed-once). Read-only so + // the container can never write back to the host's live DB — the seed is a + // one-way snapshot. ensure-host-config-dirs.cjs creates ~/.claude-mem on the + // host so this bind resolves even when claude-mem was never installed there. + "source=${localEnv:HOME}/.claude-mem,target=/host/.claude-mem,type=bind,readonly", + + // NO read-write bind mounts for the shareable subfolders. They USED to be + // bound here (Claude skills/agents/memory/commands/plugins; Codex plugins/ + // prompts/memories/skills; Cursor rules/commands/agents/skills/plugins) so + // host and container shared one copy both ways. That bind was a write-through + // hole: a compromised in-container dependency could drop a malicious skill, + // agent, command, or plugin straight onto the host, which the next HOST + // session would auto-load. To protect the host's on-disk setup, these are + // now COPIED once from the read-only /host/. stage into the per-container + // named volume by post-create.sh (step 3/4), exactly like claude-mem and the + // session volumes. Trade-offs of the copy model: + // - The container gets its OWN writable copy and can never write back to + // the host. Host setup is protected. + // - It is seed-ONCE: host edits made after first create don't reach the + // container until you remove the config volume and rebuild. Container + // edits persist across rebuilds. (See README § Rebuild/reset to re-seed.) + // - The plugin REGISTRY JSONs (Claude known_marketplaces.json / + // installed_plugins.json / plugin-catalog-cache.json; Cursor + // installed_plugins.json) carry absolute OS-native paths, so they can't + // be copied verbatim — post-create.sh translates their paths to the + // container's Linux paths, also seed-once, alongside the cache/ copy so + // the two stay consistent. Codex needs no translation (config.toml holds + // git URLs, not paths), so its whole plugins/ dir is copied as-is. + // - The old read-only-stage-plus-symlink design failed `/plugin marketplace + // add` in the container with EROFS; copy-into-a-writable-volume avoids + // that — the container writes to its own copy, not a read-only mount. + // + // SINGLE-FILE binds for settings.json, .claude.json, and config.toml are + // deliberately ABSENT. On Docker Desktop Windows the named volume sits on + // one filesystem (ext4, /dev/sdd) and a single-file bind from the host sits + // on another (the 9p drvfs share). Apps save a config by writing `foo.tmp` + // and renaming it over `foo`. That rename can't cross filesystems: it hits + // the EXDEV error and fails with `Device or resource busy` or `inter-device + // move failed`. Codex's TUI shows this as "config/batchWrite failed in + // TUI"; Claude just silently loses the write the same way. Instead, we use + // a read-only host stage at /host/.claude, and post-create.sh copies these + // files into the named volume on every container-create. Host changes show + // up on the next rebuild. Container changes stay inside the container until + // a rebuild. + "source=${localEnv:HOME}/.claude.json,target=/host/.claude.json,type=bind,readonly", + "source=${localEnv:HOME}/.config/git,target=/home/node/.config/git,type=bind,readonly", + "source=${localEnv:HOME}/.ssh,target=/home/node/.ssh,type=bind,readonly", + // gh uses the COPY-INTO-VOLUME model (read-only host stage at + // /host/.config/gh + the gh-config named volume above). post-create.sh seeds + // hosts.yml/config.yml from this stage into the volume on create, so the + // container has a writable copy: an in-container `gh auth login` persists + // across rebuilds, and nothing is ever written back to the host because this + // stage is read-only. docker stays a direct READ-ONLY bind: the container + // reads your EXISTING host login (the common case), and a compromised + // in-container dependency can't rewrite ~/.docker/config.json (the registry + // credHelper, which points at a binary). A `docker login` run inside the + // container won't persist back to the host — re-run it on the host, or give + // docker the same copy-into-volume treatment as gh. See README § Trust boundary. + "source=${localEnv:HOME}/.config/gh,target=/host/.config/gh,type=bind,readonly", + "source=${localEnv:HOME}/.docker,target=/home/node/.docker,type=bind,readonly", + "source=${localEnv:HOME}/.aws,target=/home/node/.aws,type=bind,readonly", + "source=${localEnv:HOME}/.azure,target=/home/node/.azure,type=bind,readonly", + "source=commandhistory-${devcontainerId},target=/commandhistory,type=volume", + "source=npm-cache-${devcontainerId},target=/home/node/.npm,type=volume", + "source=${localWorkspaceFolderBasename}-root-node-modules-${devcontainerId},target=/workspace/node_modules,type=volume", + "source=${localWorkspaceFolderBasename}-gitnexus-node-modules-${devcontainerId},target=/workspace/gitnexus/node_modules,type=volume", + "source=${localWorkspaceFolderBasename}-gitnexus-web-node-modules-${devcontainerId},target=/workspace/gitnexus-web/node_modules,type=volume", + "source=${localWorkspaceFolderBasename}-gitnexus-shared-node-modules-${devcontainerId},target=/workspace/gitnexus-shared/node_modules,type=volume" + ], + + // Interactive login is the default way to authenticate for all three CLIs. + // Credentials live in the per-container named volumes (claude-config, + // codex-config, cursor-config), NOT in the host bind mounts. They are copied + // from the read-only /host/. stage into the volume on container-create. + // Single-file binds would break on Docker Desktop Windows (the EXDEV error). + // Shareable content (plugins, skills, agents, memory, commands) is NOT bound + // read-write — it is copied once from the read-only /host/. stage into + // the volume on first create, so the host's on-disk setup stays protected. + // API keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, CURSOR_API_KEY) are NOT + // injected via containerEnv. `${localEnv:VAR}` turns an unset host var into + // an empty string. Cursor in particular treats `CURSOR_API_KEY=""` as "use + // this empty key" instead of "fall back to the stored login", which would + // silently break `cursor-agent login`. If you need API-key auth, `export` + // the var in your container shell, or carry it in your VS Code dotfiles repo + // (see .devcontainer/README.md). + // CLAUDE_CONFIG_DIR is left unset on purpose. The Claude default is + // `$HOME/.claude` (= `/home/node/.claude`), which is exactly where the + // claude-config named volume mounts. Setting the env var would change which + // file Claude reads `hasCompletedOnboarding` from. With the var set, Claude + // reads `$CLAUDE_CONFIG_DIR/.claude.json`, the small identity file. Without + // it, Claude reads `$HOME/.claude.json`, the big onboarding-state file that + // actually holds `hasCompletedOnboarding`, the user-scope MCP config, and + // per-project trust. Leaving the var unset matches host behavior. It also + // lets post-create.sh's sync of `$HOME/.claude.json` skip the setup wizard + // on every container-create. + // + // CODEX_HOME is kept even though it matches the Codex default, as a canary. + // If we ever move the Codex named volume target, this env var makes the + // dependency explicit instead of silently following the default. + "containerEnv": { + "CODEX_HOME": "/home/node/.codex", + "DISABLE_AUTOUPDATER": "1", + // post-create.sh removes `installMethod` from the seeded ~/.claude.json so + // the npm-global binary detects its own install method. This is a backup + // safeguard for Claude Code issue #17289. The install-checks routine probes + // ~/.local/bin/claude just because that directory EXISTS. It does exist + // here, because Cursor drops agent and cursor-agent symlinks there. So even + // when installMethod is non-native, the routine reports a false "claude + // command not found at ~/.local/bin/claude". DISABLE_AUTOUPDATER does NOT + // turn that routine off. DISABLE_INSTALLATION_CHECKS is its dedicated kill + // switch. + "DISABLE_INSTALLATION_CHECKS": "1", + "HISTFILE": "/commandhistory/.zsh_history" + }, + + "customizations": { + "vscode": { + "extensions": [ + "anthropic.claude-code", + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "eamodio.gitlens" + ], + "settings": { + "editor.formatOnSave": true, + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.codeActionsOnSave": { + "source.fixAll.eslint": "explicit" + }, + "files.eol": "\n", + "terminal.integrated.defaultProfile.linux": "zsh", + "terminal.integrated.profiles.linux": { + "bash": { "path": "bash", "icon": "terminal-bash" }, + "zsh": { "path": "zsh" } + } + } + } + }, + + // Do not remap port 4747 (gitnexus serve). gitnexus-web hardcodes + // http://localhost:4747 as its default backend URL. + "forwardPorts": [5173, 4747, 4173], + "portsAttributes": { + "5173": { + "label": "Vite dev (gitnexus-web)", + "onAutoForward": "notify" + }, + "4747": { + "label": "gitnexus serve HTTP API", + "onAutoForward": "notify", + "requireLocalPort": true + }, + "4173": { + "label": "Static web (Vite preview)", + "onAutoForward": "silent" + } + }, + + // Lifecycle split (from the Dev Container spec): + // - `updateContentCommand` runs on container-create AND whenever the + // workspace content changes, such as a lockfile update. It owns installing + // the workspace dependencies. Re-installing on every container-create + // wastes time when nothing changed, but it must re-run when deps change. + // - `postCreateCommand` runs once on container-create. It owns syncing the + // AI CLI credentials and identity from the host. That work should happen + // exactly once per container instance, not on every content update. + // Run both with an explicit `bash` so they don't depend on the script's + // executable bit surviving the workspace bind mount. + "updateContentCommand": "bash .devcontainer/install-deps.sh", + "postCreateCommand": "bash .devcontainer/post-create.sh" +} diff --git a/.devcontainer/ensure-host-config-dirs.cjs b/.devcontainer/ensure-host-config-dirs.cjs new file mode 100644 index 0000000000..c6780dd30b --- /dev/null +++ b/.devcontainer/ensure-host-config-dirs.cjs @@ -0,0 +1,149 @@ +// This runs on the HOST, not inside the container, before the dev container is +// created. devcontainer.json calls it via `initializeCommand`. Its job is to +// make sure the bind-mount source folders listed in devcontainer.json already +// exist on the host. Docker rejects a bind mount when its source is missing, +// which happens if a CLI has never been used. +// +// It works on every platform. `os.homedir()` returns the home folder ($HOME on +// Mac/Linux, %USERPROFILE% on Windows). `fs.mkdirSync({recursive: true})` +// creates folders. It is safe to run repeatedly: a path that already exists is +// left alone. We deliberately do NOT handle `~/.gitconfig` here. VS Code's Dev +// Containers extension copies the host gitconfig into the container when you +// attach, and a bind mount fights with that, so it was removed. +// +// The path-creating logic is exported (ensurePaths/DIRS/FILES) so tests can use +// it. The Windows HOME side effect only runs when this file is run directly as +// the initializeCommand. That keeps tests able to drive it against a temp dir +// without touching the real home or calling `setx`. +// +// Host prerequisite: Node.js must be on PATH. That is the only host requirement +// beyond Docker Desktop and the VS Code Dev Containers extension. Everything +// else runs inside the container. + +'use strict'; + +const fs = require('fs'); +const os = require('os'); +const path = require('path'); + +// Folders that are bind-mount sources in devcontainer.json. Docker rejects a +// bind mount whose source is missing, so we create each one. +// +// We create the TOP per-CLI folders (~/.claude, ~/.codex, ~/.cursor) and +// ~/.claude-mem. These back the /host/. and /host/.claude-mem read-only +// STAGE mounts that post-create.sh copies from on container-create. We do NOT +// create the shareable subfolders (skills/agents/plugins/memory/commands/...) +// here anymore: they used to be read-write bind sources, but they are now +// copied once out of the read-only stage into the per-container volume, so they +// are no longer bind sources and pre-creating empty ones would needlessly write +// into the host of someone who never used that CLI. post-create.sh's seed step +// simply skips any subfolder the host doesn't have. The read-only stage bind is +// the whole ~/. dir, so whatever shareable subfolders DO exist are visible +// to the seed without being listed here. +const DIRS = [ + '.claude', + // claude-mem store ($HOME/.claude-mem). A SEPARATE top-level folder from + // ~/.claude, holding claude-mem's SQLite DB + Chroma vector store. It is NOT + // bind-mounted (a multi-GB SQLite/WAL store is unsafe over a 9p bind on Docker + // Desktop Windows). post-create.sh SEEDS it once into a per-container named + // volume from the /host/.claude-mem read-only stage. We create the source here + // so that stage bind resolves even for a host that never ran claude-mem + // (Docker rejects a missing bind source); the seed then finds no DB to copy + // and the container starts with empty memory. + '.claude-mem', + '.codex', + '.cursor', + '.ssh', + '.docker', + '.aws', + '.azure', + path.join('.config', 'gh'), + path.join('.config', 'git'), +]; + +// Files to pre-create. Only `~/.claude.json` is created here. It is the one +// source that is bound as a single file (read-only at /host/.claude.json). If +// that source is missing, Docker would create a FOLDER in its place, so it has +// to exist as a file first. `~/.claude/settings.json` and +// `~/.codex/config.toml` are NOT single-file binds. post-create.sh copies them +// out of the /host/. read-only folder stage, and `sync_from_host` simply +// does nothing when they are absent (the `[ -f ]` guard). Creating them here +// would needlessly write to the host of someone who never ran that CLI, so we +// don't. +const FILES = ['.claude.json']; + +// Create every folder and touch every file under `home`. Safe to run again: +// an existing path is left untouched. The root is a parameter so tests can run +// it against a temp dir. +function ensurePaths(home, dirs = DIRS, files = FILES) { + for (const dir of dirs) { + const full = path.join(home, dir); + if (!fs.existsSync(full)) { + fs.mkdirSync(full, { recursive: true }); + } + } + for (const file of files) { + const full = path.join(home, file); + if (!fs.existsSync(full)) { + fs.closeSync(fs.openSync(full, 'a')); + } + } +} + +module.exports = { ensurePaths, DIRS, FILES }; + +if (require.main === module) { + // One-time setup for native Windows. VS Code fills in the bind-mount sources + // using `${localEnv:HOME}`, which reads its own process environment. Windows + // does not set `HOME` by default; it uses `USERPROFILE`. With no `HOME`, the + // bind sources shrink to filesystem-root paths (`/.claude`, `/.codex`, ...) + // and Docker rejects them with `bind source path does not exist`. + // + // The fix is to save `HOME=%USERPROFILE%` into the user's environment with + // `setx`. `setx` writes to `HKCU\Environment`. Every process the user starts + // after that inherits the new value, including VS Code once it restarts. The + // current VS Code process can't see the change, because its environment was + // set when it launched. So we tell the user to restart VS Code once. + // + // Later runs see that `HOME` is set, skip this block, and continue normally. + // Mac, Linux, and WSL hosts already have `HOME` set by the shell, so this + // block does nothing on those platforms. + if (process.platform === 'win32' && !process.env.HOME) { + const userprofile = process.env.USERPROFILE; + if (userprofile) { + try { + require('child_process').execFileSync('setx', ['HOME', userprofile], { + stdio: 'ignore', + }); + console.error(''); + console.error('='.repeat(70)); + console.error(' GitNexus devcontainer one-time Windows setup'); + console.error('='.repeat(70)); + console.error(''); + console.error(`HOME has been set to %USERPROFILE% (${userprofile}).`); + console.error("VS Code reads this at startup, so the current session can't pick it up."); + console.error(''); + console.error(' 1. Close ALL VS Code windows (File > Exit, not just the window).'); + console.error(' 2. Reopen VS Code, open this folder, and re-run Reopen in Container.'); + console.error(''); + console.error('This is a one-time setup. Subsequent rebuilds work normally.'); + console.error('='.repeat(70)); + process.exit(1); + } catch (err) { + console.error('ERROR: failed to set HOME automatically: ' + err.message); + console.error(''); + console.error('Run this in a Windows shell, then restart VS Code:'); + console.error(' setx HOME "%USERPROFILE%"'); + process.exit(1); + } + } else { + console.error('ERROR: neither HOME nor USERPROFILE is set on this host.'); + console.error(''); + console.error('Set HOME to your user profile directory and restart VS Code:'); + console.error(' setx HOME "%USERPROFILE%"'); + process.exit(1); + } + } + + ensurePaths(os.homedir()); +} diff --git a/.devcontainer/install-deps.sh b/.devcontainer/install-deps.sh new file mode 100644 index 0000000000..d574f77be9 --- /dev/null +++ b/.devcontainer/install-deps.sh @@ -0,0 +1,68 @@ +#!/usr/bin/env bash +# Devcontainer updateContentCommand. The Dev Container spec runs this when the +# container is created AND whenever workspace content changes (for example a +# lockfile update). This script installs workspace dependencies only. Syncing AI +# CLI state lives in post-create.sh, which runs once right after this. +# +# Why the split: updateContentCommand re-runs on content changes, but +# postCreateCommand runs only at container-create. Keeping `npm install` here +# means a rebuild after pulling new dependencies refreshes them. The AI CLI +# credential and path-translation work does not re-run each time. + +set -euo pipefail +cd /workspace + +echo "[install-deps] 1/4: chown workspace node_modules + npm cache mount points" +# The named volumes (workspace/*/node_modules and ~/.npm) are created at first +# mount. They inherit ownership from the image's UID before realignment. Then +# `updateRemoteUserUID: true` shifts the `node` user's UID. Now the volumes are +# owned by the old, stale UID and npm install cannot write to them. So we chown +# again here, after realignment. Running it again later changes nothing. +# +# We use `find -xdev -exec chown -h` (the same idiom as post-create.sh) instead +# of a plain `chown -R`. There are two separate guards. First, `-xdev` stops +# find from descending past each volume's own filesystem, so it won't recurse +# into a host folder mounted underneath. Second, `-h` makes chown change the +# symlink itself instead of following it to its target. Without `-h`, a symlink +# in the tree (one a dependency's postinstall drops, or a dangling +# node_modules/.bin link) would either send the chown onto a target on another +# filesystem, or fail to follow and abort the whole script under `set -e`. For +# regular files and directories `-h` does nothing, so the ownership fix is the +# same. +for d in /workspace/node_modules \ + /workspace/gitnexus/node_modules \ + /workspace/gitnexus-web/node_modules \ + /workspace/gitnexus-shared/node_modules \ + /home/node/.npm; do + sudo find "$d" -xdev -exec chown -h node:node {} + +done + +echo "[install-deps] 2/4: clear stale .husky/_ runtime cache" +# On Docker Desktop for Windows, the bind-mount permission translation won't let +# the new container's `node` user overwrite a `.husky/_/h` file that an earlier +# container wrote under a different UID. So we delete it. `.husky/_` is a +# gitignored runtime cache, and husky rebuilds it during the root `npm install`. +# Husky upstream has no fix for this UID clash. +rm -rf .husky/_ + +echo "[install-deps] 3/4: npm install at root, then gitnexus-shared (build required)" +# Install order matters. Root goes first, for lint-staged, husky, and prettier. +# Then gitnexus-shared, which must be built before installing gitnexus-web or +# gitnexus. Both of those depend on it via `file:../gitnexus-shared`. +npm install +cd /workspace/gitnexus-shared +npm install +npm run build + +echo "[install-deps] 4/4: npm install gitnexus-web, then gitnexus" +# gitnexus-web goes before gitnexus. The gitnexus `prepare` script runs +# scripts/build.js, which compiles gitnexus-web when that directory is present. +# In the devcontainer the whole workspace is bind-mounted, so gitnexus-web/ is +# present when gitnexus installs. The production Dockerfiles COPY only selected +# files, so the directory is not present there. +cd /workspace/gitnexus-web +npm install +cd /workspace/gitnexus +npm install + +echo "[install-deps] done" diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh new file mode 100644 index 0000000000..58c9f8892d --- /dev/null +++ b/.devcontainer/post-create.sh @@ -0,0 +1,310 @@ +#!/usr/bin/env bash +# Devcontainer postCreate script. It runs once, right after the container is +# created. devcontainer.json wires it up via `postCreateCommand`. Workspace +# dependencies are installed elsewhere, in install-deps.sh (`updateContentCommand`). +# That script runs BEFORE this one — that is the order the devcontainer spec +# defines. This script does one job: sync the AI CLI credentials and identity +# from the host. + +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" + +echo "[post-create] 1/4: chown AI CLI named-volume mount points" +# Fix ownership on the named volumes (~/.claude, ~/.codex, ~/.cursor, +# /commandhistory). When they first mount, they take the user ID baked into the +# image, before any realignment. Then `updateRemoteUserUID: true` shifts the +# `node` user to a new ID. Now the volumes are owned by the old, stale ID, and +# writes into them fail. (~/.local is a directory in the image, not a volume. +# We chown it too, just to be safe.) install-deps.sh fixes the workspace side. +# This script fixes the AI CLI side, so each lifecycle hook handles its own part. +# +# There are two separate guards here, and they do different things. `-xdev` +# keeps find from descending into other filesystems. The shareable dirs (skills, +# agents, plugins, memory, commands, prompts, rules) are no longer host bind +# mounts — they now live INSIDE the config volume (seeded in step 3/4), so +# `-xdev` correctly walks and chowns them as the container-private volume files +# they are. What `-xdev` still stops at are the SESSION volumes (mount group 6), +# which remain separate filesystems mounted at sub-paths (see below). `-h` tells +# chown to act on a symlink ITSELF instead of following it, so it never lands on +# a target across a filesystem boundary and never aborts on a broken symlink +# under `set -e` (a legacy Option-B symlink could still exist on a carried-over +# volume). For regular files and directories `-h` does nothing extra. +# +# The session volumes (mount group 6: .claude/projects, .codex/sessions, +# .cursor/chats, .cursor/projects) are their OWN filesystems mounted at +# sub-paths, so `-xdev` rooted at the config-volume parent deliberately skips +# them. That is why each one is listed as its own root below: rooted there, +# `-xdev` walks just that volume and chowns its top level, so the CLI's first +# write doesn't hit EACCES on a stale image UID. These are container-private +# volumes, not the host's own files — the read-only /host/. stages we copy +# from are mounted elsewhere and are never chowned. +DIRS=( + /home/node/.claude + /home/node/.claude/projects + /home/node/.codex + /home/node/.codex/sessions + /home/node/.cursor + /home/node/.cursor/chats + /home/node/.cursor/projects + /home/node/.config/gh + /home/node/.local + /commandhistory +) +# claude-mem volume: chown it ONLY on first create (its completion sentinel is +# absent). The step-4/4 seed copies the store as the node user, so a populated +# claude-mem volume is already node-owned on every later rebuild — a recursive +# `find` over a multi-GB store (the 7GB+ DB plus the Chroma index) just to +# re-stamp ownership that is already correct would add real latency to every +# rebuild for nothing. On first create the volume is empty, so this chown of the +# bare mount point is trivial and lets the seed write into it. +[ -f /home/node/.claude-mem/.claude-mem-seeded ] || DIRS+=(/home/node/.claude-mem) +for d in "${DIRS[@]}"; do + # Skip a root that isn't present rather than aborting the whole run under + # `set -e`. Docker creates every declared volume's mount point before this + # script runs, so in the normal case all roots exist and this is a no-op. + # The guard matters only if a session volume is later removed from + # devcontainer.json without its matching DIRS entry being removed too — then + # provisioning skips it instead of failing before credentials ever sync. + [ -d "$d" ] || continue + sudo find "$d" -xdev -exec chown -h node:node {} + +done + +echo "[post-create] 2/4: sync AI CLI credentials + identity from host" +# Clean up after an older devcontainer design (Option B). Back then these paths +# were symlinks pointing into the read-only host stage +# (e.g. /home/node/.claude/plugins -> /host/.claude/plugins). A write through +# such a symlink would land on a read-only host file and fail. Delete any that +# survive on a carried-over volume. The shareable dirs are now real directories +# in the named volume, seeded from the host in step 3/4 below. +for p in plugins skills agents memory commands; do + [ -L "/home/node/.claude/$p" ] && rm "/home/node/.claude/$p" +done +for p in plugins prompts memories skills config.toml; do + [ -L "/home/node/.codex/$p" ] && rm "/home/node/.codex/$p" +done +for p in plugins rules commands agents skills; do + [ -L "/home/node/.cursor/$p" ] && rm "/home/node/.cursor/$p" +done +mkdir -p /home/node/.claude/plugins /home/node/.cursor/plugins + +# Shareable content (skills, agents, plugins, memory, commands, prompts, rules) +# is NO LONGER bind-mounted. It is COPIED once from the read-only host stage into +# the named volume in step 3/4 below, so a compromised in-container dependency +# can't write through to the host's on-disk CLI setup. This step handles only the +# credentials, identity, and single config files. Those stay per-container in the +# named volume and are COPIED from the host once when the container is created: +# - .credentials.json (Claude OAuth tokens) +# - .claude/.claude.json (Claude identity: userID, oauthAccount, and +# migration tracking — a different file from $HOME/.claude.json) +# - settings.json (Claude), config.toml (Codex), mcp.json (Cursor). These are +# single config files, and single files can't be bind-mounted on Windows +# (the EXDEV error explained below). +# - auth.json (Codex), cli-config.json (Cursor — which mixes auth and settings) +# - the plugin registry JSONs that contain absolute paths (Claude + Cursor). +# Those are translated below. +# +# How the sync behaves: it ALWAYS overwrites from the host when the container is +# created. A fresh container then starts logged in as the host's user, if the +# host had credentials. From that point the container manages its own login, +# until the next rebuild copies the host files again. Logging out inside the +# container does NOT log out the host. Per-container login is the goal, and +# bind-mounting these files would instead make a logout shared between both. + +sync_from_host() { + local src=$1 + local dst=$2 + local mode=${3:-600} + if [ -f "$src" ]; then + rm -f "$dst" + cp "$src" "$dst" + chmod "$mode" "$dst" + fi +} + +sync_from_host \ + /host/.claude/.credentials.json /home/node/.claude/.credentials.json +sync_from_host \ + /host/.claude/.claude.json /home/node/.claude/.claude.json 644 + +# These config files are COPIED from the host, not bind-mounted. We tried +# bind-mounting them as single files and it didn't work. On Docker Desktop for +# Windows the named volume (ext4) and the host bind mount (9p drvfs) are +# different filesystems. Apps save a config by writing a temp file and renaming +# it over the real one, and that rename fails across filesystems (the "EXDEV" or +# "Device or resource busy" error). So copy the host's version into the named +# volume when the container is created. The container can then rewrite it freely +# until the next rebuild copies the host version again. +sync_from_host /host/.claude/settings.json /home/node/.claude/settings.json 644 +sync_from_host /host/.codex/config.toml /home/node/.codex/config.toml 644 + +# Seed $HOME/.claude.json from the host, but NOT as a straight copy. That file +# mixes two kinds of state. Some is portable account and onboarding state we +# want to keep: hasCompletedOnboarding, oauthAccount, userID, projects, +# tipsHistory. The rest describes how Claude is installed on the host, and that +# part is never valid here. This image installs Claude with `npm install -g`, +# but the host's `installMethod` (for example "native") makes Claude look for +# ~/.local/bin/claude and fail with +# "claude command not found at /home/node/.local/bin/claude". The fix strips the +# machine-specific fields and forces hasCompletedOnboarding, while handling a +# host file that isn't a JSON object. That logic lives in seed-claude-config.cjs +# so it can be unit-tested and prettier-checked +# (translate-plugin-registries.test.cjs). +node "$SCRIPT_DIR/seed-claude-config.cjs" + +# Codex auth. Some hosts store credentials in the OS keyring instead of on disk +# (`cli_auth_credentials_store = "keyring"`, the default on macOS). Those hosts +# have no auth.json file, so the copy below quietly does nothing. In that case, +# log in inside the container with `codex login --device-auth`. +sync_from_host \ + /host/.codex/auth.json /home/node/.codex/auth.json + +# Cursor CLI. Its cli-config.json holds both auth and settings in one file. +# Cursor has known upstream problems authenticating inside Docker, even when the +# config is copied correctly. If `cursor-agent` reports auth errors after the +# copy, run `cursor-agent login` again inside the container. mcp.json (Cursor's +# MCP server config) is also a single file, so it is copied on create rather +# than bind-mounted, for the same EXDEV reason as above. hooks.json is left out +# on purpose. Cursor hooks run shell commands, and sharing the host's hooks +# would widen the supply-chain attack surface inside the container. Copy it in +# yourself if you want the host's hooks in the container. +sync_from_host \ + /host/.cursor/cli-config.json /home/node/.cursor/cli-config.json +sync_from_host \ + /host/.cursor/mcp.json /home/node/.cursor/mcp.json 644 + +# gh CLI auth + settings. Same copy-into-volume model as the credentials above: +# hosts.yml holds the GitHub token (mode 600), config.yml holds settings (644). +# Copied from the read-only /host/.config/gh stage into the gh-config named +# volume on create. Because the volume is writable, an in-container +# `gh auth login` / `gh auth refresh` persists across rebuilds; because the +# stage is read-only, nothing flows back to the host. If the host had no login, +# both copies quietly no-op and whatever the container wrote is kept. +sync_from_host /host/.config/gh/hosts.yml /home/node/.config/gh/hosts.yml +sync_from_host /host/.config/gh/config.yml /home/node/.config/gh/config.yml 644 + +echo "[post-create] 3/4: seed shareable config dirs from host (first create only)" +# The shareable dirs (Claude skills/agents/memory/commands/plugins; Codex +# plugins/prompts/memories/skills; Cursor rules/commands/agents/skills/plugins) +# used to be read-write host bind mounts, so a write inside the container landed +# directly on the host's files. That exposed the host's on-disk CLI setup: a +# compromised workspace dependency running in the container could drop a malicious +# skill, agent, command, or plugin into the host's folders, which the next HOST +# session would then auto-load. To protect the host, these are no longer bound. +# Instead we COPY them once from the read-only /host/. stage into the +# per-container named volume, exactly like claude-mem (step 4/4) and the session +# volumes. The container gets its own writable copy and can NEVER write back to +# the host. The container also avoids the old read-only-stage EROFS failure, +# because it writes to its own volume copy, not a read-only mount. +# +# Seed-once, persist: a per-CLI marker file records that the copy has happened. +# On the first container-create the marker is absent, so we copy; on every later +# rebuild the marker is present, so we skip and keep whatever the container has +# accumulated. Host edits made AFTER the first create do NOT reach the container +# until you remove the config volume and rebuild (see README § Rebuild/reset). +seed_shareable() { + # seed_shareable ...: copy each /host/./ into the + # named volume, once. Skips a subdir the host doesn't have. We use `cp -r`, + # NOT `cp -a`/`cp -p`: this script runs as the non-root node user, and the + # host-stage files are owned by a different UID, so trying to preserve + # ownership would fail with EPERM and abort the run under `set -e` (the same + # reason sync_from_host uses plain cp). `cp -r` copies contents owned by node + # — exactly what we want — and preserves symlinks as symlinks (GNU default). + local cli=$1 + shift + local marker="/home/node/.$cli/.devcontainer-shareable-seeded" + [ -f "$marker" ] && return 0 + for sub in "$@"; do + local src="/host/.$cli/$sub" + local dst="/home/node/.$cli/$sub" + [ -d "$src" ] || continue + mkdir -p "$dst" + cp -r "$src/." "$dst/" + done +} + +# Decide which plugin registries to translate BEFORE seeding sets the markers. +# We translate only a CLI being seeded this run, so a plugin installed inside the +# container isn't overwritten by the host's registry on a later rebuild. Codex +# has no path-bearing registry (config.toml holds git URLs), so it's never here. +TRANSLATE_CLIS=() +[ -f /home/node/.claude/.devcontainer-shareable-seeded ] || TRANSLATE_CLIS+=(claude) +[ -f /home/node/.cursor/.devcontainer-shareable-seeded ] || TRANSLATE_CLIS+=(cursor) + +seed_shareable claude skills agents memory commands plugins/marketplaces plugins/cache +seed_shareable codex plugins prompts memories skills +seed_shareable cursor rules commands agents skills plugins/marketplaces plugins/local + +# Translate the path-bearing plugin registries (Claude + Cursor) for the CLIs we +# just seeded. They store absolute, OS-native install paths +# (`C:\Users\X\.claude\plugins\...` on Windows), which the Linux container can't +# resolve — it would fail with `cache-miss`. translate-plugin-registries.cjs +# rewrites those to the container's paths and writes the result into the volume. +if [ "${#TRANSLATE_CLIS[@]}" -gt 0 ]; then + node "$SCRIPT_DIR/translate-plugin-registries.cjs" "${TRANSLATE_CLIS[@]}" +fi + +# Record that each CLI's shareable surface is seeded, so later rebuilds keep the +# container's copy. Touch even when the host had nothing to copy — an empty CLI +# is still "seeded", and we don't want to re-scan the host on every rebuild. +# +# ORDERING INVARIANT — do NOT move these touches earlier (e.g. into +# seed_shareable per-CLI). The markers must be written only AFTER the registry +# translation above, because seed (cache copy) and translate (registry rewrite) +# are logically atomic: a marker set between them would let a later rebuild skip +# translation for an already-seeded CLI, leaving its cache/ in place but its +# registry still pointing at host paths (`cache-miss`). Writing all markers here, +# after translate, means any abort mid-seed leaves NO markers, so the next create +# re-runs the whole seed+translate. The cost is re-copying an already-copied CLI +# on retry; `cp -r` overwrites in place, so that is idempotent and cheap relative +# to a broken plugin registry. +for cli in claude codex cursor; do + touch "/home/node/.$cli/.devcontainer-shareable-seeded" +done + +echo "[post-create] 4/4: seed claude-mem store from host (first create only)" +# claude-mem keeps its memory in $HOME/.claude-mem — a SQLite DB (claude-mem.db +# plus -wal/-shm) and a Chroma vector store (chroma/chroma.sqlite3 + HNSW index +# binaries). It is mounted as a per-container named volume, NOT a host bind: +# pushing a multi-GB SQLite/WAL store over the 9p/virtiofs bind risks unreliable +# fcntl locking and corruption, especially if claude-mem ran on the host and in +# the container against the same files at once (see devcontainer.json). +# +# So seed it ONCE, then let the container own its copy. On every later rebuild +# we skip the copy and keep whatever the container has accumulated since — +# rebuilds never clobber it. The container's memory and the host's diverge from +# this seed point on; that is the deliberate cost of keeping SQLite off a shared +# bind. To re-seed from the host, remove the volume (`docker volume rm +# claude-mem-`) and rebuild. +# +# The skip guard is a COMPLETION SENTINEL (.claude-mem-seeded), NOT the presence +# of claude-mem.db. Keying on the DB file would be a trap: a multi-GB `cp -r` can +# be interrupted (disk full, I/O error) and abort the script under `set -e`, +# leaving a PARTIAL claude-mem.db behind. The next create would then see that +# truncated file and treat the store as "already seeded", sticking the container +# with a corrupt DB forever. With a sentinel touched only AFTER `cp` returns 0, +# an interrupted seed leaves no sentinel; the next create clears the half-copied +# store and retries cleanly. CONSISTENCY: copying a live WAL database is only +# crash-consistent if claude-mem is NOT writing on the host during the copy — do +# not run claude-mem on the host during a first-create or a re-seed rebuild. +# +# `cp -r` (not `cp -a`/`cp -p`) copies the DB together with its -wal/-shm +# sidecars in one pass. We avoid preserving ownership for the same reason as the +# shareable seed above: this runs as the non-root node user against host-owned +# files, so `cp -a` would fail with EPERM and abort under `set -e`. `cp -r` +# leaves the copies owned by node. The host stage is read-only, so this can +# never write back to the host's live DB. +if [ -f /host/.claude-mem/claude-mem.db ] && [ ! -f /home/node/.claude-mem/.claude-mem-seeded ]; then + echo "[post-create] seeding ~/.claude-mem from host (one-time copy, may be several GB)" + # Clear any partial store left by a previously-interrupted seed (mindepth 1 + # so the volume mount point itself is never removed), then copy and only then + # write the sentinel. A partial store is node-owned (cp runs as node, and + # step 1 re-chowns the volume whenever the sentinel is absent), so no sudo. + find /home/node/.claude-mem -mindepth 1 -maxdepth 1 -exec rm -rf {} + + cp -r /host/.claude-mem/. /home/node/.claude-mem/ + touch /home/node/.claude-mem/.claude-mem-seeded +else + echo "[post-create] skipping claude-mem seed (already seeded, or host has no store)" +fi + +echo "[post-create] done" diff --git a/.devcontainer/seed-claude-config.cjs b/.devcontainer/seed-claude-config.cjs new file mode 100644 index 0000000000..6010753a43 --- /dev/null +++ b/.devcontainer/seed-claude-config.cjs @@ -0,0 +1,83 @@ +// Builds the container's $HOME/.claude.json from the host's copy. It does NOT +// copy the host file verbatim. The host's ~/.claude.json holds two kinds of +// data. Some is portable account and onboarding state: hasCompletedOnboarding, +// oauthAccount, userID, projects, tipsHistory. We keep that. The rest tracks +// how Claude was installed on the host machine, and that is never right inside +// this container. +// +// Here is why the install fields break things. The image installs Claude with +// `npm install -g`. But if the host's `installMethod` says something like +// "native", Claude looks for ~/.local/bin/claude and fails with +// "claude command not found at /home/node/.local/bin/claude". So we drop the +// install and machine fields. With them gone, the npm-global binary detects its +// own install method. We also force hasCompletedOnboarding so the setup wizard +// is skipped, even when the host has never run Claude before. +// +// This logic was pulled out of a heredoc in post-create.sh. As its own file the +// transform can be unit-tested and prettier-checked (see seed-claude-config.test +// via the translate-plugin-registries test harness). DISABLE_AUTOUPDATER=1 in +// containerEnv already stops runtime updates. This file only quiets the doctor +// mismatch and the native-path probe. + +'use strict'; + +const fs = require('fs'); + +// Fields that describe how Claude was installed on the host machine. They are +// never valid in an `npm install -g` container. Removing them lets Claude +// detect the npm-global install on its own. +const MACHINE_FIELDS = [ + 'installMethod', + 'autoUpdates', + 'autoUpdatesProtectedForNative', + 'shiftEnterKeyBindingInstalled', +]; + +// Pure transform: take whatever the host file parsed to and return a config +// object suitable for the container. It also guards against a host file that is +// valid JSON but not an object. A bare number, string, or array would pass the +// parse try/catch. Then the field deletes would do nothing, the +// hasCompletedOnboarding assignment would silently fail, and onboarding would +// trigger again on every rebuild. The guard replaces such a value with {}. +function sanitizeClaudeConfig(parsed) { + let cfg = parsed; + if (cfg === null || typeof cfg !== 'object' || Array.isArray(cfg)) { + cfg = {}; + } + for (const k of MACHINE_FIELDS) { + delete cfg[k]; + } + cfg.hasCompletedOnboarding = true; // skip the wizard, even on a first-time host + return cfg; +} + +function readHostConfig(src) { + try { + if (fs.existsSync(src) && fs.statSync(src).size > 0) { + return JSON.parse(fs.readFileSync(src, 'utf8')); + } + } catch { + // Host file is malformed or unreadable. Fall back to an empty config so the + // container still gets a valid file that carries hasCompletedOnboarding. + } + return {}; +} + +function main() { + const src = process.argv[2] || '/host/.claude.json'; + const dst = process.argv[3] || '/home/node/.claude.json'; + const cfg = sanitizeClaudeConfig(readHostConfig(src)); + try { + fs.writeFileSync(dst, JSON.stringify(cfg, null, 2)); + fs.chmodSync(dst, 0o644); + } catch (err) { + console.error(`[post-create] ERROR: failed to seed ${dst}: ${err && err.message}`); + process.exit(1); + } +} + +module.exports = { sanitizeClaudeConfig, readHostConfig, MACHINE_FIELDS }; + +if (require.main === module) { + main(); +} diff --git a/.devcontainer/translate-plugin-registries.cjs b/.devcontainer/translate-plugin-registries.cjs new file mode 100644 index 0000000000..3113e37fa4 --- /dev/null +++ b/.devcontainer/translate-plugin-registries.cjs @@ -0,0 +1,107 @@ +// Rewrites the host paths inside Claude and Cursor plugin-registry JSON files +// so they point at the container's Linux paths, then writes the results into +// the named volume. +// +// Why: both CLIs store absolute, OS-native install paths in their registry +// JSONs. On Windows that looks like `C:\Users\X\.claude\plugins\...`; on macOS +// like `/Users/X/.cursor/...`. The Linux container can't use those paths. If we +// just bind-mounted the host files in, the CLI would try to resolve a Windows +// path under Linux and fail with `cache-miss`. So for each CLI we read the host +// registry, rewrite every absolute path ending in `/./plugins/` to +// `/home/node/./plugins/`, and write the result into the named volume. +// +// Codex is left alone. Its registry is config.toml and holds git URLs, not +// filesystem paths, so there's nothing to translate — its whole plugins/ dir is +// copied as-is into the container volume instead (seeded once by post-create.sh). +// +// This code lived inside a post-create.sh heredoc. We pulled it out so the regex +// and the deep rewrite can be unit-tested and prettier-checked. The regex has +// had path-handling bugs before. + +'use strict'; + +const fs = require('fs'); +const path = require('path'); + +// Build a regex that matches an absolute path containing +// `.plugins`, where is `/` or `\`. It's anchored +// at the start of the string. The lazy `.*?` eats the home prefix up to the +// FIRST `./plugins` segment. +function buildRe(cliName) { + return new RegExp(`^(?:[A-Za-z]:)?[\\\\/].*?[\\\\/]\\.${cliName}[\\\\/]plugins[\\\\/](.*)$`); +} + +// Walk `obj` and rewrite every string value that matches `re`. A match is +// remapped under `ctr`, the container's plugins dir. Windows backslashes in the +// matched part are switched to forward slashes. +function rewriteDeep(obj, re, ctr) { + if (Array.isArray(obj)) return obj.map((v) => rewriteDeep(v, re, ctr)); + if (obj && typeof obj === 'object') { + const out = {}; + for (const [k, v] of Object.entries(obj)) out[k] = rewriteDeep(v, re, ctr); + return out; + } + if (typeof obj === 'string') { + return obj.replace(re, (_, rest) => `${ctr}/${rest.replace(/\\/g, '/')}`); + } + return obj; +} + +const REGISTRIES = [ + { + cli: 'claude', + host: '/host/.claude/plugins', + ctr: '/home/node/.claude/plugins', + files: ['known_marketplaces.json', 'installed_plugins.json', 'plugin-catalog-cache.json'], + }, + { + cli: 'cursor', + host: '/host/.cursor/plugins', + ctr: '/home/node/.cursor/plugins', + files: ['installed_plugins.json'], + }, +]; + +function translate(registries) { + for (const reg of registries) { + const re = buildRe(reg.cli); + try { + fs.mkdirSync(reg.ctr, { recursive: true }); + } catch (err) { + console.error(`[post-create] ERROR: failed to create ${reg.ctr}: ${err && err.message}`); + process.exit(1); + } + for (const name of reg.files) { + const src = path.join(reg.host, name); + const dst = path.join(reg.ctr, name); + if (!fs.existsSync(src) || fs.statSync(src).size === 0) continue; + let data; + try { + data = JSON.parse(fs.readFileSync(src, 'utf8')); + } catch { + continue; // Skip a malformed host registry instead of aborting. + } + try { + fs.writeFileSync(dst, JSON.stringify(rewriteDeep(data, re, reg.ctr), null, 2)); + } catch (err) { + console.error(`[post-create] ERROR: failed to write ${dst}: ${err && err.message}`); + process.exit(1); + } + } + } +} + +// Filter the registry table by CLI name. post-create.sh passes the CLIs it is +// seeding this run (e.g. `claude`), so a registry is only (re)generated on the +// FIRST container-create for that CLI — never on a rebuild, where it would +// clobber a plugin the user installed inside the container. An empty filter +// (no args) means "translate every registry" — the original behavior. +function selectRegistries(registries, only) { + return only && only.length ? registries.filter((r) => only.includes(r.cli)) : registries; +} + +module.exports = { buildRe, rewriteDeep, REGISTRIES, translate, selectRegistries }; + +if (require.main === module) { + translate(selectRegistries(REGISTRIES, process.argv.slice(2))); +} diff --git a/.devcontainer/translate-plugin-registries.test.cjs b/.devcontainer/translate-plugin-registries.test.cjs new file mode 100644 index 0000000000..1a60d59fe3 --- /dev/null +++ b/.devcontainer/translate-plugin-registries.test.cjs @@ -0,0 +1,436 @@ +// Unit tests for the devcontainer host->container config transforms. +// +// This code used to live inside post-create.sh heredocs, where lint could not +// see it and tests could not reach it. We test three things: +// - plugin-registry path translation (buildRe + rewriteDeep + the real +// filesystem translate() driver). Path handling here has had bugs before. +// - the strip of machine-specific fields from $HOME/.claude.json +// (sanitizeClaudeConfig + readHostConfig + the seed-claude-config main() +// entry point) +// - the host bind-source bootstrap (ensurePaths). One test guards against a +// regression: ensurePaths must NOT pre-create settings.json / config.toml +// on the host. +// +// We test both pure functions and code that touches the filesystem. The +// filesystem tests use throwaway directories under os.tmpdir() and delete them +// when done. So they run in CI with no mounts and never touch the real home dir. +// +// Run with the built-in Node test runner (no extra dependencies): +// node --test .devcontainer/ + +'use strict'; + +const test = require('node:test'); +const assert = require('node:assert/strict'); +const os = require('node:os'); +const fs = require('node:fs'); +const path = require('node:path'); +const { execFileSync } = require('node:child_process'); + +const { + buildRe, + rewriteDeep, + translate, + selectRegistries, +} = require('./translate-plugin-registries.cjs'); +const { sanitizeClaudeConfig, readHostConfig } = require('./seed-claude-config.cjs'); +const { ensurePaths, DIRS, FILES } = require('./ensure-host-config-dirs.cjs'); + +const CLAUDE = '/home/node/.claude/plugins'; +const CURSOR = '/home/node/.cursor/plugins'; + +// Make a fresh throwaway directory under the OS temp root. mkdtemp picks a +// unique name on every call, so we don't need Date.now() or random names. +function tmp() { + return fs.mkdtempSync(path.join(os.tmpdir(), 'gn-dc-')); +} + +function rw(value, cli, ctr) { + return rewriteDeep(value, buildRe(cli), ctr); +} + +test('claude: Windows backslash absolute path -> container path', () => { + assert.equal( + rw('C:\\Users\\gergo\\.claude\\plugins\\cache\\x\\1.0', 'claude', CLAUDE), + '/home/node/.claude/plugins/cache/x/1.0', + ); +}); + +test('claude: Windows forward-slash absolute path -> container path', () => { + assert.equal( + rw('C:/Users/gergo/.claude/plugins/marketplaces/m', 'claude', CLAUDE), + '/home/node/.claude/plugins/marketplaces/m', + ); +}); + +test('claude: macOS POSIX path -> container path', () => { + assert.equal( + rw('/Users/alice/.claude/plugins/marketplaces/m', 'claude', CLAUDE), + '/home/node/.claude/plugins/marketplaces/m', + ); +}); + +test('claude: Linux POSIX path -> container path', () => { + assert.equal( + rw('/home/bob/.claude/plugins/cache/foo', 'claude', CLAUDE), + '/home/node/.claude/plugins/cache/foo', + ); +}); + +test('cursor: Windows path -> container cursor path', () => { + assert.equal( + rw('C:\\Users\\gergo\\.cursor\\plugins\\local\\myplug', 'cursor', CURSOR), + '/home/node/.cursor/plugins/local/myplug', + ); +}); + +test('cross-CLI isolation: claude regex leaves a .cursor path untouched', () => { + const input = 'C:\\Users\\g\\.cursor\\plugins\\x'; + assert.equal(rw(input, 'claude', CLAUDE), input); +}); + +test('non-path strings pass through unchanged', () => { + assert.equal(rw('not-a-path', 'claude', CLAUDE), 'not-a-path'); + assert.equal( + rw('https://github.com/EveryInc/x.git', 'claude', CLAUDE), + 'https://github.com/EveryInc/x.git', + ); +}); + +test('non-string scalars pass through unchanged', () => { + assert.equal(rw(42, 'claude', CLAUDE), 42); + assert.equal(rw(null, 'claude', CLAUDE), null); + assert.equal(rw(true, 'claude', CLAUDE), true); +}); + +test('nested objects/arrays are rewritten deeply', () => { + const input = { + 'compound-engineering@m': [ + { installPath: 'C:\\Users\\g\\.claude\\plugins\\cache\\ce\\3.9.2', version: '3.9.2' }, + ], + nested: { installLocation: '/Users/g/.claude/plugins/marketplaces/m' }, + }; + const out = rw(input, 'claude', CLAUDE); + assert.equal( + out['compound-engineering@m'][0].installPath, + '/home/node/.claude/plugins/cache/ce/3.9.2', + ); + assert.equal(out['compound-engineering@m'][0].version, '3.9.2'); + assert.equal(out.nested.installLocation, '/home/node/.claude/plugins/marketplaces/m'); +}); + +test('sanitizeClaudeConfig: strips machine fields, forces hasCompletedOnboarding', () => { + const out = sanitizeClaudeConfig({ + installMethod: 'native', + autoUpdates: false, + autoUpdatesProtectedForNative: true, + shiftEnterKeyBindingInstalled: true, + userID: 'abc', + oauthAccount: { emailAddress: 'x@y.z' }, + }); + assert.equal(out.installMethod, undefined); + assert.equal(out.autoUpdates, undefined); + assert.equal(out.autoUpdatesProtectedForNative, undefined); + assert.equal(out.shiftEnterKeyBindingInstalled, undefined); + assert.equal(out.userID, 'abc'); + assert.equal(out.oauthAccount.emailAddress, 'x@y.z'); + assert.equal(out.hasCompletedOnboarding, true); +}); + +test('sanitizeClaudeConfig: non-object inputs become a valid onboarding-bearing object', () => { + for (const bad of [42, 'x', null, ['a'], true]) { + const out = sanitizeClaudeConfig(bad); + assert.equal(typeof out, 'object'); + assert.equal(Array.isArray(out), false); + assert.equal(out.hasCompletedOnboarding, true); + } +}); + +test('sanitizeClaudeConfig: empty object still gets hasCompletedOnboarding', () => { + assert.deepEqual(sanitizeClaudeConfig({}), { hasCompletedOnboarding: true }); +}); + +// --- readHostConfig: reading the file, and the fallbacks when it fails ------ + +test('readHostConfig: missing file -> {}', () => { + const dir = tmp(); + try { + assert.deepEqual(readHostConfig(path.join(dir, 'nope.json')), {}); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test('readHostConfig: empty (zero-byte) file -> {}', () => { + const dir = tmp(); + try { + const f = path.join(dir, 'empty.json'); + fs.writeFileSync(f, ''); + assert.deepEqual(readHostConfig(f), {}); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test('readHostConfig: malformed JSON -> {}', () => { + const dir = tmp(); + try { + const f = path.join(dir, 'bad.json'); + fs.writeFileSync(f, '{ not valid json'); + assert.deepEqual(readHostConfig(f), {}); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test('readHostConfig: valid object is parsed through', () => { + const dir = tmp(); + try { + const f = path.join(dir, 'ok.json'); + fs.writeFileSync(f, JSON.stringify({ userID: 'u', hasCompletedOnboarding: false })); + const out = readHostConfig(f); + assert.equal(out.userID, 'u'); + assert.equal(out.hasCompletedOnboarding, false); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +// --- translate(): runs against real registry files on disk ------------------ + +test('translate: rewrites host absolute paths and writes into the ctr dir', () => { + const hostDir = tmp(); + const ctrParent = tmp(); + const ctrDir = path.join(ctrParent, 'plugins'); // need not exist yet; translate creates it + try { + const reg = [{ cli: 'claude', host: hostDir, ctr: ctrDir, files: ['installed_plugins.json'] }]; + fs.writeFileSync( + path.join(hostDir, 'installed_plugins.json'), + JSON.stringify({ 'p@m': [{ installPath: 'C:\\Users\\g\\.claude\\plugins\\cache\\p\\1.0' }] }), + ); + translate(reg); + const out = JSON.parse(fs.readFileSync(path.join(ctrDir, 'installed_plugins.json'), 'utf8')); + assert.equal(out['p@m'][0].installPath, `${ctrDir}/cache/p/1.0`); + } finally { + fs.rmSync(hostDir, { recursive: true, force: true }); + fs.rmSync(ctrParent, { recursive: true, force: true }); + } +}); + +test('translate: idempotent — a second run reproduces byte-identical output', () => { + const hostDir = tmp(); + const ctrParent = tmp(); + const ctrDir = path.join(ctrParent, 'plugins'); + try { + const reg = [{ cli: 'claude', host: hostDir, ctr: ctrDir, files: ['installed_plugins.json'] }]; + fs.writeFileSync( + path.join(hostDir, 'installed_plugins.json'), + JSON.stringify({ 'p@m': [{ installPath: 'C:\\Users\\g\\.claude\\plugins\\cache\\p\\1.0' }] }), + ); + translate(reg); + const first = fs.readFileSync(path.join(ctrDir, 'installed_plugins.json'), 'utf8'); + translate(reg); + const second = fs.readFileSync(path.join(ctrDir, 'installed_plugins.json'), 'utf8'); + assert.equal(first, second); + } finally { + fs.rmSync(hostDir, { recursive: true, force: true }); + fs.rmSync(ctrParent, { recursive: true, force: true }); + } +}); + +test('translate: malformed host registry is skipped, dst not written', () => { + const hostDir = tmp(); + const ctrParent = tmp(); + const ctrDir = path.join(ctrParent, 'plugins'); + try { + const reg = [{ cli: 'claude', host: hostDir, ctr: ctrDir, files: ['installed_plugins.json'] }]; + fs.writeFileSync(path.join(hostDir, 'installed_plugins.json'), '{ broken'); + translate(reg); + assert.equal(fs.existsSync(path.join(ctrDir, 'installed_plugins.json')), false); + } finally { + fs.rmSync(hostDir, { recursive: true, force: true }); + fs.rmSync(ctrParent, { recursive: true, force: true }); + } +}); + +test('translate: empty and missing host registries are skipped without error', () => { + const hostDir = tmp(); + const ctrParent = tmp(); + const ctrDir = path.join(ctrParent, 'plugins'); + try { + const reg = [ + { cli: 'claude', host: hostDir, ctr: ctrDir, files: ['empty.json', 'missing.json'] }, + ]; + fs.writeFileSync(path.join(hostDir, 'empty.json'), ''); // we never create missing.json + translate(reg); + assert.equal(fs.existsSync(path.join(ctrDir, 'empty.json')), false); + assert.equal(fs.existsSync(path.join(ctrDir, 'missing.json')), false); + } finally { + fs.rmSync(hostDir, { recursive: true, force: true }); + fs.rmSync(ctrParent, { recursive: true, force: true }); + } +}); + +// --- selectRegistries: the per-CLI filter post-create.sh drives translate with + +test('selectRegistries: no filter -> all registries (original behavior)', () => { + const regs = [{ cli: 'claude' }, { cli: 'cursor' }]; + assert.deepEqual(selectRegistries(regs, []), regs); + assert.deepEqual(selectRegistries(regs, undefined), regs); +}); + +test('selectRegistries: filter keeps only the named CLIs', () => { + const regs = [{ cli: 'claude' }, { cli: 'cursor' }]; + assert.deepEqual(selectRegistries(regs, ['claude']), [{ cli: 'claude' }]); + assert.deepEqual(selectRegistries(regs, ['cursor']), [{ cli: 'cursor' }]); + assert.deepEqual(selectRegistries(regs, ['claude', 'cursor']), regs); +}); + +test('selectRegistries: an unknown CLI name selects nothing', () => { + const regs = [{ cli: 'claude' }, { cli: 'cursor' }]; + assert.deepEqual(selectRegistries(regs, ['codex']), []); +}); + +test('selectRegistries: empty registry table stays empty under any filter', () => { + assert.deepEqual(selectRegistries([], ['claude']), []); + assert.deepEqual(selectRegistries([], []), []); +}); + +// --- seed-claude-config main(): end-to-end, through the real CLI entry point + +const SEED_SCRIPT = path.join(__dirname, 'seed-claude-config.cjs'); + +test('seed main: strips machine fields, keeps account, sets onboarding, chmod 644', () => { + const dir = tmp(); + try { + const src = path.join(dir, 'host.claude.json'); + const dst = path.join(dir, 'out.claude.json'); + fs.writeFileSync( + src, + JSON.stringify({ + installMethod: 'native', + userID: 'abc', + oauthAccount: { emailAddress: 'x@y.z' }, + }), + ); + execFileSync(process.execPath, [SEED_SCRIPT, src, dst]); + const out = JSON.parse(fs.readFileSync(dst, 'utf8')); + assert.equal(out.installMethod, undefined); + assert.equal(out.userID, 'abc'); + assert.equal(out.oauthAccount.emailAddress, 'x@y.z'); + assert.equal(out.hasCompletedOnboarding, true); + if (process.platform !== 'win32') { + assert.equal(fs.statSync(dst).mode & 0o777, 0o644); + } + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test('seed main: missing host file still writes a valid onboarding-bearing file', () => { + const dir = tmp(); + try { + const dst = path.join(dir, 'out.claude.json'); + execFileSync(process.execPath, [SEED_SCRIPT, path.join(dir, 'nope.json'), dst]); + assert.deepEqual(JSON.parse(fs.readFileSync(dst, 'utf8')), { hasCompletedOnboarding: true }); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +test('seed main: chmodSync widens a pre-existing restrictive dst to 0o644', () => { + // This checks the file's permission bits, which only exist on POSIX systems. + // + // The catch: CI's default umask is 022, so a plain writeFileSync already + // creates files at mode 0o644. Asserting 0o644 right after a fresh write + // would therefore NOT prove the explicit chmodSync did anything. + // + // So we pre-create dst at the stricter mode 0o600. Opening a file in 'w' + // mode replaces its contents but KEEPS the mode of a file that already + // exists. That means the only way dst can end up at 0o644 is the chmodSync + // inside seed-claude-config.cjs. This pins the test to the chmod and not to + // the umask: delete the chmodSync line and this test fails, while the other + // seed test still passes. + if (process.platform === 'win32') return; + const dir = tmp(); + try { + const src = path.join(dir, 'host.claude.json'); + const dst = path.join(dir, 'out.claude.json'); + fs.writeFileSync(src, JSON.stringify({ userID: 'u' })); + fs.writeFileSync(dst, '{}'); + fs.chmodSync(dst, 0o600); + execFileSync(process.execPath, [SEED_SCRIPT, src, dst]); + assert.equal(fs.statSync(dst).mode & 0o777, 0o644); + assert.equal(JSON.parse(fs.readFileSync(dst, 'utf8')).userID, 'u'); + } finally { + fs.rmSync(dir, { recursive: true, force: true }); + } +}); + +// --- ensurePaths: sets up the host paths the bind mounts point at ----------- + +test('ensurePaths: creates every DIR and FILE under a temp home, idempotently', () => { + const home = tmp(); + try { + ensurePaths(home); + for (const d of DIRS) { + assert.equal(fs.statSync(path.join(home, d)).isDirectory(), true, `not a dir: ${d}`); + } + for (const f of FILES) { + assert.equal(fs.statSync(path.join(home, f)).isFile(), true, `not a file: ${f}`); + } + // Running it again must not throw and must not overwrite existing content. + fs.writeFileSync(path.join(home, '.claude.json'), '{"keep":true}'); + ensurePaths(home); + assert.equal(fs.readFileSync(path.join(home, '.claude.json'), 'utf8'), '{"keep":true}'); + } finally { + fs.rmSync(home, { recursive: true, force: true }); + } +}); + +test('ensurePaths: does NOT pre-create settings.json / config.toml (no gratuitous host mutation)', () => { + const home = tmp(); + try { + ensurePaths(home); + assert.equal(fs.existsSync(path.join(home, '.claude', 'settings.json')), false); + assert.equal(fs.existsSync(path.join(home, '.codex', 'config.toml')), false); + } finally { + fs.rmSync(home, { recursive: true, force: true }); + } +}); + +test('ensurePaths: does NOT pre-create the shareable subdirs (now copied, not bound)', () => { + // The shareable dirs are seeded into the per-container volume from the + // read-only /host stage, so they are no longer bind-mount sources. Pre-creating + // empty ones would needlessly write into the host of someone who never used a + // CLI. This pins the DIRS trim: re-adding any of these would fail the test. + const home = tmp(); + const mustNotExist = [ + path.join('.claude', 'skills'), + path.join('.claude', 'agents'), + path.join('.claude', 'memory'), + path.join('.claude', 'commands'), + path.join('.claude', 'plugins'), + path.join('.codex', 'plugins'), + path.join('.codex', 'prompts'), + path.join('.codex', 'memories'), + path.join('.codex', 'skills'), + path.join('.cursor', 'rules'), + path.join('.cursor', 'commands'), + path.join('.cursor', 'agents'), + path.join('.cursor', 'skills'), + path.join('.cursor', 'plugins'), + ]; + try { + ensurePaths(home); + for (const sub of mustNotExist) { + assert.equal(fs.existsSync(path.join(home, sub)), false, `should not pre-create: ${sub}`); + } + // The top-level stage roots that ARE still bind sources must exist. + for (const top of ['.claude', '.codex', '.cursor', '.claude-mem']) { + assert.equal(fs.statSync(path.join(home, top)).isDirectory(), true, `missing root: ${top}`); + } + } finally { + fs.rmSync(home, { recursive: true, force: true }); + } +}); diff --git a/.gitattributes b/.gitattributes index 5e9d18bf44..5110ebb5da 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,2 +1,17 @@ * text=auto eol=lf .husky/* text eol=lf + +# Shell scripts: force LF unconditionally so devcontainer scripts +# (e.g. anything COPYed into a Linux container) execute correctly when +# checked out on Windows hosts with core.autocrlf=true. +*.sh text eol=lf +*.bash text eol=lf + +# Native and binary assets shouldn't be treated as text under any +# auto-detection or eol normalization. +*.node binary +*.wasm binary +*.onnx binary +*.so binary +*.dll binary +*.dylib binary diff --git a/.github/workflows/ci-devcontainer.yml b/.github/workflows/ci-devcontainer.yml new file mode 100644 index 0000000000..aa7785c28a --- /dev/null +++ b/.github/workflows/ci-devcontainer.yml @@ -0,0 +1,88 @@ +name: Devcontainer Smoke + +# Smoke-tests .devcontainer/ whenever it changes. Two things happen here. +# First, unit tests run on the pure host->container config transforms: the +# plugin-registry path translation, and the strip of the machine field from +# $HOME/.claude.json. Second, the devcontainer image is built through the +# standard @devcontainers/cli path. That CLI reads build.args from +# devcontainer.json, so the version pin there stays the single source of truth. +on: + push: + branches: [main] + paths: + - '.devcontainer/**' + - '.github/workflows/ci-devcontainer.yml' + pull_request: + paths: + - '.devcontainer/**' + - '.github/workflows/ci-devcontainer.yml' + +permissions: + contents: read + +# Concurrency convention: see CONTRIBUTING.md → "GitHub Actions — Concurrency Convention". +# Grouped per branch or tag. Cancel a PR run when a newer one replaces it. +# Never cancel a push-to-main run. +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +jobs: + config-transforms: + name: Config-transform unit tests + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + # persist-credentials: false — this job only reads (tests and syntax + # checks) and never pushes. The setting keeps GITHUB_TOKEN out of + # .git/config, which zizmor flags as the "artipacked" issue. + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + with: + node-version: 22 + - name: Unit-test the host->container config transforms + run: node --test .devcontainer/translate-plugin-registries.test.cjs + - name: Syntax-check the lifecycle shell scripts + run: | + bash -n .devcontainer/install-deps.sh + bash -n .devcontainer/post-create.sh + + build: + name: Build devcontainer image + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + # persist-credentials: false — this is a read-only build smoke that + # never pushes. The setting keeps GITHUB_TOKEN out of .git/config, + # which zizmor flags as the "artipacked" issue. + - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + with: + persist-credentials: false + - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 + with: + node-version: 22 + # Builds the image the same way a developer's "Reopen in Container" does. + # @devcontainers/cli reads devcontainer.json (jsonc format), resolves + # build.args (the CLAUDE_CODE_VERSION / CODEX_VERSION pins), and runs the + # Dockerfile. This smoke catches Dockerfile regressions and any drift from + # the canonical version pins. The lifecycle hooks (post-create.sh) do not + # run here. They need the host config mounts, and CI has none. + # + # ARCH COVERAGE: this runs on an x64 runner with no --platform or QEMU, so + # it builds only the amd64 Cursor branch (CURSOR_SHA256_X64). The arm64 + # branch (CURSOR_SHA256_ARM64 plus the arm64 tarball URL) is pinned by a + # sha256 checked against the published artifact, but it is not BUILT here. + # Cursor's extract-and-symlink step does not depend on the architecture, so + # the only remaining gap is a stale arm64 URL or hash. If that becomes a + # concern, add a linux/arm64 matrix leg (docker/setup-qemu-action plus + # `--platform`). + # + # The @devcontainers/cli version is pinned on purpose. A bare + # `npx --yes @devcontainers/cli` would resolve @latest at run time. A + # breaking or malicious publish could then change CI behavior, or change + # how devcontainer.json is read, with no diff to show for it. Bump this pin + # deliberately, alongside the Dockerfile and devcontainer.json pins. + - name: Build devcontainer via @devcontainers/cli + run: npx --yes @devcontainers/cli@0.87.0 build --workspace-folder . diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e048d4f2fa..4cb50c8c3d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,10 @@ This project uses the [PolyForm Noncommercial License 1.0.0](https://polyformpro 3. **Web UI (if needed):** `cd gitnexus-web && npm install` 4. Run tests as described in [TESTING.md](TESTING.md). +### Containerized development (optional) + +If you prefer an isolated environment with Claude Code, OpenAI Codex CLI, and Cursor CLI pre-installed, open the repo in VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and run **Dev Containers: Reopen in Container**. See [`.devcontainer/README.md`](.devcontainer/README.md) for first-time auth flows and Windows WSL2 setup. + ## Branch and pull requests - Use short-lived branches off the default branch of the repo you are targeting.