Merge pull request #18 from jooh/codex/implement-upstream-submodule-cutover-step-919m0s Upstream submodule cutover: remove duplicated root upstream files, add readiness checks, docs, and tests

.github/workflows/dev-containers.yml

@@ -19,13 +19,17 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - uses: actions/setup-node@v5
       with:
         node-version: '20.x'
         registry-url: 'https://npm.pkg.github.com'
         scope: '@microsoft'
     - name: Install Dependencies
       run: yarn install --frozen-lockfile
+    - name: Upstream Compatibility Baseline
+      run: yarn check-upstream-compatibility
     - name: Type-Check
       run: yarn type-check
     - name: Lint
@@ -69,6 +73,8 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - name: Setup Node.js
       uses: actions/setup-node@v5
       with:
@@ -117,6 +123,8 @@ jobs:
     steps:
     - name: Checkout
       uses: actions/checkout@v6
+      with:
+        submodules: recursive
     - name: Setup Node.js
       uses: actions/setup-node@v5
       with:
@@ -151,6 +159,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

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

AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md
+
+## Scope
+These instructions apply to the entire repository tree rooted at this directory.
+
+## Upstream submodule policy
+- The `upstream/` directory is the canonical location for upstream `devcontainers/cli` TypeScript sources.
+- Do **not** introduce new copies of upstream-owned files at repository root.
+- Keep project-owned implementation and migration work outside `upstream/` unless explicitly updating the submodule pointer.
+
+## Compatibility baseline
+- Treat the pinned `upstream/` submodule commit as the compatibility target.
+- When changing compatibility-sensitive behavior, prefer tests/logging that make the current upstream commit easy to identify.
+
+## Updating upstream
+When asked to update upstream:
+1. Update the submodule pointer in `upstream/`.
+2. Run/adjust parity tests and related fixtures against the new upstream revision.
+3. Keep changes reviewable (submodule bump + project-owned compatibility fixes).
+
+## 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.