Default devcontainer to template's prebuilt image for fast startup

New repos from this template hit a chicken-and-egg problem: they can't
use their own prebuilt image because CI hasn't built it yet. Default to
the template's prebuilt image so new repos get fast startup immediately.

Three devcontainer states: template-prebuilt (default), local-build
(dev-use-local), and repo-prebuilt (dev-use-prebuilt). Fix awk bug in
both switching scripts where `if (/\}/)` matched `{}` inside feature
values like `"./claude-code": {}`, causing premature block termination.

- Default devcontainer.json to template prebuilt image
- Add dev-use-local script and pixi task
- Fix awk closing-brace patterns in both switching scripts
- Add docker-in-docker and common-utils features to CI devcontainer
- Protect template image URL in rename_project.sh
- Update README with three-state documentation table

Author: blooop

.devcontainer/ci/devcontainer.json

@@ -5,6 +5,8 @@
         "context": "../.."
     },
     "features": {
-        "../claude-code": {}
+        "../claude-code": {},
+        "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+        "ghcr.io/devcontainers/features/common-utils:2": {}
     }
 }

.devcontainer/devcontainer.json

@@ -1,21 +1,21 @@
 {
     "name": "python_template",
 
-    "build": {
-        "dockerfile": "Dockerfile",
-        "context": ".."
-    },
+    // Uses the template's prebuilt image by default for fast startup.
+    // To build locally: pixi run dev-use-local
+    // To use this repo's own prebuilt image: pixi run dev-use-prebuilt
+    // "build": {
+    //     "dockerfile": "Dockerfile",
+    //     "context": ".."
+    // },
+    "image": "ghcr.io/blooop/python_template/devcontainer:latest",
+
     "features": {
         "./claude-code": {},
         "ghcr.io/devcontainers/features/docker-in-docker:2": {},
         "ghcr.io/devcontainers/features/common-utils:2": {}
     },
 
-    // To use a prebuilt image instead of building locally (faster startup),
-    // comment out "build" and "features" above, uncomment "image" below,
-    // and ensure the GHCR package is public (see README).
-    // "image": "ghcr.io/blooop/python_template/devcontainer:latest",
-
     "initializeCommand": ".devcontainer/claude-code/init-host.sh",
     "customizations": {
         "vscode": {

README.md

@@ -59,48 +59,30 @@ See [.claude/README.md](.claude/README.md) for detailed information about the Cl
 
 # Devcontainer
 
-By default, the devcontainer builds locally from `.devcontainer/Dockerfile`. This works out of the box for all users, including forks and projects created from this template.
+The devcontainer has three states:
 
-## Switching to a prebuilt image (optional)
+| State | When | `image` | `build` | `features` |
+|---|---|---|---|---|
+| **Template prebuilt** (default) | Fresh clones, after rename | template URL | commented | active |
+| **Local build** | After `dev-use-local` | commented | active | active |
+| **Repo prebuilt** | After `dev-use-prebuilt` | repo URL | commented | commented |
 
-A CI workflow (`.github/workflows/devcontainer.yml`) automatically builds and pushes a devcontainer image to GHCR whenever `.devcontainer/` files change on `main`. The image is published as `ghcr.io/<owner>/<repo>/devcontainer:latest`, where `<owner>` is your GitHub username or organization and `<repo>` is the repository name (e.g. `ghcr.io/myuser/myproject/devcontainer:latest`).
+By default, the devcontainer uses a prebuilt image from the template repository (`ghcr.io/blooop/python_template/devcontainer:latest`) for fast startup. This works immediately for new repos created from this template — no CI build needed.
 
-You can migrate automatically with:
+To switch to building locally from `.devcontainer/Dockerfile` (e.g. after customizing the Dockerfile):
 
 ```bash
-pixi run dev-use-prebuilt
+pixi run dev-use-local
 ```
 
-Or manually:
-
-1. Edit `.devcontainer/devcontainer.json`: comment out the `"build"` and `"features"` blocks, uncomment the `"image"` line
-2. Update the image reference to match your repo: `ghcr.io/<owner>/<repo>/devcontainer:latest`
-3. Push to `main` and wait for the CI workflow to complete. For new repos or forks where the workflow hasn't run yet, you can trigger it manually from the Actions tab or via `gh workflow run devcontainer.yml`
-4. **Make the GHCR package public** (see below) — GHCR packages are private by default and will fail with `MANIFEST_UNKNOWN` otherwise
-
-### Making the GHCR package public
-
-**Option 1: GitHub Web UI**
-
-1. Go to your repository's package settings:
-   - Personal repos: `https://github.com/users/<username>/packages/container/<repo>%2Fdevcontainer/settings`
-   - Organization repos: `https://github.com/orgs/<org>/packages/container/<repo>%2Fdevcontainer/settings`
-2. Under "Danger Zone", click **Change visibility**
-3. Select **Public** and confirm
-
-**Option 2: GitHub CLI**
+To switch to this repo's own prebuilt image (built by CI on each push to `main`):
 
 ```bash
-# Ensure your token has the write:packages scope
-gh auth refresh -s write:packages
-
-# For personal repos:
-gh api --method PATCH /user/packages/container/<repo>%2Fdevcontainer -f visibility=public
-
-# For organization repos:
-gh api --method PATCH /orgs/<org>/packages/container/<repo>%2Fdevcontainer -f visibility=public
+pixi run dev-use-prebuilt
 ```
 
+This detects the repo from git remote, updates `devcontainer.json` to use `ghcr.io/<owner>/<repo>/devcontainer:latest`, and attempts to make the GHCR package public. See the script output for manual steps if automatic visibility fails.
+
 # Github setup
 
 There are github workflows for CI, codecov and automated pypi publishing in `ci.yml` and `publish.yml`.

pixi.lock

@@ -100,6 +100,7 @@ clear-pixi = "rm -rf .pixi pixi.lock"
 setup-git-merge-driver = "git config merge.ourslock.driver true"
 update-from-template-repo = "./scripts/update_from_template.sh"
 dev-use-prebuilt = "./scripts/devcontainer_use_prebuilt.sh"
+dev-use-local = "./scripts/devcontainer_use_local.sh"
 
 [tool.pylint]
 extension-pkg-whitelist = ["numpy"]

pyproject.toml

@@ -0,0 +1,40 @@
+#!/bin/bash
+set -euo pipefail
+
+# Switch devcontainer.json to build locally from Dockerfile.
+
+DEVCONTAINER_JSON=".devcontainer/devcontainer.json"
+
+# Already using local build?
+if grep -q '^[[:space:]]*"build"' "$DEVCONTAINER_JSON"; then
+    echo "Already using local build. Nothing to do."
+    exit 0
+fi
+
+awk '
+    # Uncomment commented build block
+    /^    \/\/ "build": \{/ { in_build=1 }
+    in_build {
+        sub(/^    \/\/ /, "    ")
+        if (/^    \}/) in_build=0
+        print; next
+    }
+
+    # Uncomment commented features block
+    /^    \/\/ "features": \{/ { in_features=1 }
+    in_features {
+        sub(/^    \/\/ /, "    ")
+        if (/^    \}/) in_features=0
+        print; next
+    }
+
+    # Comment out uncommented image line
+    /^    "image":/ {
+        sub(/^    /, "    // ")
+        print; next
+    }
+
+    { print }
+' "$DEVCONTAINER_JSON" > "${DEVCONTAINER_JSON}.tmp" && mv "${DEVCONTAINER_JSON}.tmp" "$DEVCONTAINER_JSON"
+
+echo "Switched to local build from Dockerfile."

scripts/devcontainer_use_local.sh

@@ -1,7 +1,7 @@
 #!/bin/bash
 set -euo pipefail
 
-# Migrate devcontainer.json from local builds to a prebuilt GHCR image.
+# Switch devcontainer.json to use this repo's own prebuilt GHCR image.
 # Also attempts to make the GHCR package public.
 
 DEVCONTAINER_JSON=".devcontainer/devcontainer.json"
@@ -20,7 +20,6 @@ REMOTE_URL=$(git remote get-url origin 2>/dev/null) || {
     exit 1
 }
 
-# Handle common GitHub remote URL formats
 REPO=$(echo "$REMOTE_URL" | sed -E 's#(ssh://git@github\.com/|git@github\.com:|https?://github\.com/|git://github\.com/)##; s/\.git$//')
 
 if [[ -z "$REPO" || "$REPO" != */* ]]; then
@@ -32,43 +31,47 @@ IMAGE="ghcr.io/${REPO}/devcontainer:latest"
 echo "Repository: $REPO"
 echo "Image:      $IMAGE"
 
-# --- Check current state: look for an uncommented "image": line ---
-if grep -q '^[[:space:]]*"image"[[:space:]]*:' "$DEVCONTAINER_JSON"; then
-    echo "Already using a prebuilt image. Nothing to do."
+# --- Check if already using this repo's prebuilt image (uncommented) ---
+if grep -q '^[[:space:]]*"image": "'"${IMAGE}"'"' "$DEVCONTAINER_JSON"; then
+    echo "Already using repo prebuilt image. Nothing to do."
     exit 0
 fi
 
-# --- Replace the file using awk for reliable block manipulation ---
+# --- Transform devcontainer.json ---
 awk -v image="$IMAGE" '
-    # Comment out uncommented "build" block (4-space indent open/close).
-    # NOTE: assumes no nested {} within these blocks.
+    # Comment out uncommented build block
     /^    "build": \{/ { in_build=1 }
     in_build {
         sub(/^    /, "    // ")
         if (/^    \/\/ \}/) in_build=0
         print; next
     }
 
-    # Comment out uncommented "features" block (4-space indent open/close).
-    # NOTE: assumes no nested {} within these blocks.
+    # Comment out uncommented features block
     /^    "features": \{/ { in_features=1 }
     in_features {
         sub(/^    /, "    // ")
         if (/^    \/\/ \}/) in_features=0
         print; next
     }
 
-    # Uncomment the image line and set the correct reference
+    # Uncomment commented image line and set repo URL
     /^    \/\/ "image":/ {
         printf "    \"image\": \"%s\",\n", image
         next
     }
 
+    # Replace uncommented image line (e.g. template URL) with repo URL
+    /^    "image":/ {
+        printf "    \"image\": \"%s\",\n", image
+        next
+    }
+
     { print }
 ' "$DEVCONTAINER_JSON" > "${DEVCONTAINER_JSON}.tmp" && mv "${DEVCONTAINER_JSON}.tmp" "$DEVCONTAINER_JSON"
 
 echo ""
-echo "Updated $DEVCONTAINER_JSON to use prebuilt image."
+echo "Updated $DEVCONTAINER_JSON to use repo prebuilt image."
 
 # --- Try to make the GHCR package public ---
 echo ""

scripts/devcontainer_use_prebuilt.sh

@@ -2,8 +2,11 @@
 
 mv python_template "$1"
 
-# change project name in all files
-find . \( -type d -name .git -prune \) -o \( -type f -not -name 'tasks.json' -not -name 'update_from_template.sh' -not -name 'pixi.lock' \) -print0 | xargs -0 sed -i "s/python_template/$1/g"
+# change project name in all files (exclude main devcontainer.json to protect template image URL)
+find . \( -type d -name .git -prune \) -o \( -type f -not -name 'tasks.json' -not -name 'update_from_template.sh' -not -name 'pixi.lock' -not -path './.devcontainer/devcontainer.json' \) -print0 | xargs -0 sed -i "s/python_template/$1/g"
+
+# update just the name field in devcontainer.json
+sed -i "s/\"name\": \"python_template\"/\"name\": \"$1\"/" .devcontainer/devcontainer.json
 
 # regenerate lockfile to match renamed project
 pixi update
@@ -18,7 +21,7 @@ if [ -n "$3" ]; then
     find . \( -type d -name .git -prune \) -o \( -type f -not -name 'tasks.json' -not -name 'update_from_template.sh'  \) -print0 | xargs -0 sed -i "s/blooop@gmail.com/$3/g"
 fi
 
-# github username
+# github username (exclude main devcontainer.json to protect template image URL)
 if [ -n "$4" ]; then
-    find . \( -type d -name .git -prune \) -o \( -type f -not -name 'setup_host.sh' -not -name 'update_from_template.sh'  \) -print0 | xargs -0 sed -i "s/blooop/$4/g"
+    find . \( -type d -name .git -prune \) -o \( -type f -not -name 'setup_host.sh' -not -name 'update_from_template.sh' -not -path './.devcontainer/devcontainer.json' \) -print0 | xargs -0 sed -i "s/blooop/$4/g"
 fi