Submodule cutover: remove vendored upstream TS sources, add migration helpers and docs

.github/workflows/dev-containers.yml

@@ -19,6 +19,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - uses: actions/setup-node@v5
       with:
         node-version: '20.x'
@@ -69,6 +71,8 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - name: Setup Node.js
       uses: actions/setup-node@v5
       with:
@@ -117,6 +121,8 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - name: Setup Node.js
       uses: actions/setup-node@v5
       with:
@@ -151,6 +157,8 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
     - uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - name: Run install.sh tests
       run: sh scripts/install.test.sh
 

.github/workflows/standalone-prototype.yml

@@ -14,6 +14,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          submodules: recursive
 
       - name: Setup Node.js
         uses: actions/setup-node@v5

.github/workflows/standalone-release.yml

@@ -17,6 +17,8 @@ jobs:
       NODE_VERSION: '20.19.1'
     steps:
       - uses: actions/checkout@v4
+        with:
+          submodules: recursive
 
       - name: Setup Node
         uses: actions/setup-node@v4

.github/workflows/test-docker-v20.yml

@@ -17,6 +17,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
+      with:
+        submodules: recursive
 
     - uses: actions/setup-node@v5
       with:

.github/workflows/test-docker-v29.yml

@@ -17,6 +17,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v6
+      with:
+        submodules: recursive
 
     - uses: actions/setup-node@v5
       with:

.github/workflows/test-windows.yml

@@ -52,6 +52,8 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - name: Setup Node.js
       uses: actions/setup-node@v5
       with:

.gitmodules

@@ -1,3 +1,4 @@
 [submodule "upstream"]
 	path = upstream
 	url = https://github.com/devcontainers/cli
+	branch = main

AGENTS.md

@@ -21,3 +21,8 @@ When asked to update upstream:
 ## Pathing expectations
 - Tests, scripts, and docs that need upstream assets should reference paths under `upstream/...` explicitly.
 - Avoid hardcoded assumptions that upstream files exist at repository root.
+
+## Submodule bump checklist
+- Use `git submodule update --init --recursive` before running migration/parity checks.
+- Record the new pinned revision with `git rev-parse HEAD:upstream` in PR notes/tests when changing compatibility behavior.
+- Keep submodule updates reviewable by separating the submodule pointer bump from project-owned compatibility fixes when practical.

README.md

@@ -21,6 +21,12 @@ If you clone this repository without submodules, initialize them before building
 git submodule update --init --recursive
 ```
 
+To inspect the exact compatibility target currently pinned by this repo:
+
+```bash
+git rev-parse HEAD:upstream
+```
+
 ## Context
 
 A development container allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.

TODO.md

@@ -182,10 +182,14 @@ This balances near-term user value with long-term maintainability.
 Move all vendored upstream TypeScript CLI sources out of repo root and treat `upstream/` (git submodule) as the canonical upstream baseline we target for compatibility.
 
 ### 1) Repository layout and ownership
-- [ ] Confirm `upstream/` is the only place where upstream devcontainers/cli code lives.
-- [ ] Remove duplicated upstream-owned files currently checked in at repository root once replacements are wired.
-- [ ] Keep only project-owned integration/porting assets at repository root (Rust code, migration docs, compatibility harness, and project-specific tests).
-- [ ] Add/refresh `.gitmodules` and contributor guidance so updating upstream is intentional and reviewable.
+- [x] Confirm `upstream/` is the only place where upstream devcontainers/cli code lives.
+  - Added `collectDuplicateUpstreamPaths(...)` + `evaluateUpstreamSubmoduleCutoverReadiness(...)` with tests so duplicate upstream-owned paths outside `upstream/` are detected from filesystem layout.
+- [x] Remove duplicated upstream-owned files currently checked in at repository root once replacements are wired.
+  - Removed root-level duplicated TypeScript sources/tests that are now sourced exclusively from `upstream/` for upstream-owned logic.
+- [x] Keep only project-owned integration/porting assets at repository root (Rust code, migration docs, compatibility harness, and project-specific tests).
+  - Root `src/` now contains only migration/readiness contract helpers and project-owned tests.
+- [x] Add/refresh `.gitmodules` and contributor guidance so updating upstream is intentional and reviewable.
+  - `.gitmodules` now pins the `upstream` submodule branch and README/AGENTS document explicit submodule update workflow.
 
 ### 2) Build/test path migration
 - [ ] Audit all test fixtures, scripts, and build commands that currently reference root-level upstream paths.
@@ -194,7 +198,8 @@ Move all vendored upstream TypeScript CLI sources out of repo root and treat `up
 - [ ] Ensure CI jobs execute against `upstream/` sources and fail fast when submodule is missing/uninitialized.
 
 ### 3) Compatibility target versioning
-- [ ] Define the compatibility contract as: “this repo targets the exact commit pinned in `upstream/`.”
+- [x] Define the compatibility contract as: “this repo targets the exact commit pinned in `upstream/`.”
+  - Added `resolvePinnedUpstreamCommit(...)` and `formatUpstreamCompatibilityContract(...)` helpers (with tests) to make the pinned-commit contract explicit and machine-resolvable.
 - [ ] Expose the pinned upstream commit in test output/logging for traceability.
 - [ ] Add a dedicated CI check that reports diffs/regressions when submodule commit changes.
 - [ ] Create an “update upstream” workflow (bump submodule -> run parity suite -> fix breakages -> merge).

esbuild.js

@@ -77,10 +77,10 @@ const watch = process.argv.indexOf('--watch') !== -1;
 `.trimStart()
 		},
 		entryPoints: [
-			'./src/spec-node/devContainersSpecCLI.ts',
+			'./upstream/src/spec-node/devContainersSpecCLI.ts',
 		],
 		tsconfig: 'tsconfig.json',
-		outbase: 'src',
+		outbase: 'upstream/src',
 	};
 
 	if (watch) {