feat: add CI-gated claude-dev image package

Define claude-dev capabilities as a tested contract and deploy immutable tags only after smoke checks so daily tooling upgrades remain CI-first and rollback-safe.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.gitea/workflows/deploy-claude-dev-dev.yml

@@ -0,0 +1,107 @@
+name: Deploy Claude Dev (Dev)
+on:
+  push:
+    branches: [dev]
+    paths:
+      - 'claude-dev/**'
+      - '.gitea/workflows/deploy-claude-dev-dev.yml'
+  workflow_dispatch:
+    inputs:
+      rollback_image:
+        description: 'Optional full image ref (for rollback), e.g. claude-dev:dev-abc123'
+        required: false
+
+jobs:
+  deploy-claude-dev-dev:
+    runs-on: ubuntu-latest
+    container:
+      volumes:
+        - /var/packages/ContainerManager/target/usr/bin/docker:/usr/bin/docker
+        - /volume1/docker/claude-dev:/claude-dev-runtime
+    steps:
+      - name: Checkout dev branch
+        run: git clone --depth 1 --branch dev http://gitea:3000/jimmy/nas-tools.git .
+
+      - name: Resolve image tags
+        run: |
+          set -euo pipefail
+          if [ -n "${{ inputs.rollback_image }}" ]; then
+            image_ref="${{ inputs.rollback_image }}"
+            image_tag="${image_ref#claude-dev:}"
+            if [ "$image_ref" = "$image_tag" ]; then
+              echo "rollback_image must be in claude-dev:<tag> format" >&2
+              exit 1
+            fi
+            echo "ROLLBACK_ONLY=1" >> "$GITHUB_ENV"
+          else
+            short_sha="$(git rev-parse --short=12 HEAD)"
+            date_tag="$(date +%Y%m%d%H%M%S)"
+            image_tag="dev-${date_tag}-${short_sha}"
+            image_ref="claude-dev:${image_tag}"
+            echo "ROLLBACK_ONLY=0" >> "$GITHUB_ENV"
+          fi
+          echo "CLAUDE_DEV_IMAGE_TAG=${image_tag}" >> "$GITHUB_ENV"
+          echo "CLAUDE_DEV_IMAGE=${image_ref}" >> "$GITHUB_ENV"
+
+      - name: Build claude-dev image
+        if: env.ROLLBACK_ONLY == '0'
+        run: |
+          set -euo pipefail
+          DOCKER_BUILDKIT=0 docker build \
+            --cache-from claude-dev:latest \
+            -t "$CLAUDE_DEV_IMAGE" \
+            -t claude-dev:latest \
+            claude-dev/
+
+      - name: Smoke test required tools
+        if: env.ROLLBACK_ONLY == '0'
+        run: |
+          set -euo pipefail
+          docker run --rm "$CLAUDE_DEV_IMAGE" bash /opt/claude-dev/scripts/smoke-tools.sh
+
+      - name: Smoke test network assumptions
+        if: env.ROLLBACK_ONLY == '0'
+        run: |
+          set -euo pipefail
+          docker run --rm --network host "$CLAUDE_DEV_IMAGE" bash /opt/claude-dev/scripts/smoke-network.sh
+
+      - name: Smoke test auth and mount expectations
+        if: env.ROLLBACK_ONLY == '0'
+        run: |
+          set -euo pipefail
+          docker run --rm --network host \
+            -e REQUIRE_MOUNTS=1 \
+            -v /volume1/docker/claude-dev/claude-config:/root/.claude \
+            -v /volume1/docker/claude-dev/claude-config/.claude.json:/root/.claude.json \
+            -v /volume1/docker/claude-dev/gitea_token:/root/.gitea_token:ro \
+            "$CLAUDE_DEV_IMAGE" \
+            bash /opt/claude-dev/scripts/smoke-auth.sh
+
+      - name: Record previous image
+        run: |
+          set -euo pipefail
+          previous_image="$(docker inspect -f '{{.Config.Image}}' claude-dev 2>/dev/null || true)"
+          if [ -n "$previous_image" ]; then
+            printf '%s\n' "$previous_image" > /claude-dev-runtime/previous-image.txt
+            echo "Saved previous image: $previous_image"
+          else
+            echo "No existing claude-dev container found"
+          fi
+
+      - name: Sync compose and target tag
+        run: |
+          set -euo pipefail
+          cp claude-dev/docker-compose.yml /claude-dev-runtime/docker-compose.yml
+          printf '%s\n' "$CLAUDE_DEV_IMAGE_TAG" > /claude-dev-runtime/target-tag.txt
+
+      - name: Deploy claude-dev
+        run: |
+          set -euo pipefail
+          CLAUDE_DEV_IMAGE_TAG="$CLAUDE_DEV_IMAGE_TAG" docker compose -f /claude-dev-runtime/docker-compose.yml up -d --pull never
+
+      - name: Post-deploy runtime checks
+        run: |
+          set -euo pipefail
+          docker exec claude-dev bash -lc 'claude --version'
+          docker exec claude-dev bash -lc 'gh --version'
+          docker exec claude-dev bash -lc 'gh auth status || true'

CLAUDE.md

@@ -17,7 +17,20 @@
 - Build images on Mac: `docker build --platform linux/amd64`
 - Transfer: `docker save <image> | ssh zjgump@100.78.131.124 "/volume1/@appstore/ContainerManager/usr/bin/docker load"`
 - Deploy: `git push` triggers Gitea Actions CI (`docker compose up -d --pull never`) — do NOT manually restart
-- CI workflow `deploy.yml` is stored in Gitea, not in this repo
+- CI workflows are in `.gitea/workflows/` in this repo
+
+## claude-dev CI Contract
+- Source package lives in `claude-dev/` (`Dockerfile`, `required-tools.txt`, and smoke scripts under `claude-dev/scripts/`)
+- CI-first only: update `claude-dev/*` in git, then push; do not do ad-hoc local image rebuild/redeploy for normal changes
+- Required capabilities are declared in `claude-dev/required-tools.txt`; adding tools must update this file and related smoke checks
+- Build/deploy gate (`.gitea/workflows/deploy-claude-dev-dev.yml`) uses NAS runner with `DOCKER_BUILDKIT=0`, then runs:
+  - tools smoke (`smoke-tools.sh`)
+  - network smoke (`smoke-network.sh`)
+  - auth/mount smoke (`smoke-auth.sh` with required runtime mounts)
+- Deployment only happens after smoke pass, using immutable tag format `claude-dev:dev-<timestamp>-<sha>`
+- Runtime compose definition is `claude-dev/docker-compose.yml`; CI syncs it to `/volume1/docker/claude-dev/docker-compose.yml`
+- Runtime requirements preserved: `network_mode: host`, `/volume1/repos` mount, `/root/.claude` mount, `/root/.claude.json` mount, `/root/.gitea_token` mount
+- Rollback: run workflow manually with `rollback_image` (for example the value in `/volume1/docker/claude-dev/previous-image.txt`) to redeploy a known-good immutable tag via CI
 
 ## Synology Quirks
 - No `crontab` — edit `/etc/crontab` with `sudo` + `printf`, restart crond

claude-dev/Dockerfile

@@ -0,0 +1,60 @@
+FROM node:20-bookworm
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+      bash \
+      ca-certificates \
+      curl \
+      fd-find \
+      gh \
+      git \
+      jq \
+      make \
+      openssh-client \
+      python3 \
+      ripgrep \
+      rsync \
+      unzip \
+      wget \
+      zip \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN ln -sf /usr/bin/fdfind /usr/local/bin/fd
+
+ARG YQ_VERSION=v4.44.6
+RUN wget -q -O /usr/local/bin/yq "https://github.com/mikefarah/yq/releases/download/${YQ_VERSION}/yq_linux_amd64" \
+    && chmod +x /usr/local/bin/yq
+
+RUN npm install -g @anthropic-ai/claude-code
+
+RUN python3 - <<'PY'
+from pathlib import Path
+
+path = Path("/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js")
+if not path.exists():
+    raise SystemExit(f"claude cli not found: {path}")
+
+content = path.read_text()
+old = 'F8.get("https://api.anthropic.com/api/hello",{headers:K8($)}).catch((()=>!1))'
+if old not in content:
+    raise SystemExit("preflight patch target not found in claude cli; refusing to build")
+
+patched = content.replace(old, "!0")
+path.write_text(patched)
+
+if old in path.read_text():
+    raise SystemExit("preflight patch did not apply cleanly")
+
+print("Applied Claude preflight bypass patch")
+PY
+
+WORKDIR /repos/nas-tools
+
+COPY required-tools.txt /opt/claude-dev/required-tools.txt
+COPY scripts /opt/claude-dev/scripts
+
+RUN chmod +x /opt/claude-dev/scripts/*.sh
+
+CMD ["bash"]

claude-dev/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  claude-dev:
+    image: claude-dev:${CLAUDE_DEV_IMAGE_TAG:?CLAUDE_DEV_IMAGE_TAG is required}
+    container_name: claude-dev
+    restart: unless-stopped
+    network_mode: host
+    stdin_open: true
+    tty: true
+    working_dir: /repos/nas-tools
+    volumes:
+      - /volume1/repos:/repos
+      - /volume1/docker/claude-dev/claude-config:/root/.claude
+      - /volume1/docker/claude-dev/claude-config/.claude.json:/root/.claude.json
+      - /volume1/docker/claude-dev/gitea_token:/root/.gitea_token:ro
+      - /volume1/docker/claude-dev/bashrc:/root/.bashrc

claude-dev/required-tools.txt

@@ -0,0 +1,16 @@
+gh
+git
+jq
+yq
+curl
+wget
+python3
+node
+npm
+rg
+fd
+rsync
+zip
+unzip
+make
+claude

claude-dev/scripts/smoke-auth.sh

@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+require_mounts="${REQUIRE_MOUNTS:-0}"
+
+auth_ok=true
+
+check_required_file() {
+  local path="$1"
+  if [[ ! -e "$path" ]]; then
+    echo "Missing required mounted path: $path" >&2
+    auth_ok=false
+    return
+  fi
+  if [[ ! -r "$path" ]]; then
+    echo "Path is not readable: $path" >&2
+    auth_ok=false
+    return
+  fi
+  if [[ -f "$path" ]] && [[ ! -s "$path" ]]; then
+    echo "Path is empty: $path" >&2
+    auth_ok=false
+    return
+  fi
+  echo "Verified mounted path: $path"
+}
+
+if [[ "$require_mounts" == "1" ]]; then
+  check_required_file "/root/.claude"
+  check_required_file "/root/.claude.json"
+  check_required_file "/root/.gitea_token"
+
+  if [[ -f "/root/.claude/.git-credentials" ]]; then
+    echo "Verified mounted path: /root/.claude/.git-credentials"
+  else
+    echo "Missing expected git credentials file: /root/.claude/.git-credentials" >&2
+    auth_ok=false
+  fi
+fi
+
+if [[ -n "${GH_TOKEN:-}" ]]; then
+  if GH_TOKEN="$GH_TOKEN" gh auth status >/dev/null 2>&1; then
+    echo "gh auth status succeeded with GH_TOKEN"
+  else
+    echo "gh auth status failed with GH_TOKEN provided" >&2
+    auth_ok=false
+  fi
+else
+  if gh auth status >/dev/null 2>&1; then
+    echo "gh auth status succeeded using persisted auth"
+  else
+    echo "gh auth status not configured (allowed without GH_TOKEN)"
+  fi
+fi
+
+if [[ "$auth_ok" != "true" ]]; then
+  exit 1
+fi
+
+echo "Auth/config smoke checks passed"

claude-dev/scripts/smoke-network.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+check_http_status() {
+  local url="$1"
+  local allowed_regex="$2"
+
+  local code
+  code=$(curl -sS -o /dev/null -m 10 -w "%{http_code}" "$url")
+  if [[ ! "$code" =~ $allowed_regex ]]; then
+    echo "Unexpected HTTP status from $url: $code" >&2
+    return 1
+  fi
+  echo "$url => HTTP $code"
+}
+
+if ! getent hosts api.bytecatcode.org >/dev/null 2>&1; then
+  echo "DNS lookup failed for api.bytecatcode.org" >&2
+  exit 1
+fi
+
+echo "DNS lookup passed for api.bytecatcode.org"
+
+check_http_status "https://api.bytecatcode.org" '^(200|301|302|400|401|403|404)$'
+check_http_status "http://127.0.0.1:3300" '^(200|301|302|401|403|404)$'
+
+echo "Network smoke checks passed"

claude-dev/scripts/smoke-tools.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+TOOLS_FILE="${1:-/opt/claude-dev/required-tools.txt}"
+
+if [[ ! -f "$TOOLS_FILE" ]]; then
+  echo "required tools file not found: $TOOLS_FILE" >&2
+  exit 1
+fi
+
+missing=()
+while IFS= read -r tool; do
+  [[ -z "$tool" ]] && continue
+  [[ "$tool" =~ ^# ]] && continue
+  if ! command -v "$tool" >/dev/null 2>&1; then
+    missing+=("$tool")
+  fi
+done < "$TOOLS_FILE"
+
+if (( ${#missing[@]} > 0 )); then
+  echo "Missing required tools:" >&2
+  printf ' - %s\n' "${missing[@]}" >&2
+  exit 1
+fi
+
+echo "All required tools are present"

claude-dev/target-tag.txt

@@ -0,0 +1 @@
+auto