* fix(ingestion): stop emitting phantom Function defs for array-method callbacks
The HOC-wrapped-arrow scope-query pattern (`const X = HOC(args => ...)`),
added for React idioms such as forwardRef/memo/useCallback, also matched
array higher-order-method callbacks like `const x = arr.map(a => ...)`.
Those produced a spurious `@declaration.function` named after the
binding, on top of its value def, so calls inside the callback attributed
to a phantom `Function:x` instead of the enclosing scope.
- Add a shared `isArrayMethodCallbackArrow` detector
(`ARRAY_CALLBACK_METHODS` blocklist) and suppress the
`@declaration.function` emit-side in both the JS and TS scope-captures
emitters, leaving the value binding as the sole def.
- Add `selectNodeBearingDef` in scope-extractor: the tested
collapse-rule contract (function-like > value > first) the deferred
node-creation migration will consume to keep one graph node per
binding.
This corrects the registry-primary scope model and CALLS-edge
attribution (calls inside array-method callbacks now source from the
enclosing File scope). The duplicate graph *node* itself is still
created by the legacy parse-worker path and is removed by the follow-up
node-creation migration.
Refs #1876
Co-authored-by: Cursor <cursoragent@cursor.com>
* test(ingestion): strengthen array-callback coverage; document receiver-blind suppression
Follow-ups from the production-readiness review of PR #1906:
- array-callback.ts: document that isArrayMethodCallbackArrow is
receiver-blind — an in-set method name on a NON-array receiver
(Map/Set.forEach, RxJS observable.map, query-builder .sort, lodash
chain .filter) is also suppressed. Accepted limitation, not a bug:
the binding holds the call's result value, not a callable.
- captures unit tests (JS + TS): add a non-array-receiver
characterization case, and extend the it.each lists to cover
findLast, findLastIndex, reduceRight — the full 13-entry
ARRAY_CALLBACK_METHODS set is now exercised in both languages.
- js-array-method-callback-attribution integration test: tighten the
File-sourced CALLS assertions from toBeGreaterThan(0) to
toHaveLength(1) (now also catches over-attribution).
- scope-extractor.ts: note that the dead selectNodeBearingDef export is
intentional and tracked by #1876 (deferred node-creation migration).
Comment-and-test only; no production behavior change. Verified locally:
tsc clean, prettier/eslint clean, captures unit 106 passed,
scope-extractor 31 passed, integration 3 passed.
Refs #1876
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(review): add PR reviewer swarm agents
Seven read-only subagents coordinated by an orchestration skill for
structured, evidence-grounded production-readiness PR reviews.
Agents: facts-historian, branch-hygiene, risk-architect, test-ci-verifier,
security-boundary, docs-dod, synthesis-critic. All use Read/Grep/Glob/Bash
only — no edit tools.
Skill invoked as /gitnexus-pr-swarm-review <PR>.
* Address PR review feedback (#1851)
- Pin explicit model IDs in all 7 reviewer-swarm agents per CLAUDE.md
(no unversioned aliases). Set the two mechanical agents
(test-ci-verifier, branch-hygiene-reviewer) to claude-haiku-4-5-20251001
per @Cenrax's "this could be haiku"; the five analytical agents use
claude-sonnet-4-6.
- Add an explicit read-only Bash policy (permitted/prohibited command
lists) to every agent's Rules section, so the read-only guarantee is
defended against injected/adversarial PR content rather than prose-only.
- Add a hard synthesis-critic gate to the swarm skill: do not post the
final review until the critic's "Required corrections before posting"
section is empty (was advisory only).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* feat(review): make PR reviewer swarm portable across AI CLIs
Restructure the reviewer swarm around a single CLI-neutral source of truth so it
runs from any AI CLI, not just Claude Code.
- pr-swarm-review/: canonical orchestration.md (Swarm + Solo execution modes with
an identical output contract) and personas/0N-*.md (the 7 review personas,
relocated verbatim from the Claude agents, each tagged with a model tier and the
read-only Bash policy). Single source of truth — edit here, not in the wrappers.
- Thin per-CLI adapters that read the canonical spec at runtime (no duplication):
- Claude Code: coordinator skill (Swarm mode) + the 7 agents are now thin
wrappers that read their persona file (frontmatter/model preserved; mechanical
lanes Haiku, analytical lanes Sonnet).
- Gemini CLI: .gemini/commands/gitnexus-pr-swarm-review.toml
- GitHub Copilot: .github/prompts/gitnexus-pr-swarm-review.prompt.md
- Cursor: .cursor/commands/gitnexus-pr-swarm-review.md
- AGENTS.md: canonical "PR Swarm Review" section -> orchestration.md, the universal
entrypoint honored by Codex, Cursor, Gemini, Copilot, and any AGENTS.md-aware
agent (Codex user-level prompt install noted in the README).
Graceful degradation: only Claude Code has parallel subagents (Swarm mode); every
other CLI runs the 7 lanes sequentially in one agent (Solo mode) with the same
output contract. prettier --check clean (root config).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* fix(group): derive grpc consumer FQN from java imports so client-jar consumers don't fall back to short names
Java gRPC microservices commonly follow the "client-jar" pattern: the
service owner publishes a pre-compiled stub jar to a Maven repository
and consumer repos depend on the jar instead of carrying the
originating `.proto` files. gRPC's official Java quickstart, Alibaba
HSF, ByteDance KiteX-Java and google-cloud-java all document this
shape.
Before this commit, `GrpcExtractor` resolved a fully-qualified
contract id (`grpc::<package>.<Service>/*`) only when the consumer
repo also carried a matching `.proto`. Client-jar consumers had no
proto, so they fell back to a short-name contract id
(`grpc::<Service>/*`) that never matched the provider's contract id.
Cross-repo grpc cross-link counts dropped to zero on every realistic
Java microservice group — including all of crsdp's `crsdp-backend →
unipus_cloud_framework` connections.
Fix: derive the proto package directly from each consumer file's
`import <pkg>.<XxxGrpc>;` statement. The package from the import is
exactly the proto package, so the contract id matches the provider's
verbatim — no `.proto` lookup needed in the consumer repo.
Implementation
--------------
* `grpc-patterns/types.ts` — `GrpcDetection` gains an optional
`protoPackage` field. Plugins set it when the package can be
derived from the source file alone.
* `grpc-patterns/java.ts` — adds `GRPC_CLASS_IMPORT_PATTERNS`, a
tree-sitter query that captures every
`import_declaration > scoped_identifier { scope, name }` pair where
the imported name ends in `Grpc`. `import static …` and
`import w.x.*;` are excluded by tree-sitter shape: the `name:` field
is only present on the non-static, non-wildcard form. The plugin
builds a per-file `XxxGrpc → fullPackage` map and tags every
provider / consumer detection it emits.
* `grpc-extractor.ts` — `detectionToContract()` now resolves the
contract id in three steps:
1. detection-supplied `protoPackage` wins (skips the proto map
entirely so an unrelated same-name service in the consumer
repo can't blur the FQN);
2. otherwise consult the legacy per-repo proto map;
3. otherwise fall back to a short-name contract id, preserving
pre-fix behaviour.
Confidence stays at the "with proto" tier when the import path
resolves: an import statement in real source is at least as
authoritative as a per-repo proto map.
Same-short-name disambiguation
-------------------------------
The motivating case `unipus_cloud_framework` defines two distinct
`ContentRpcService` services in different proto packages
(`cn.unipus.ucf.api.proto.client.service.ContentRpcService` vs
`cn.unipus.ucf.admin.proto.client.service.ContentRpcService`). Two
consumer files importing the two flavours now emit two distinct FQNs;
neither could be told apart from the other under the legacy short-
name fallback.
Out of scope
------------
`import w.x.*;` (wildcard service imports) are left to the legacy
short-name fallback. Wildcard imports are discouraged by Google's
Java style guide and IntelliJ's defaults, and resolving them
unambiguously would require either group-level proto-package
catalogs or per-class disambiguation, both of which are larger
follow-ups. This commit only changes behaviour for the dominant
specific-import case.
Tests
-----
`test/unit/group/grpc-extractor.test.ts` adds a new "Java client-jar
consumer (import-derived FQN)" describe block with 9 cases covering
both the happy paths (consumer/provider FQN derivation, same-short-
name disambiguation, import-vs-local-proto precedence) and the
regression-protection paths (no import + no detection emitted, static
imports / wildcards ignored, mixed-file repos preserved).
End-to-end verification
-----------------------
Ran the patched cli on the real `crsdp-backend` (consumer, no
`.proto`) and `unipus_cloud_framework` (provider, has `.proto`)
repos. Synced as a two-repo group, every `XxxGrpc` referenced via a
specific import in `UcfAdminGrpcClientService.java` produced an FQN
contract id that exact-matched the provider repo's FQN — 9 grpc
cross-links surfaced where there were 0 before.
Verification
------------
* `npx tsc --noEmit`: pass
* `npx tsc` (dist rebuild): pass
* `test/unit/group/grpc-extractor.test.ts`: 60/60 pass (51 existing
+ 9 new)
* `test/unit/group/`: 30 files / 545 tests all green
* `npx prettier --check` on touched files: pass
* `npx eslint` on touched src files: 0 errors / 0 warnings
* fix(group): handle option java_package and proto-map disagreement in grpc detection
Addresses Claude bot review on PR #1889:
- Finding 1: parse `option java_package` when building proto context;
add a reverse index so an import-derived package can be translated
back to the proto package.
- Finding 2: when same-repo proto map has the service, use the proto
package; warn and record `meta.importPackage` if the import disagrees.
- Finding 3: add an end-to-end wildcard match test (provider+consumer
fixture, runs `buildProviderIndex`+`runWildcardMatch`).
Client-jar consumer + diverging `java_package` (no local proto)
remains a known limitation; pinned by a dedicated test.
---------
Co-authored-by: henry <zhangwei2017@unipus.cn>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
* feat(cobol): migrate COBOL to scope-based resolution (regex provider)
Migrate COBOL to scope-based registry resolution, validating the
parse-source-agnostic contract — COBOL uses regex, not tree-sitter,
but implements the same LanguageProvider interface via emitScopeCaptures.
Phase 1-5 complete per #941 DoD.
New files:
languages/cobol/captures.ts — emitScopeCaptures wrapping regex tagger
languages/cobol/interpret.ts — import/type-binding/receiver hooks
languages/cobol/index.ts — barrel export
languages/cobol/scope-resolver.ts — ScopeResolver wiring (9 fields, 3 toggles)
Modified files:
languages/cobol.ts — wire 4 scope-resolution hooks
registry.ts — register cobolScopeResolver
registry-primary-flag.ts — document REGISTRY_PRIMARY_COBOL
Fixtures:
17 fixture files, 30 test cases across 11 required classes
test/integration/resolvers/cobol-scope.test.ts
Tests: 24/24 pass (default + REGISTRY_PRIMARY_COBOL=0)
tsc: zero cobol-specific errors
Shadow mode (GITNEXUS_SHADOW_MODE=1): zero crashes
Regex perf: 10K-line file in 408ms (threshold: 2000ms)
NOT added to MIGRATED_LANGUAGES — REGISTRY_PRIMARY_COBOL env var only.
* chore(cobol): add COBOL to MIGRATED_LANGUAGES
* fix(cobol): revert MIGRATED_LANGUAGES flip, fix JSDoc dup, fix arityCompatibility
* fix(standalone): wire standalone providers into scope-extractor for registry-primary (COBOL Ring 3 flip)
- Gate cobolPhase with isRegistryPrimary() guard to prevent double emission
- Wire standalone providers (parseStrategy !== 'tree-sitter') with
emitScopeCaptures into parse-worker via extractParsedFile bridge
- Add COBOL to MIGRATED_LANGUAGES in registry-primary-flag.ts
- Fix Module scope range in captures.ts to use full program bounds
(was just PROGRAM-ID line, causing scope containment failures)
- Update cobol.test.ts grand totals to be mode-aware
- Wrap legacy exact-count assertions in if (!isPrimary)
- Fix cobol-scope.test.ts fixture path to use __dirname (was process.cwd())
Tests:
REGISTRY_PRIMARY_COBOL=0: 83/83 pass (59 legacy + 24 capture)
REGISTRY_PRIMARY_COBOL=1: 28/28 pass (4 mode-aware + 24 capture)
* test(cobol): restore original test assertions, add mode-aware describe blocks alongside
- Remove if (!isPrimary) wrapper from legacy assertions
- Keep ALL 59 original tests intact and running unconditionally
- Add new 'scope-resolution mode' describe block alongside legacy tests
- New block uses isPrimary to check for scope-resolution capture output
- Legacy tests run against cobolPhase output (skipGraphPhases=true)
- Mode-aware tests validate standalone provider wiring in registry-primary mode
* fix(test): use result.graph instead of result.parsedFiles in scope-mode test
- PipelineResult has no parsedFiles field; use graph.nodes instead
- Use toBe strict equality (not.toBeNull()) per review feedback
- Object.keys for node count as suggested by reviewer
* test(cobol): add COBOL pipeline benchmark following PHP benchmark structure
- Generate synthetic COBOL codebases at 100/250/500 file scales
- Each file has 1 PROGRAM-ID, N paragraphs, cross-file CALLs, COPY books
- Measures wall-clock time, peak heap, node/edge counts
- SkipIf(!GITNEXUS_BENCH) — run with GITNEXUS_BENCH=1
- Prints table with scaling ratios and linearity assertions
* fix(bench): remove COPY from paragraphs, add REGISTRY_PRIMARY_COBOL note
- COPY statements belong only in DATA DIVISION (already present there)
- Revert copyLine inside paragraph blocks to idiomatic COBOL
- Add header note about =1 mode producing ~0 node/edge counts
* fix(bench): restore COPY in paragraphs for preprocessing stress
- COPY in paragraph blocks exercises the preprocessor expansion path
more heavily than DATA DIVISION only placement.
* fix(bench): constant 3 paragraphs per program, add 1000-files scale, relax threshold to 4x
- Fixed paragraphsPerProgram to constant 3 for consistent scaling
- Added 1000-file scale to benchmark
- Raised assertion threshold to 4x to accommodate 100-250 step
* fix: skip standalone providers in scope-resolution phase when registry-primary
scopeResolutionPhase was reading all COBOL files from disk and running
scope-resolution for standalone providers that don't emit graph edges
yet. Added a guard: if provider.languageProvider.parseStrategy ===
'standalone', skip it entirely. Saves 68s at 1000 files in =1 mode.
* fix: remove COBOL isRegistryPrimary gate, suppress standalone IMPORTS double-emission
- Remove the isRegistryPrimary gate in cobolPhase so it runs in both modes,
keeping cobolPhase as the sole COBOL graph-edge producer.
- Add a guard in runScopeResolution to skip emitImportEdges for standalone
providers (parseStrategy === 'standalone'), preventing scope-resolution
from duplicating IMPORTS edges already produced by cobolPhase.
- Scope-resolution still runs for standalone providers (capture extraction,
model finalization, reference resolution) — only edge emission is skipped.
- Both modes: 60/60 cobol.test.ts, 24/24 cobol-scope.test.ts.
* fix: 4 review fixes — dead code removal, memory cleanup, benchmark comment, standalone-bridge test
1. Remove dead standalone guard in run.ts (phase.ts:164 is canonical).
2. Filter standalone preExtractedByPath entries in phase.ts (memory leak).
3. Update benchmark comment: cobolPhase runs in both modes.
4. Add unit test proving extractParsedFile works for COBOL standalone provider.
Revert PipelineResult.parsedFiles — not needed with unit test approach.
* perf(cobol): memoize copybook preprocessing; make benchmark measure file-count scaling
The COBOL pipeline benchmark reported superlinear (quadratic) scaling, but the
pipeline itself is O(n) in file count. The superlinearity was a fixture artifact:
every program COPYed all floor(fileCount/5) copybooks in WORKING-STORAGE, so
emitted data-item nodes — and total work — grew O(n^2). Verified empirically:
node count grew ~2x per file-doubling; with constant per-program fan-out it grows
exactly 1x (linear), and 0/3 adversarial audits could refute the O(n) conclusion.
- benchmark: each program now COPYs a constant 3 shared copybooks so the
benchmark measures true file-count scaling. Add a deterministic node-ratio
assertion that fails if the O(n^2) copy-all fan-out is reintroduced.
- processor: memoize preprocessed copybook content per processCobol call so each
copybook is preprocessed once, not once per COPY site
(O(programs x copybooks) -> O(copybooks)). Safe: REPLACING is applied later by
the expander on the cached pre-REPLACING content.
Verified: 246 COBOL tests pass; benchmark scales linearly (node ratio 1.0); tsc clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The pin was 2.1.153, which predates Opus 4.8 support (added in
2.1.154). With DISABLE_AUTOUPDATER=1 the container never updated past
the pin, so Claude Code only offered models up to 4.7. Bump to the
latest 2.1.156 so Opus 4.8 is available.
Co-authored-by: Cursor <cursoragent@cursor.com>
Move ~/.config/gh from a read-only bind to the same read-only host
stage + per-container named volume pattern used for the AI CLI
credentials. post-create.sh seeds hosts.yml/config.yml from the
/host/.config/gh stage into the gh-config volume on create, so an
in-container `gh auth login` now persists across rebuilds while the
read-only stage still prevents any write-back to the host token.
Co-authored-by: Cursor <cursoragent@cursor.com>
Installed by the official bun.sh/install script with the release tag
passed as the first positional arg, so the version is pinned even though
the install path itself is an unverified remote script (the one such
exception in the image — Cursor and the base image stay sha256/digest-
pinned). BUN_INSTALL is set in ENV so the binary lands at a known path
and the installer's rc-file edits don't matter. unzip is added to apt
since the Bun installer extracts a .zip.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replace the read-write host bind mounts for the AI-CLI shareable dirs
(Claude skills/agents/memory/commands/plugins; Codex plugins/prompts/
memories/skills; Cursor rules/commands/agents/skills/plugins) with a
seed-once copy from a read-only /host/.<cli> stage into the per-container
config volume. The container gets its own writable copy and can never
write back to the host, closing the write-through vector where a
compromised in-container dependency could drop a malicious agent, command,
skill, or plugin onto the host for the next host session to auto-load.
Add a per-container claude-mem named volume (claude-mem-${devcontainerId})
at /home/node/.claude-mem, seeded once from a read-only /host/.claude-mem
stage. claude-mem's multi-GB SQLite + Chroma store is kept off a host bind
(unreliable fcntl locking / corruption risk over 9p on Docker Desktop
Windows) while still surviving rebuilds.
- post-create.sh: seed shareable dirs (marker-gated, seed-once) and run
plugin-registry translation per seeded CLI; seed claude-mem behind a
completion-sentinel guard that self-heals an interrupted multi-GB copy;
chown the claude-mem volume only on first create.
- translate-plugin-registries.cjs: add selectRegistries() so translation
runs per-CLI seed-once instead of clobbering container-installed plugins.
- ensure-host-config-dirs.cjs: add ~/.claude-mem; drop the shareable
subdirs (no longer bind sources).
- devcontainer.json: drop the RW shareable binds; add the claude-mem
volume + read-only stage.
- README: rewrite trust-boundary, mount table, and rebuild/reset docs for
the copy model.
- tests: cover selectRegistries and the trimmed DIRS (30 pass).
* feat(group): add Kotlin Spring WebClient long-form HTTP consumer extraction
Follow-up to #1855. Extends `kotlin.ts` with the long-form WebClient
fluent chain that #1855 explicitly deferred:
webClient.method(HttpMethod.GET).uri("/x").retrieve().awaitBody<T>()
This pattern remains common in Kotlin Spring 4 → 5 migrations and in
codebases that prefer the fluent verb-as-enum style. The short form
(`webClient.get().uri("/x")`) was already supported in #1855.
Approach:
- Single deeper tree-sitter query (`WEB_CLIENT_LONG_PATTERNS`) that
matches the full chain structurally — both `.method(HttpMethod.X)`
and `.uri("...")` in one pattern. Verb is captured as the
`simple_identifier` of the `HttpMethod.X` field access.
- Verb is whitelisted to GET/POST/PUT/DELETE/PATCH (consistent with
the short-form's `WEB_CLIENT_SHORT_TO_HTTP` map).
- Receiver constraint `(#eq? @obj "webClient")` mirrors the short
form and Java plugin heuristic.
Out of scope (intentional):
- Variable-bound verbs: `val verb = HttpMethod.PATCH; webClient.method(verb)...`
Source-scan can't follow the binding without graph context.
Pinned by an anti-overreach test.
- HEAD/OPTIONS/TRACE: not in `WEB_CLIENT_SHORT_TO_HTTP` either —
keeps polyglot symmetry with java.ts and the short form.
Tests: 4 new cases under `consumer extraction — fetch patterns`,
gated by tree-sitter-kotlin grammar availability.
positive (3)
- long form GET
- long form POST / PUT / DELETE / PATCH (4 verbs in 1 fixture)
- no double-emit pin (long-form chain produces exactly one
consumer, not one from each query)
anti-regression (1)
- variable-bound verb does NOT match (graph-aware concern)
The previous `'does NOT match Kotlin WebClient long form (deferred
to follow-up)'` test from #1855 is replaced by these — the deferred
state is now resolved.
Reverse-validated: temporarily disabling the long-form emit makes
exactly the 3 positive tests fail; the variable-bound-verb anti-
regression test continues to pass (it pins behavior independent
of the emit being on or off).
Local validation:
- test/unit/group/http-route-extractor.test.ts: 66/66 ✅
- test/unit/group: 546/546 ✅
- npx prettier --check (changed files): clean ✅
* test(group): address Claude review findings F1 and F2 on PR #1884
Two minor follow-ups from the production-readiness review:
F1 — Stale block comment at the top of the Kotlin consumer suite
(was: "Three consumer flavors covered here ... long-form deferred
to a follow-up"). Updated to "Four consumer flavors" and removed
the deferred sentence — the deferral is resolved by this PR. The
kotlin.ts file header was already updated; this brings the test
file comment in sync. Per DoD §2.3 (no stale comments).
F2 — Replaced `expect(wcConsumers.length).toBeGreaterThanOrEqual(4)`
with `expect(wcConsumers).toHaveLength(4)` in the multi-verb test.
The fixture is fully deterministic — exactly 4 long-form calls,
no other consumer types — so an exact count assertion is the right
shape per DoD §2.7 ("use toBe / toEqual for exact expectations").
Added a comment explaining what the assertion catches that the
existing per-verb toBeDefined() checks would miss (accidental 5th
consumer from a duplicate query firing or a regressed receiver
constraint).
F3 (HEAD/OPTIONS/TRACE negative test) is intentionally not added
in this PR — same precedent as #1855 where HEAD/OPTIONS/TRACE on
the short form are also implicitly excluded without a pinning
test. Happy to add one in a separate PR if maintainers want
explicit pinning across both forms.
F4 (CI on pre-merge SHA) is the maintainer's call — the merge from
main is theirs to re-trigger CI on. The merge brings only Java
consumer changes (PR #1872) and Go provider changes (PR #1886),
both in entirely separate files from this PR's Kotlin work.
Local validation:
- test/unit/group/http-route-extractor.test.ts: 73/73 ✅
(66 from this PR pre-merge + 7 from PR #1872 merged via main)
- npx prettier --check (changed files): clean ✅
* refactor(group): hoist Kotlin WebClient long-form verb regex to module scope
Address @magyargergo's review request on PR #1884:
> Can you please extract the regexp from the for loop? 🙏
(kotlin.ts:510)
Compiles the verb whitelist `^(GET|POST|PUT|DELETE|PATCH)$` once at
module load instead of every iteration of the long-form scan loop.
Mirrors the placement and JSDoc style of the sibling
`WEB_CLIENT_SHORT_TO_HTTP` constant.
Behavior is unchanged — same verb whitelist, same exclusion of
HEAD/OPTIONS/TRACE for symmetry with the short form. The 4
itKotlinConsumer long-form tests added in this PR continue to
pass, and the variable-bound-verb anti-overreach test continues
to pin the deliberate non-match.
Local validation:
- test/unit/group/http-route-extractor.test.ts: 77/77 ✅
- test/unit/group: 557/557 ✅
- npx prettier --check (changed file): clean ✅
---------
Co-authored-by: henry <zhangwei2017@unipus.cn>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
Add dedicated per-workspace named volumes (mount group 6) for the three
AI CLIs' session/resume state so `claude --resume`, `codex resume`, and
`cursor-agent resume` survive a rebuild, a full delete-and-recreate, and
the `docker volume rm <cli>-config-*` re-login fix:
- Claude -> ~/.claude/projects
- Codex -> ~/.codex/sessions
- Cursor -> ~/.cursor/chats + ~/.cursor/projects
The volumes are SEPARATE from the credential/config volumes and keyed
like the node_modules volumes (${localWorkspaceFolderBasename}-...-
${devcontainerId}), so wiping a config volume to force a re-login no
longer destroys session history. Session state already survived a plain
rebuild (it lived in the config volume); this closes the recreation,
volume-rm, and devcontainerId-change gaps.
Kept container-private (not host bind mounts) deliberately: transcripts
can contain pasted secrets, so a host bind would spill them to host
disk, widen the supply-chain write-through surface, and leak
cross-project transcripts. A commented-out opt-in host-bind block is
included for users who accept that trade-off.
post-create.sh: chown each new volume root explicitly (find -xdev stops
at the config-volume filesystem boundary and won't descend into them),
guarded with `[ -d ] || continue` so a missing root can't abort
provisioning under set -e.
README: document the topology, what survives vs not, the one-time
first-rebuild masking of pre-existing config-volume sessions, updated
rebuild/reset commands, and the trust-boundary impact.
The devcontainer comments had grown dense and jargon-heavy. Rewrite them
across all 9 files into short, plain-English sentences — same facts and
reasoning, just clearer wording.
Comments only; no code changed. Verified: the diff touches comment lines
only, 25/25 config-transform tests pass, devcontainer.json is still valid
JSONC with build.args + readonly mounts unchanged, shell scripts pass
`bash -n`, and prettier is clean.
Follow-up to a local branch review (run after the cloud review crashed before
producing findings); all 5 confirmed findings were low/nit:
- chown via `find -xdev -exec chown -h`: add -h so chown acts on a symlink
ITSELF, not its target. Without it a dangling node_modules/.bin link aborted
provisioning under `set -e`, and a cross-fs symlink target could be
dereferenced/rewritten. Verified in a clean container (regular files still
chowned; dangling link no longer aborts; cross-fs target untouched). Applied
to install-deps.sh and post-create.sh; the inline comments are corrected to
describe -xdev (descent bound) and -h (no deref) as the two distinct guards.
- Reword the .cjs header claims from "lintable" to "unit-tested and
prettier-checked": ESLint applies no rules to .cjs in this repo; CI only
prettier-checks them.
- README: the initializeCommand is `node ensure-host-config-dirs.cjs`, which
creates the full bind-source set, not a bash `mkdir -p` of four dirs.
- ci-devcontainer.yml: document that the x64 runner exercises only the amd64
Cursor branch; the arm64 sha/URL is hash-pinned (verified against the
published artifact) but not built in CI.
- Make the seed chmod-644 test meaningful: pre-create dst at 0o600 so only the
explicit chmodSync can widen it (the prior assertion passed under the default
umask regardless of whether the chmod ran).
25/25 config-transform tests pass; arm64 + x64 Cursor artifacts verified.
Resolves the blocking + actionable findings from the PR #1875 review:
- Pin base image by digest as bare name@digest [#1]. The :tag@digest form
trips the @devcontainers/cli image-name parser (which builds this image
in CI and in VS Code "Reopen in Container"); bare name@digest is the
parser-compatible form. Verified by a full local build.
- Pin Cursor by version + per-arch sha256 and fetch the artifact directly
instead of executing cursor.com/install; fail-closed on mismatch [#2].
- Mount ~/.config/gh and ~/.docker read-only so a compromised dep can't
rewrite the host GitHub token / Docker credHelper [#4].
- Pin @devcontainers/cli@0.87.0 in the CI smoke [#5].
- chown via find -xdev in install-deps.sh (symlink-safe; matches
post-create.sh) [#6].
- Add filesystem-I/O tests (translate/readHostConfig/seed main/ensurePaths)
and refactor ensure-host-config-dirs to be unit-testable [#7].
- Stop pre-creating settings.json/config.toml on the host; only the real
single-file bind source (.claude.json) is touched [#10].
- Add a prominent top-of-README security callout for the RW write-through
trade-off and reframe the deferred egress firewall as the key missing
compensating control [#3, #9].
Full devcontainer build verified locally (digest pull + pinned Cursor
download/extract/symlink). 24/24 config-transform tests pass.
* feat(go): add builtInNames set to Go language provider
Add GO_BUILT_INS (15 functions, 18 types, 3 values) to the Go
LanguageProvider for parity with the other 13 language providers.
The set is converted to an isBuiltInName predicate by defineLanguage()
and consumed by the type-env return-type lookup to short-circuit
lookups for Go built-in symbols.
* feat(go): add Go 1.18+ and 1.21 predeclared identifiers to builtInNames
Add `clear`, `min`, `max` (Go 1.21 builtins), `any`, `comparable`
(Go 1.18 type aliases), and `iota` (predeclared constant) to
GO_BUILT_INS for complete coverage of the Go specification.
---------
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
- zizmor `artipacked` (CodeQL/GitHub Advanced Security) flagged both
actions/checkout steps in ci-devcontainer.yml: checkout defaults to
persist-credentials:true, leaving GITHUB_TOKEN in .git/config where it
can leak into uploaded artifacts. Both jobs are read-only (run tests /
build smoke, never push), so persist-credentials:false is correct —
matches the repo convention in codeql.yml / ci-tests.yml.
- Ran prettier 3.8.0 over the new .cjs modules + test (single-quote/style
normalization to match the repo). JSON/YAML were already compliant;
README is in .prettierignore; .sh has no prettier parser. Behavior
unchanged — 12/12 transform unit tests still pass.
Multi-agent review (9 reviewers) found the devcontainer files carried
comments + README from the abandoned read-only-symlink design, plus real
behavioral gaps. Resolved all actionable findings (no deferrals).
Documentation drift (the headline — stale comments described a security
model opposite to what shipped):
- README "Trust boundary" claimed a malicious dep "cannot write back …
the read-only /host mount blocks the write." FALSE — the shareable dirs
are RW-bound. Rewrote to document the bidirectional write-through, what
stays one-way (credentials never flow back), and how to close it.
- devcontainer.json mount group-1 comment described "selectively symlinks
… read-only eliminates write-through" — replaced with the RW-bind reality.
- Header "Windows-native is unsupported" -> supported (auto HOME setup).
- containerEnv comment "credentials persist in host-bind-mounted dirs" ->
they live in the named volumes.
- hooks.json exclusion documented honestly as a partial mitigation, not a
clean boundary (commands/agents/skills/rules are equally executing).
- ~/.local "named volume" -> image directory.
Behavioral fixes:
- chown -R recursed into the RW host binds (could rewrite host ownership /
EPERM-abort provisioning on non-UID-aligned Linux). Switched to
`find -xdev` per dir so chown stays on the volume filesystem.
- Cursor installer wrapped in `timeout 300` — its inner binary download
isn't covered by curl --max-time and could hang docker build forever.
- Removed dead CURSOR_VERSION ARG/ENV/build-arg (never consumed; "latest"
implied a pin the installer can't honor). Documented why Cursor is unpinned.
Extraction + tests (the two inline post-create.sh node heredocs were
unlintable and untestable; the path regex had had bugs):
- seed-claude-config.cjs — installMethod-strip seed, now with a non-object
guard (a bare-value/array host .claude.json could otherwise slip the
try/catch and silently re-trigger onboarding) and labeled write errors.
- translate-plugin-registries.cjs — plugin-registry path translation with
labeled errors.
- translate-plugin-registries.test.cjs — 12 tests (Windows/POSIX paths,
cross-CLI isolation, nested objects, non-object/empty-config guard).
- post-create.sh calls the modules via $SCRIPT_DIR.
CI:
- .github/workflows/ci-devcontainer.yml — runs the unit tests + shell
syntax checks + a `@devcontainers/cli build` smoke on .devcontainer/**
changes. Conforms to the repo concurrency convention (validator passes).
Documented (real gaps, fixes are honest docs since no correct auto-fix
exists): user-scope MCP servers with absolute host command paths don't
resolve in-container; user-scope config is copy-on-create so host edits
need a rebuild; in-container plugin installs get shadowed by an empty host
bind on rebuild (recovery noted); plugin installs are single-writer across
checkouts; gh/docker RW-vs-ssh/aws/azure-RO rationale.
Verified: fresh `@devcontainers/cli up` succeeds; installMethod stripped,
registry translated to Linux paths, credentials node:node, 12/12 tests pass.
Codex plugins installed in the container never reached the Windows host
because, unlike Claude, the Codex plugin tree wasn't bind-mounted —
only memories/ and skills/ were. Verified via live /proc/mounts: Claude
binds 6 shareable dirs (incl. plugins/marketplaces + plugins/cache),
Codex bound 2. So `codex plugin add` wrote into the ext4 named volume
and stayed there.
Codex changes:
- Bind the WHOLE ~/.codex/plugins dir + ~/.codex/prompts (plus existing
memories/skills). Strace of two real `codex plugin add` runs proved
the installer stages INSIDE plugins/cache/<marketplace>/ and renames
intra-dir, so a single 9p bind of plugins/ keeps the rename intra-fs —
no EXDEV (the bug that broke single-file binds). .tmp/ stays on the
volume (it's the cross-fs staging source). No path translation needed:
Codex enablement lives in config.toml as git URLs, not FS paths.
- Verified live: `codex plugin add compound-engineering@...` now writes
through to C:\Users\...\.codex\plugins\cache\ on the Windows host, and
host-created files appear in the container (bidirectional).
Cursor changes (review found cursor-agent has a real plugin surface, not
editor-only — Cursor 2.5 Marketplace shared by IDE + CLI):
- Bind plugins/marketplaces, plugins/local, rules, commands, agents,
skills (dir binds, EXDEV-safe).
- Copy-on-create mcp.json (single file → EXDEV-unsafe as bind), alongside
the existing cli-config.json.
- Translate plugins/installed_plugins.json (carries absolute Windows
paths like Claude's) — generalized the existing path-rewrite to run
for both Claude and Cursor.
- hooks.json deliberately NOT shared (runs shell commands → supply-chain
surface); documented as opt-in.
ensure-host-config-dirs.cjs pre-creates all new host bind sources.
post-create.sh defensive symlink cleanup extended to the new Codex/Cursor
paths. README updated with the accurate per-CLI share/sync/translate
matrix.
Design adversarially verified (straced installs, EXDEV primitive tests,
sqlite-under-bind check, path-encoding check) before implementing.
On Docker Desktop Windows the named volumes are ext4 (`/dev/sdd`) while
single-file bind mounts from the Windows host land as 9p (drvfs).
Different filesystems → atomic config writes (write `foo.tmp`, then
rename onto `foo`) trip EXDEV `inter-device move failed` /
`Device or resource busy`.
Codex's TUI surfaces this as `config/batchWrite failed in TUI` when
saving model preference. Claude's writes to settings.json / .claude.json
fail the same way, silently.
Reproduction in container:
$ echo x > /tmp/foo.toml; mv /tmp/foo.toml /home/node/.codex/config.toml
mv: inter-device move failed: ... Device or resource busy
Fix: drop the three single-file bind mounts. Sync host's versions into
the named volume on container-create via `sync_from_host` (same pattern
already used for credentials). Atomic rename within the volume works
because everything is ext4.
Trade-off: container writes to these files no longer propagate to host;
they stay in the volume until next rebuild, which re-syncs from host.
Host is source of truth on rebuild — same model as credentials. Plugin/
skill/agent/memory/command DIRS still bind-mount bidirectionally (atomic
writes within a dir bind stay on one filesystem, no EXDEV).
Files affected:
- ~/.codex/config.toml
- ~/.claude/settings.json
- ~/.claude.json (HOME-level — added `/host/.claude.json` RO mount back
for sync_from_host to read)
* feat(ingestion): resolve FastAPI include_router(prefix=...) cross-file routes
FastAPI sub-route files declare paths via @router.<verb> while the entry
file mounts the router with app.include_router(<router>, prefix='/x').
Previously both the ingestion-layer Route graph nodes and the group-layer
ExtractedContract URLs lost the cross-file prefix, breaking provider <->
consumer matching.
Ingestion layer:
- parse-worker emits routerIncludes / routerImports + decoratorReceiver
- parsing-processor / parse-impl thread the new fields and aggregate
prefixesByModule across chunks; decorator routes whose receiver is
'router' are duplicated once per matching prefix
- routes.ts joins prefix via normalizeExtractedRoutePath
Group layer:
- HttpLanguagePlugin gains an optional prepareRepo() pre-pass and a
repoContext arg to scan(); python.ts builds prefixesByModule and
falls back to the bare path when no entry matches
- http-route-extractor caches one repoContext per plugin
Tests:
- 3 new http-route-extractor cases (attr / named-import / no-prefix)
- ParseWorkerResult literals in 3 test files updated to the new shape
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(ingestion,group): address PR #1877 review — relative imports, cross-package collisions, host names, ingestion tests
Follow-ups to the FastAPI `include_router(prefix=...)` cross-file fix
based on PR #1877's automated production-readiness review. Three
correctness gaps and one test coverage gap addressed:
1. Relative-import support in the worker regex (FINDING 2)
`FROM_IMPORT_ROUTER_RE` now accepts module paths starting with a
`.` (e.g. `from .calls import router as calls_router`). The
previous `[A-Za-z_][\w.]*` rejected leading dots and silently
dropped every relative-import Shape-B include — a real pattern
from the PR description's own motivating example. The matching
helpers now strip leading dots before keying so absolute and
relative imports collapse to the same module key.
2. Cross-package same-name module collisions (FINDING 3)
Two-tier module keying replaces the previous basename-only key:
• short key — `users` (file basename without `.py`)
• long key — `api/users` (parent dir + stem)
`prefixesByLongKey` is consulted first and only falls back to
`prefixesByShortKey` when no long-key match is available. Both
the ingestion pipeline (parse-impl.ts) and the group extractor
(http-patterns/python.ts) carry the same scheme so the graph
nodes and HTTP contracts agree on which prefix applies.
New protocol field `ExtractedRouterModuleAlias` (parse-worker →
parsing-processor → parse-impl) lets Shape-A
`<host>.include_router(<mod>.router, prefix='/x')` calls promote
to a long key when the same file imports `<mod>` via
`from <pkg> import <mod>`. Without this, `api/users.py` and
`admin/users.py` collided on the basename `users` and the admin
file's routes inherited the `/users` prefix that was only meant
for `api/users.py`.
3. Non-`app` host variable names (FINDING 4)
The group-layer `INCLUDE_ROUTER_*_PATTERNS` queries pinned the
host identifier to the literal `"app"` and dropped every
`application = FastAPI()` / `api = FastAPI()` pattern — the
constraint was redundant given that the call shape
(`include_router` invoked with a router argument and a
`prefix=` keyword) is already specific enough. The pin is
removed; the ingestion regex was already unrestricted.
4. Ingestion-layer regression tests (FINDING 1)
The previous PR added group-layer tests
(`http-route-extractor.test.ts`) but zero in-tree tests for the
ingestion path. Two new suites pin the
worker → parse-impl → routes flow:
- `test/unit/fastapi-router-bindings.test.ts` (23 cases):
`extractFastAPIRouterBindings()` is split into a stand-alone
module so it can be unit-tested without booting a worker
thread, then pinned for regex shape, two-tier key emission,
relative-import support, and negative cases.
- `test/integration/fastapi-prefix-pipeline.test.ts` (5 cases)
plus `test/fixtures/fastapi-prefix-app/` — runs the full
`runPipelineFromRepo()` against a realistic multi-package
fixture (containing both `api/users.py` and `admin/users.py`)
and inspects the resulting `Route` graph nodes for cross-file
prefix joining and absence of cross-package bleed.
Verification
- `npx tsc --noEmit`: pass
- PR-touched test suites (6 files / 117 cases): all green
- `npx prettier --check`: pass on touched files
- `npx eslint`: 0 errors on touched files
Cache / compatibility
The new `routerModuleAliases?` field on `ParseWorkerResult` and
`routerModuleAliases` on `WorkerExtractedData` are optional /
guarded with `?? []`, so historical parse-cache entries continue
to load without forced re-scan.
Refs PR #1877.
* refactor(ingestion): move fastapi-router-bindings out of workers/ — pure module, not a worker
Addresses @magyargergo's `CHANGES_REQUESTED` review on PR #1877:
> Sorry I just found that we are introducing a new worker in the PR.
`gitnexus/src/core/ingestion/workers/fastapi-router-bindings.ts` was a
**pure-function module** — it never imported `worker_threads` or
`parentPort`, never spawned a worker, and was never registered as a
worker entry. It was placed in `workers/` purely because it was split
out of `workers/parse-worker.ts` to make its functions unit-testable
without booting a worker thread (parse-worker is itself the worker
entry and cannot be loaded from the main thread).
To remove the misleading directory placement:
• The implementation moves to
`gitnexus/src/core/ingestion/route-extractors/fastapi-router-bindings.ts`,
alongside the other framework-specific route extractors (`expo`,
`nextjs`, `php`, `laravel`, `middleware`, `response-shapes`).
• `workers/parse-worker.ts` keeps a thin re-export so the worker
entry can keep using `extractFastAPIRouterBindings` directly. The
re-export now carries an explicit comment stating that the imported
file is **not** a worker and that the `workers/` directory
deliberately hosts only true worker entries (`parse-worker.ts`,
`worker-pool.ts`, `quarantine.ts`).
• The new file's leading docstring opens with "NOT A WORKER" and
explains why it exists where it does.
• The unit test (`test/unit/fastapi-router-bindings.test.ts`) is
updated to import from the new path.
No behaviour change. The function body, signatures, and exported types
are identical.
Verification
• `npx tsc --noEmit`: pass
• `npx tsc` (dist rebuild): pass
• `test/unit/fastapi-router-bindings.test.ts` (23 cases): all green
• `test/integration/fastapi-prefix-pipeline.test.ts` (5 cases): all green
• `test/unit/group/http-route-extractor.test.ts` (63 cases): all green
• `npx prettier --check` on touched files: pass
• `npx eslint` on touched files: 0 errors
Refs PR #1877.
* refactor(ingestion): drop parse-worker re-exports; consumers import router types directly from route-extractors
Addresses @magyargergo's two remaining review comments on PR #1877:
1. **`gitnexus/src/core/ingestion/workers/parse-worker.ts:247`** —
"Can you please remove them and update the call sites?"
The `export type { ExtractedRouterInclude, ExtractedRouterImport,
ExtractedRouterModuleAlias } from '../route-extractors/...'` block
in parse-worker.ts is gone. The remaining `import type {…}` is
purely local — used only to type the corresponding fields on
`ParseWorkerResult` below — and the leading comment now says so
explicitly ("this file does NOT re-export them"). The
`extractFastAPIRouterBindings` symbol is also no longer re-exported
from parse-worker.ts; it's still imported here so the worker entry
can call it per file, but downstream consumers must reach it via
`route-extractors/fastapi-router-bindings` directly.
Call sites updated:
- `gitnexus/src/core/ingestion/parsing-processor.ts`
- `gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts`
Both files now `import type { ExtractedRouterInclude,
ExtractedRouterImport, ExtractedRouterModuleAlias }` directly from
`route-extractors/fastapi-router-bindings.js`. The worker types
they still need (`ParseWorkerResult`, `ExtractedToolDef`, etc.)
keep coming from `workers/parse-worker.js`.
The unit + integration tests already imported from the new path,
so no test changes were required.
2. **`gitnexus/src/core/ingestion/parsing-processor.ts:168`** —
suggested simplification:
for (const item of result.routerIncludes ?? []) allRouterIncludes.push(item);
for (const item of result.routerImports ?? []) allRouterImports.push(item);
for (const item of result.routerModuleAliases ?? []) allRouterModuleAliases.push(item);
Applied verbatim. Replaces the previous `if (result.…) for …`
guards. The cache-compat semantics are unchanged — historical
parse-cache entries that lack these fields still load cleanly,
the new form just spells the fallback inline.
No behavior change, no tests touched, no public API change.
Verification
• `npx tsc --noEmit`: pass
• `npx tsc` (dist rebuild): pass
• PR-touched test suites (6 files / 117 cases): all green
• `npx prettier --check` on touched files: pass
• `npx eslint` on touched files: 0 errors
Refs PR #1877.
* refactor(ingestion): hoist fastapi-router-bindings type imports to top of parse-worker.ts
Move the `import type { ExtractedRouterInclude, ExtractedRouterImport,
ExtractedRouterModuleAlias }` block to the top of the file with the
other type imports, and drop the comment that previously sat next to
ExtractedDecoratorRoute.
---------
Co-authored-by: henry <zhangwei2017@unipus.cn>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
post-create.sh was doing two unrelated jobs: workspace dependency install
(four `npm install` runs in topological order) and AI CLI credential
sync. They have different lifecycle needs — deps should re-run when
lockfiles change, AI sync should run once per container — but both were
gated on container-create.
Per Dev Container spec lifecycle, `updateContentCommand` is the right
hook for workspace deps: runs at container-create AND on content
changes (lockfile updates). `postCreateCommand` is right for AI CLI
sync: container-create only.
Move steps 3-7 (husky cleanup + four `npm install` runs) into
install-deps.sh wired as `updateContentCommand`. Split the chown step
too — install-deps owns workspace-side dirs (node_modules volumes,
~/.npm), post-create owns AI-side dirs (~/.claude, ~/.codex, ~/.cursor,
/commandhistory, ~/.local). Each script now has one concern.
post-create.sh drops from ~187 lines to 148; install-deps.sh is 56 lines
new. Faster rebuilds when nothing about deps changed (the credential
sync + path translation work still runs every container-create, but the
npm install dance no longer does).
Research backing (no other simplification applies):
- Anthropic's reference devcontainer uses pure named volumes; no
host-state inheritance pattern is published.
- Path translation has no upstream fix (issues #21916, #10379 closed
without resolution). Our Node rewrite is the workaround.
- pnpm workspaces (`pnpm -r install`) would replace the four installs
with one command, but that's a real refactor (touches
gitnexus/scripts/build.js + 4 package.json files); deferred.
- `HUSKY=0` in containerEnv would drop the `rm -rf .husky/_` hack, but
would also stop pre-commit hooks from firing inside the container;
deferred.
A user upgrading from Option B (read-only host stage + symlinks) to the
current hybrid RW-bind topology hit EROFS in post-create.sh when the
plugin registry path-translator tried to write
`/home/node/.claude/plugins/known_marketplaces.json`. The named volume
still carried `/home/node/.claude/plugins -> /host/.claude/plugins`
(Option B's symlink). The new design's sub-path bind mounts at
`plugins/marketplaces` and `plugins/cache` overlay through the symlink,
but writes to the parent dir itself resolve via the symlink to the RO
host stage and fail.
Drop any leftover symlinks at known target paths early in step 2 so the
mkdir/writes that follow land in the volume.
The previous topology bind-mounted the entire `~/.claude/plugins/`
directory from host. That brought through plugins, marketplaces, and
extracted cache content correctly — but ALSO brought through the
registry JSONs (`known_marketplaces.json`, `installed_plugins.json`,
`plugin-catalog-cache.json`) which carry absolute OS-native paths:
"installLocation": "C:\Users\gergo\.claude\plugins\marketplaces\X"
"installPath": "C:\Users\gergo\.claude\plugins\cache\Y\Z"
Claude in the Linux container fails to resolve these Windows paths and
reports `Marketplace X failed to load: cache-miss`.
Split the topology:
- `plugins/marketplaces/` (git clones) and `plugins/cache/` (extracted
plugin files) stay bidirectional RW binds — content is path-independent.
- Registry JSONs move into the per-container named volume. post-create.sh
reads host's versions, rewrites any absolute path ending in
`/.claude/plugins/<rest>` (Windows `C:\Users\...` and POSIX
`/Users/...` / `/home/...` patterns) to `/home/node/.claude/plugins/<rest>`,
and writes the translated result to the volume.
What this gets you:
- Plugin installed on host → next container rebuild has it (translated).
- Plugin installed inside container → lives in volume registry; lost on
rebuild (consistent with credentials model). Re-install on host for
persistence.
ensure-host-config-dirs.cjs now also creates `plugins/marketplaces/` and
`plugins/cache/` on host if absent (Docker rejects bind mounts whose
source doesn't exist).
The previous Option B topology (RO host stage + named volume + symlinks
into the volume) made `/plugin marketplace add` inside the container fail
with EROFS — the symlinks pointed at a read-only mount, so Claude
couldn't create new marketplace dirs. Switch to a hybrid: shareable
content (plugins/skills/agents/memory/commands/settings.json/$HOME/.claude.json
for Claude; config.toml/memories/skills for Codex) gets a direct RW bind
from host so reads and writes go bidirectionally; credentials + the
small identity file stay in per-container named volumes so logout in
container doesn't log out host.
Mount precedence does the heavy lifting: the named volume mounts at
/home/node/.<cli> first, then sub-path bind mounts overlay specific
sub-paths. Container's view at /home/node/.claude/plugins/ is the host
dir; container's view at /home/node/.claude/.credentials.json is the
named volume's file.
What this gives you:
- /plugin marketplace add in container = installed on host
- New skill on host = visible in container immediately (no rebuild)
- claude logout in container = host stays logged in
- compound-engineering plugin enabled on host = enabled in container
- Theme picker fires once (or never if host has theme set)
What it costs:
- Write-through: a compromised npm dep in workspace deps can write to
host ~/.claude/{plugins,skills,agents,memory,commands}/. Documented
trade-off; for personal dev, accepted. Credentials still per-container.
post-create.sh becomes much simpler — only syncs the four credential
files from host into the named volumes. No more symlink dance, no more
state-file merging.
ensure-host-config-dirs.cjs gains the new bind sources: the shareable
subdirs and settings.json/config.toml files get mkdir/touched on host
so Docker doesn't reject the mount when a CLI has never been used.
Two changes that together give the container the same plugins and configs
as the host for all three AI CLIs (login stays per-container):
1. Drop CLAUDE_CONFIG_DIR from containerEnv. The named-volume mount target
`/home/node/.claude` already matches Claude's default `~/.claude`, 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 that
does NOT carry `hasCompletedOnboarding`); without it, Claude reads
`$HOME/.claude.json` (the big onboarding-state file that does). The
wizard fires every container-create when set, skips when unset.
2. Sync `settings.json` from host (Claude) + symlink `memories/` and
`skills/` from host (Codex). Theme + `enabledPlugins` +
`extraKnownMarketplaces` live in `settings.json` — without syncing
it, the theme picker fires and host-installed plugins stay disabled
even though their files are symlinked in. Codex's `memories/` and
`skills/` are the symmetric Codex user-installed surface, now shared
the same way Claude's plugins/skills/agents/memory/commands are.
Cursor stays as-is — `cli-config.json` conflates auth+settings (already
synced), and there's no separate plugin surface to mirror.
Login details remain per-container by design (acceptable to re-login on
rebuild). Everything else — plugins, skills, agents, memory, MCP user-
scope config, project trust, theme, plugin enablement — now matches
host on every container-create.
* feat(impact): per-symbol processes field on byDepth items
Today `impact` returns aggregated `affected_processes` at the top level
but the per-symbol `byDepth` items don't say which processes each caller
participates in. Consumers planning a deploy want to know if a given
caller is hit by a daily cron, a webhook, or a user-facing route - each
is a different deploy-risk profile - and that information requires a
follow-up cypher query per symbol today.
This change attaches `processes: [...]` to every `byDepth[depth][i]`
item, listing the processes that symbol participates in:
byDepth: {
"1": [
{
depth: 1,
id: "Function:src/foo.ts:doStuff",
name: "doStuff",
...
processes: [
{ id: "proc:cron_daily", label: "Daily cron",
processType: "cron", step: 12 }
]
}
]
}
The list is empty for symbols not in any process. Additive change, no
breaking modifications to existing fields.
Implementation:
- A second chunked Cypher pass runs after the existing per-process
aggregation pass, returning per-(symbol, process) rows. Same chunk
size and MAX_CHUNKS as the aggregation pass, so worst-case adds 10
extra round-trips bounded by the same env var.
- The enrichment pass is skipped entirely when `affectedProcesses.length
=== 0` (nothing to enrich) or `summaryOnly === true` (byDepth not
returned anyway).
- The aggregation query is unchanged - the new query has a distinct
RETURN shape (`RETURN s.id AS sid, ...`) so an existing unit test that
counts STEP_IN_PROCESS chunks was narrowed to match only the
aggregation pattern.
Tests:
- New: byDepth items always have a `processes` field (default empty
when no STEP_IN_PROCESS edges exist).
- New: when STEP_IN_PROCESS rows exist, the matching byDepth item
carries the right `{id, label, processType, step}` entry.
- Updated: impact-batching-grouping test mock narrowed to count only
aggregation chunks (the new per-symbol pass is covered separately).
* style: apply prettier to gitnexus/src/mcp/local/local-backend.ts
Pure line-wrap fix flagged by quality / format CI on PR #1867. Zero
semantic change: prettier broke a chained .slice().map() across three
lines instead of one. No test changes, no logic changes.
* fix(impact): address PR review findings on per-symbol process enrichment
- byDepth.processes doc now states each item carries processes (Finding 1)
- move per-symbol STEP_IN_PROCESS enrichment post-pagination so symbols
beyond the pre-pagination cap no longer get false-empty processes:[]
(Finding 2); hoist CHUNK_SIZE/MAX_CHUNKS to function scope so the
post-pagination pass can reference them
- dedup per-symbol query with DISTINCT + MIN(r.step) per (symbol,process)
pair (Finding 3)
- suppress the per-symbol pass under summaryOnly, incl. impactByUid group
fan-out, plus a test asserting the query never fires (Findings 4, 6)
* fix(impact): address second-round review findings A-E
Finding A (blocker): impactByUid passed summaryOnly:true, which drops the
entire byDepth field. cross-impact.ts reads fan.byDepth to build the group
by_depth output, so cross-repo by_depth was always {}. Replace with a new
skipPerSymbolEnrichment option on _runImpactBFS that suppresses only the
per-symbol STEP_IN_PROCESS pass while preserving byDepth.
Finding B+D (blocker): rewrite the byDepth.processes tool description. Drop
the stale "enrichment cap" wording (no longer true post-pagination), document
the {id,label,processType,step} entry shape, and tell agents to cross-check
affected_processes when partial:true.
Finding C: bound the post-pagination per-symbol enrichment loop to
MAX_CHUNKS*CHUNK_SIZE page IDs and surface partial:true when capped, so a
large page cannot trigger unbounded DB round-trips (DoD 2.6).
Finding E: add a test exercising the real impactByUid -> _runImpactBFS path
asserting byDepth survives and the per-symbol query never fires.
---------
Co-authored-by: scotjelinski <58397194+scotjelinski@users.noreply.github.com>
Co-authored-by: Gergő Magyar <gergomagyar@icloud.com>
README still described the old "first-run copy" behavior. After the
post-create.sh change to always-sync-from-host, the design works either
direction:
- Log in on host → next container-create syncs the credentials into the
named volume.
- Log in inside the container → the named volume persists the login across
rebuilds; the host has no source to overwrite from, so it stays alone.
Also documents the two-Claude-state-files trap (`$HOME/.claude.json` AND
`$CLAUDE_CONFIG_DIR/.claude.json`, both with the same userID required), and
the volume-deletion recovery path for stale named volumes carried over
from earlier rebuilds.
Two bugs were causing Claude Code to fire the onboarding wizard inside the
container even with valid host credentials:
1. Missing the second state file. Claude Code 2.1.x writes a small `.claude.json`
INSIDE `CLAUDE_CONFIG_DIR` (carrying migration tracking + userID), not just the
one at `$HOME/.claude.json`. If the userIDs in the two files disagree, Claude
treats the session as inconsistent and re-onboards. The previous post-create.sh
only copied the `$HOME` one.
2. First-run guards (`[ ! -e $dst ]`) skipped the copy when stale named volumes
from earlier rebuilds still had the prior session's state in them, leaving the
container desynced from the host.
Replace `copy_on_first_run` with `sync_from_host` that always overwrites from
host on container-create. `link_readonly_share` now clears stale non-symlink dst
entries before linking. Copies both `$HOME/.claude.json` and
`$CLAUDE_CONFIG_DIR/.claude.json` so userIDs stay aligned. Container can still
mutate its own state between rebuilds; resync only happens on rebuild
(postCreate boundary).
Restructure the Claude Code / Codex / Cursor mount topology to fix the
silent first-run-UI bug surfaced in PR testing, and to harden against
the host-write-through escape class the previous bind-mount design
exposed.
The actual root cause of the first-run wizard firing on the user's
screenshot — confirmed via three parallel research agents (best
practices, framework docs deep dive of the OpenAI Codex Rust source,
adversarial design review) — was NOT a credential permission check.
Claude Code splits state across `~/.claude/.credentials.json` AND
`~/.claude.json` (a FILE at $HOME, sibling of the `.claude/` dir).
The latter holds `hasCompletedOnboarding`, `userID`, `oauthAccount`
metadata, MCP user-scope config, and per-project trust state — and
Claude Code reads it at literal `$HOME/.claude.json`, not via
`CLAUDE_CONFIG_DIR`. The previous design mounted `~/.claude/` but
left `~/.claude.json` outside the topology entirely, so every container
started with a missing onboarding-state file and re-ran the wizard.
Confirmed by tfvchow/field-notes-public#10:
"Persisting .credentials.json alone is NOT sufficient. Without
.claude.json, Claude Code treats the session as a fresh install and
prompts for login regardless of valid credentials being present."
The new topology:
**Mounts**
- `${localEnv:HOME}/.claude` → `/host/.claude` (read-only bind)
- `${localEnv:HOME}/.codex` → `/host/.codex` (read-only bind)
- `${localEnv:HOME}/.cursor` → `/host/.cursor` (read-only bind)
- `${localEnv:HOME}/.claude.json` → `/host/.claude.json` (read-only bind)
- `claude-config-${devcontainerId}` → `/home/node/.claude` (named volume)
- `codex-config-${devcontainerId}` → `/home/node/.codex` (named volume)
- `cursor-config-${devcontainerId}` → `/home/node/.cursor` (named volume)
**containerEnv** gains `CODEX_HOME=/home/node/.codex` (Codex's own env
override, per its public Rust source). `CLAUDE_CONFIG_DIR=/home/node/
.claude` was already set.
**`post-create.sh`** stages the named volumes on first run:
- Symlinks shareable subdirs from `/host/.claude` into the named volume:
`plugins/`, `skills/`, `agents/`, `memory/`, `commands/`. Codex gets
`config.toml` symlinked. Cursor has no shareable subdirs (cli-config
.json conflates auth and settings).
- Copies `.credentials.json`, `auth.json`, `cli-config.json` on first
run with `chmod 600`. After first run, container manages its own
refresh; host's credentials untouched.
- Copies `~/.claude.json` on first run (with stub
`{"hasCompletedOnboarding":true,"installMethod":"global"}` fallback
for hosts that haven't run Claude Code). This is the fix for the
observed onboarding-wizard loop.
`ensure-host-config-dirs.cjs` now also touches `~/.claude.json` on the
host if missing, so the bind mount has a valid source on hosts that
have never run Claude Code.
**Why read-only + named volume vs. the previous full bidirectional
bind mount:**
1. **Host filesystem write-through escape, eliminated.** Previous
design symlinked `plugins/`, `agents/`, `skills/` write-through
into the host's `~/.claude/` — a malicious npm package in the
workspace dep tree could drop `agents/evil.md` into the host's
config, which the next host Claude session would auto-load. The
read-only `/host` mount blocks this; container compromise no
longer persists across teardown via host-side autoload.
2. **Windows bind-mount perm-flattening, sidestepped.** Files
surfaced through a Docker Desktop Windows bind mount appear as
`root:root` mode `777`. Credentials in the named volume come with
proper Linux ownership and `chmod 600` — what each CLI expects on
write (none enforces on read, but write-side hygiene matters for
the host's understanding of "where credentials live").
3. **No `ide/` lock-file collisions.** Previous design symlinked
`~/.claude/ide/` write-through, including per-PID lock files. Host
PID and container PID namespaces are unrelated → lock-file PIDs
misclassify dead processes as alive. Skipping `ide/` keeps lock
files container-local.
4. **No `projects/` ghost dirs.** Host encodes the workspace path as
`D--development-coding-GitNexus`, container as `-workspace`.
Bidirectional `projects/` symlinks would split memory and session
state across two ghost project dirs for what is conceptually the
same project. Skipping `projects/` keeps per-project state
container-local; host's projects/ stays untouched.
5. **No `settings.json` version drift.** Container is pinned to a
specific Claude Code version (`CLAUDE_CODE_VERSION` build arg);
host floats with auto-update. Bidirectional `settings.json` writes
produced silent schema rollback. Skipping settings.json keeps each
side authoritative for its own version.
**README** rewritten in the same section to describe the new topology
honestly: what's shared, what isn't, the OAuth refresh-token
divergence between host and container, per-CLI quirks (macOS Keychain
storage, Cursor's known upstream in-container auth bug, Codex
keyring storage). Trust-boundary section updated to name the threat
model accurately — same read surface as before (malicious dep can
still READ all credentials), but write-through into host plugin/agent
dirs is now blocked.
Verified locally: `@devcontainers/cli read-configuration` resolves all
19 mounts correctly on Windows, `post-create.sh` parses, and
`ensure-host-config-dirs.cjs` idempotently touches `~/.claude.json`.
Research backing this design:
- Anthropic Claude Code devcontainer docs (named-volume pattern):
https://code.claude.com/docs/en/devcontainer
- tfvchow/field-notes-public#10 (both files required):
https://github.com/tfvchow/field-notes-public/issues/10
- anthropics/claude-code#29029 (VS Code extension strips
hasCompletedOnboarding):
https://github.com/anthropics/claude-code/issues/29029
- OpenAI Codex Rust source (no read-side perm check):
https://github.com/openai/codex/blob/main/codex-rs/login/src/auth/storage.rs
- Cursor CLI in-Docker auth issue:
https://forum.cursor.com/t/cursor-agent-authentication-issue-inside-docker/143995
Extend the host bind-mount surface so coding agents inside the container
inherit cloud + container-registry auth from the host without any
per-container setup:
- ~/.docker (read-write) — Docker registry auth (config.json) + buildx
config. Container-registry pushes (ghcr.io, docker.io) from inside the
container pick up host `docker login` state. Read-write because the
Docker CLI refreshes credential-helper tokens.
- ~/.aws (read-only) — AWS CLI / SDK credentials. Read-only because
rotating creds typically happens via the host. Empty on this dev box,
so forward-compatible: the moment you `aws configure` on the host the
container picks it up on the next rebuild.
- ~/.azure (read-only) — Azure CLI credentials. Same pattern as ~/.aws.
`ensure-host-config-dirs.cjs` extends to mkdir these three on init so
the bind mounts always have a valid source even if a CLI has never been
used on this host.
The Docker CLI itself isn't installed in the container by default — the
~/.docker/ mount is inert until you add `docker-outside-of-docker:1` or
similar Feature. README now calls this out under "What you still don't
have inside the container" so it's obvious which CLIs are agent-ready
and which need a feature add to become useful.
README updates:
- Bind-mount table gains a "Why" column and rows for the three new
mounts, making it clear at a glance what each one enables.
- Trust-boundary section lists Docker registry tokens, AWS, and Azure
creds in the read-side exfil path so the threat model stays honest as
the credential surface grows.
- New subsection lists not-included CLIs (Docker, AWS, Azure, gcloud,
kubectl, private-npm) with the exact Feature ID or mount snippet
needed to enable each — turns "I want my agent to do X" into a
one-line config change.
Verified locally: `npx @devcontainers/cli read-configuration` resolves
all 9 host bind mounts to valid C:\Users\<name>/* paths on Windows.
VS Code's Dev Containers extension auto-copies the host's gitconfig into
the container at attach time using `(dd ...) >> /home/node/.gitconfig`.
A read-only bind mount of ~/.gitconfig blocks that write, so attach
failed with `cannot create /home/node/.gitconfig: Read-only file system`.
Making it read-write would let the append succeed, but the bind mount
means the host file and the container file are the same file — VS Code's
append would double the host gitconfig contents on every container
start.
Drop the ~/.gitconfig bind mount entirely. VS Code's auto-copy is the
purpose-built mechanism for this, gives the container the host's
user.name / user.email transparently, and avoids both the read-only
write failure and the append-duplication trap. The container ends up
with a writable /home/node/.gitconfig that's a copy of the host's, not
a mount.
The remaining six bind mounts (.claude, .codex, .cursor, .ssh, .config/git,
.config/gh) keep their existing modes — XDG-style git config under
~/.config/git is unaffected by VS Code's auto-copy (which only targets
~/.gitconfig), so its read-only bind mount stays.
Also remove the `.gitconfig` touch from ensure-host-config-dirs.cjs
(now unnecessary) and update the README CLI-state table, sharing
explanation, and troubleshooting row to reflect that gitconfig flows
in via VS Code auto-copy rather than the bind mount.
Reverses the "WSL2 required on Windows" posture. Windows-native now
works after a one-time auto-handled setup.
The root cause of the bind-mount failure: VS Code resolves
`${localEnv:HOME}` by reading its own process env, and Windows doesn't
set `HOME` by default — Windows uses `USERPROFILE`. So the bind sources
were collapsing to `/.claude`, `/.codex`, etc., and Docker rejected them.
`ensure-host-config-dirs.cjs` now handles this automatically on Windows
hosts where `HOME` is unset:
1. Runs `setx HOME "%USERPROFILE%"`, which writes to the user-level
Windows environment (HKCU\Environment) — no admin required. Every
future user process inherits HOME from there.
2. Prints a clear one-time setup banner explaining the user needs to
fully restart VS Code (File > Exit, not just close the window) for
VS Code to pick up the new env at its next startup.
3. Exits 1 so VS Code surfaces this as a clean container-create failure
instead of letting Docker error opaquely later.
On the second Reopen-in-Container attempt, `HOME` is now set in VS
Code's env, the script skips the setup block, creates the bind-mount
source dirs, and the container builds normally. Subsequent rebuilds
have no extra steps.
Mac, Linux, and WSL2 hosts have `HOME` set by the shell, so the new
block is a no-op there. Same `devcontainer.json` works across all
supported hosts.
README rewritten to reflect the new posture:
- Header lists Windows 11 (native) as a supported host alongside macOS,
Linux, and WSL2, with a note that Windows-native gets a one-time
HOME setup handled by the initializeCommand.
- New "Windows 11 setup" section walks through the auto-handled setup
flow + a manual `setx HOME "%USERPROFILE%"` fallback for users who
want to do it themselves.
- "Known trade-offs of Windows-native vs WSL2" subsection lays out the
Docker Desktop Windows bind-mount edge cases (file watchers, npm
install perf, husky/_ EPERM) so users opting into Windows-native do
so eyes-open. WSL2 remains documented as the faster path for users
who want it, but it's no longer the only supported one.
- Troubleshooting table gets two new rows: the one-time setup banner
(with "what to do" instructions) and the residual `bind source path
does not exist` case (run setx manually + fully exit VS Code).
The previous commit's "Windows-native works" softening was wrong. VS Code
on Windows-native resolves `${localEnv:HOME}` by reading the host shell's
HOME env var, and cmd.exe has no HOME set — the bind sources collapse to
`/.claude`, `/.codex`, etc., and Docker errors:
Error response from daemon: invalid mount config for type "bind":
bind source path does not exist: /.claude
The @devcontainers/cli output that prompted the softening was misleading
because I ran it from a Bash session with HOME already set, not from VS
Code's cmd.exe call context. The original Finding-1 P0 — that Windows-
native silently breaks the bind-mount feature — was correct.
Three changes:
1. `ensure-host-config-dirs.cjs` detects the failure mode early:
`if (process.platform === 'win32' && !process.env.HOME)` prints a
targeted error message naming the root cause (cmd.exe has no HOME →
${localEnv:HOME} resolves empty → bind sources fail) and a step-by-step
pointer to set up WSL2. Exits 1 so VS Code surfaces it as a clean
container-creation failure, not the cryptic Docker bind-mount error.
2. README header reverted to "Windows 11 via WSL2" only (not "and
Windows-native"). The "Windows 11 — WSL2 is required" section names
the specific HOME-resolution mismatch concretely so future readers
understand why the constraint exists.
3. Troubleshooting table gets a new row for the `ERROR: GitNexus
devcontainer requires WSL2` message pointing at the setup section.
Two fixes bundled:
1. The previous commit's OS-keyed `initializeCommand` object was based
on a misread of the Dev Containers spec. The object form on command
properties is **named parallel tasks**, not OS dispatch — VS Code ran
all three keys in parallel via cmd.exe on Windows, the POSIX branches
failed, and container creation aborted before Docker was invoked.
Restore the single-string Node-based form:
`node .devcontainer/ensure-host-config-dirs.cjs`. Node works
identically in cmd.exe on Windows and bash/zsh on Linux/macOS/WSL,
and `os.homedir()` respects $HOME on POSIX and %USERPROFILE% on
Windows. The script is idempotent (mkdirSync recursive is a no-op
for existing dirs; touch is gated on .gitconfig existence).
Document Node ≥18 on the host as the only host-side prerequisite
beyond Docker Desktop and the VS Code Dev Containers extension.
Anyone running Claude Code on the host already has it.
2. Extend the host-bind mount surface with `~/.ssh` and `~/.config/git`,
both read-only:
- `~/.ssh` lets commit signing + push over SSH remotes work inside
the container without copying private keys. Read-only mount means
container code can read keys but can't modify or delete them.
(Threat: a malicious dep can still read private keys from inside
the container; the read-only mount narrows write-side blast
radius, not read-side. Documented in the trust-boundary section.)
- `~/.config/git` covers XDG-style git config (`~/.config/git/config`,
`~/.config/git/ignore`, `~/.config/git/attributes`) for users who
keep settings there instead of `~/.gitconfig`. Read-only, same as
`~/.gitconfig`.
Update the CLI-state-sharing table and trust-boundary paragraph to
reflect the expanded surface.
Re-adds .devcontainer/ensure-host-config-dirs.cjs (deleted before the
OS-keyed attempt).
The previous commit's `initializeCommand` was POSIX-only (`mkdir -p $HOME/...`).
VS Code on Windows runs the host shell as `cmd.exe /c ...`, which can't
parse POSIX syntax — `$HOME` doesn't expand, `mkdir -p` errors, the init
fails with `The syntax of the command is incorrect`, and container
creation aborts before Docker is invoked.
Switch `initializeCommand` to the spec's OS-keyed object form:
- linux/darwin (covers WSL2 because VS Code runs initializeCommand in
the WSL shell when attached via the WSL extension): POSIX mkdir+touch,
as before
- win32: PowerShell snippet that creates the same directories under
$USERPROFILE and touches the gitconfig if missing
Soften the README's hard "WSL2 required" framing from the previous
commit. Reality per `@devcontainers/cli read-configuration` output:
`${localEnv:HOME}` on Windows-native resolves to `C:\Users\<name>`
(VS Code falls back to USERPROFILE), so the bind mount sources are
valid Windows paths and Docker Desktop handles the translation. The
earlier `accessing specified distro mount service` failure was a
separate Docker Desktop WSL-integration issue, not a HOME-resolution
issue. Windows-native works; it's just slower with more bind-mount
permission edge cases (the husky/_/h EPERM class). The README now
explains the tradeoff and steers toward WSL2 for performance + file
watchers + permission reliability, rather than blocking Windows-native
checkouts outright.
Update the troubleshooting row to reflect the new posture.
Walkthrough resolution of the 16-finding ce-code-review on PR #1875. 15 of
16 findings applied; one (F12, Anthropic Feature floating tag) was
superseded by F6's Feature removal.
P0
- F1: WSL2 is now REQUIRED for Windows hosts, not just recommended.
${localEnv:HOME} resolves to empty string on Windows-native (no HOME env
var) — bind mounts then point at /.claude, /.codex etc. and silently
break. ensure-host-config-dirs.cjs wrote to USERPROFILE-derived paths
via os.homedir(), so the two surfaces disagreed about which env var was
"home" on Windows. README header reframed; "Windows 11 — WSL2 is required"
section explains the mismatch concretely.
P1
- F2: Workspace `node_modules` volume names now include `-${devcontainerId}`
so two GitNexus checkouts on the same host (~/work/GitNexus and
~/projects/GitNexus) don't share volumes and corrupt each other's
installs.
- F3 + F5: `postCreateCommand` extracted to `.devcontainer/post-create.sh`
with `set -euo pipefail` and six labeled echo steps so failure logs
name the step instead of an opaque &&-chain index. Chown step extended
to cover /home/node/.npm, /commandhistory, and /home/node/.local — these
named-volume mount points were owned by build-time UID 1000 but the
container's `node` is re-IDed at runtime by updateRemoteUserUID on
non-1000 Linux hosts, leaving them unwritable until now.
- F4: Cursor installer downloaded to a temp file with curl --retry +
--max-time; sha256 logged to build output before execution so drift
across rebuilds is visible in CI logs. Full hard-pin (to a versioned
downloads.cursor.com tarball with verified sha256) tracked as a
follow-up in README "What's not included".
P2
- F6: Anthropic Feature replaced with a direct
`npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}` so
CLAUDE_CODE_VERSION actually pins the installed binary (the Feature
ignored the ARG and pulled latest at install time). Honors the
earlier "pin known-good versions" decision and resolves F12's
floating-tag concern for this Feature.
- F7: Dockerfile ARG defaults dropped for the three version vars;
`devcontainer.json` `build.args` is now the single source of truth.
Standalone `docker build .devcontainer/` must pass --build-arg.
- F8: ensure-host-config-dirs.cjs deleted; `initializeCommand` now uses
POSIX `mkdir -p` + `touch ~/.gitconfig` directly, dropping the
host-Node-on-PATH prerequisite that broke on fresh Windows+Docker
Desktop installs without Node.
- F9: ~/.gitconfig bind-mounted read-only so `git commit` inside the
container uses the host's user.name / user.email. Read-only so
container-side `git config --global` doesn't leak to host.
- F10: ~/.config/gh bind-mounted (read-write) so `gh pr create` /
`gh pr checks` / `gh issue create` work inside the container without
re-auth. AGENTS.md's commit + PR workflow now fully functional for
agents inside the container.
- F11: CLAUDE_CONFIG_DIR removed from Dockerfile ENV; canonical value
lives only in devcontainer.json containerEnv. Eliminates the two-file
edit risk.
- F13: Mounts comment now documents per-instance vs per-workspace-name
scoping rationale so future contributors don't guess.
- F14: README "Trust boundary, concretely" paragraph names the exfil
path explicitly (malicious npm postinstall → OAuth tokens →
~/.claude/projects/<workspace>/memory/MEMORY.md secrets) and lists
vendor-side rotation runbook entries.
P3
- F15: Dockerfile pre-create + chown of /home/node/.claude, .codex,
.cursor dropped — those paths are bind-mounted, which fully shadows
any image-side ownership. Only .npm, .local, /commandhistory still
benefit from the pre-create.
- F16: README "Bumping CLI versions" section rewritten against the
post-F6 reality: CLAUDE_CODE_VERSION and CODEX_VERSION are real
pins; CURSOR_VERSION is informational only.
Verified locally: `docker build .devcontainer/ --build-arg ...` succeeds.
Smoke-tested image: `claude --version` (2.1.153), `codex --version`
(0.134.0), `cursor-agent --version` all resolve as the non-root `node`
user; named-volume mount points (/home/node/.npm, /commandhistory) are
node-owned at build time so non-1000 host UIDs get the post-create.sh
chown fix instead of EACCES.
Switch the credential/config mounts from per-devcontainer named volumes
to bind mounts of `${localEnv:HOME}/.claude`, `~/.codex`, and
`~/.cursor`. Effect inside the container:
- Authentication is shared with the host. If you've already run
`claude login` / `codex login --device-auth` / `cursor-agent login`
on the host, you're already authenticated in the container.
- Plugins, skills, agents, memory, and settings sync both ways. Install
a plugin in the container, it shows up on the host; add a custom
agent on the host, the container sees it immediately.
- All devcontainers on the host share the same CLI state, mirroring
how host shells already share it. (Per-workspace isolation of plugins
was never a stated requirement; the previous per-devcontainer named
volumes leaked nothing useful.)
Add `.devcontainer/ensure-host-config-dirs.cjs` and wire it as
`initializeCommand`. It runs on the host before container create and
guarantees `~/.claude`, `~/.codex`, `~/.cursor` exist, so Docker doesn't
reject the bind mount when a CLI has never been used on this host.
Cross-platform via Node `os.homedir()` + `fs.mkdirSync({recursive: true})`;
idempotent; no third-party deps.
Update `.devcontainer/README.md`:
- New "How CLI state is shared with your host" section explaining the
bind-mount model up front so users know their host plugins/skills/
memory carry into the container.
- Mark first-time-login section as skippable when the user is already
authenticated on the host.
- Note the high-trust escape hatch: replace the three bind mounts with
`type=volume` named volumes if the host/container trust boundary
needs to be separated (Anthropic's reference pattern for enterprise).
- Replace the obsolete "rm named volume" troubleshooting row with one
that covers EACCES/EPERM on the host-bind-mount path.
When `npm install` runs the root `prepare` script (husky), husky tries
to copyfile `node_modules/husky/husky` → `.husky/_/h`. On Docker Desktop
Windows bind mounts, if `.husky/_/` already exists from a prior
container run, the new container's `node` user can't overwrite it via
the bind mount's permission translation and the install fails with:
Error: EPERM: operation not permitted, copyfile
'/workspace/node_modules/husky/husky' -> '.husky/_/h'
Drop `.husky/_` defensively in `postCreateCommand` before `npm install`
so husky always starts from a clean slate. `.husky/_` is a husky
runtime cache (gitignored), so removing it has no effect on the repo —
husky regenerates it. No-op for WSL2-side checkouts (where this class
of bind-mount permission collision doesn't occur).
Add a troubleshooting row to `.devcontainer/README.md` covering the
manual recovery (`rm -rf .husky/_` on the host) and the long-term fix
(clone in WSL2 — Windows-side bind mounts will keep biting on this
kind of issue across rebuilds with different UID alignment).
The previous order (root → gitnexus-shared → gitnexus → gitnexus-web)
broke at the `gitnexus` install step because `gitnexus`'s `prepare`
script runs `scripts/build.js`, which compiles `gitnexus-web` whenever
its source tree exists. In the devcontainer the entire workspace is
bind-mounted, so `gitnexus-web/` is present from the start — but its
`node_modules/` wasn't yet, so `tsc -b` failed with:
error TS2688: Cannot find type definition file for 'vite/client'
error TS2688: Cannot find type definition file for 'node'
Reorder so `gitnexus-web` installs before `gitnexus`. Verified
end-to-end via `npx @devcontainers/cli up`: container builds clean,
all three CLIs (Claude 2.1.153, Codex 0.134.0, Cursor) respond, and
`npx tsc --noEmit` inside `/workspace/gitnexus` passes.
Production Dockerfiles (`Dockerfile.cli` etc.) don't hit this because
they only COPY `gitnexus/` + `gitnexus-shared/`, so `gitnexus-web/`
doesn't exist at install time and `scripts/build.js` skips the web
step. The devcontainer's full-tree bind mount changes that calculus.
