codeforge-dev 1.5.8 → 1.8.0

package/.devcontainer/features/dprint/install.sh

@@ -0,0 +1,131 @@
+#!/bin/bash
+set -euo pipefail
+
+# ==============================
+# dprint DevContainer Feature
+# Official installer + global config
+# ==============================
+
+DPRINT_VERSION="${VERSION:-latest}"
+USERNAME="${USERNAME:-automatic}"
+
+# Skip installation if version is "none"
+if [ "${DPRINT_VERSION}" = "none" ]; then
+    echo "[dprint] Skipping installation (version=none)"
+    exit 0
+fi
+
+echo "[dprint] Starting installation..."
+
+# ---------- USER ----------
+if [[ "${USERNAME}" == "auto" || "${USERNAME}" == "automatic" ]]; then
+    for u in vscode node codespace; do
+        if id -u "$u" >/dev/null 2>&1; then
+            USERNAME="$u"
+            break
+        fi
+    done
+    USERNAME="${USERNAME:-root}"
+fi
+
+USER_HOME="$(eval echo "~${USERNAME}")"
+
+echo "[dprint] Target user: ${USERNAME}"
+echo "[dprint] Version: ${DPRINT_VERSION}"
+
+# ---------- HELPERS ----------
+download_with_retry() {
+    local url="$1" dest="$2" retries="${3:-3}" delay="${4:-2}"
+    local attempt=1
+    while [ $attempt -le $retries ]; do
+        if curl -fsSL ${GITHUB_AUTH_HEADER:-} "$url" -o "$dest" 2>/dev/null; then
+            return 0
+        fi
+        echo "[dprint] Download attempt $attempt/$retries failed, retrying in ${delay}s..."
+        sleep "$delay"
+        attempt=$((attempt + 1))
+        delay=$((delay * 2))
+    done
+    echo "[dprint] ERROR: Download failed after $retries attempts: $url"
+    return 1
+}
+
+# GitHub API auth header (avoids rate limiting)
+GITHUB_AUTH_HEADER=""
+if [ -n "${GH_TOKEN:-}" ] || [ -n "${GITHUB_TOKEN:-}" ]; then
+    GITHUB_AUTH_HEADER="-H Authorization: token ${GH_TOKEN:-$GITHUB_TOKEN}"
+fi
+
+# ---------- INSTALL ----------
+# Install to a system-wide location so all users can access it
+export DPRINT_INSTALL="/usr/local/share/dprint"
+mkdir -p "${DPRINT_INSTALL}/bin"
+
+ARCH="$(dpkg --print-architecture)"
+case "${ARCH}" in
+    amd64) TARGET="x86_64-unknown-linux-gnu" ;;
+    arm64) TARGET="aarch64-unknown-linux-gnu" ;;
+    *)
+        echo "[dprint] ERROR: Unsupported architecture: ${ARCH}" >&2
+        exit 1
+        ;;
+esac
+
+# Version pinned for reproducible builds. Set "latest" to always get newest.
+if [[ "${DPRINT_VERSION}" == "latest" ]]; then
+    DPRINT_VERSION="$(curl -fsSL ${GITHUB_AUTH_HEADER:-} https://api.github.com/repos/dprint/dprint/releases/latest | grep -o '"tag_name": *"[^"]*"' | head -1 | cut -d'"' -f4)"
+    echo "[dprint] Resolved latest version: ${DPRINT_VERSION}"
+fi
+
+ZIP_URL="https://github.com/dprint/dprint/releases/download/${DPRINT_VERSION}/dprint-${TARGET}.zip"
+echo "[dprint] Downloading from: ${ZIP_URL}"
+
+TMP_DIR="$(mktemp -d)"
+download_with_retry "${ZIP_URL}" "${TMP_DIR}/dprint.zip"
+
+# ---------- CHECKSUM VERIFICATION ----------
+CHECKSUM_URL="https://github.com/dprint/dprint/releases/download/${DPRINT_VERSION}/SHASUMS256.txt"
+if curl -fsSL "${CHECKSUM_URL}" -o "${TMP_DIR}/checksums.txt" 2>/dev/null; then
+    EXPECTED=$(grep "dprint-${TARGET}.zip" "${TMP_DIR}/checksums.txt" | awk '{print $1}')
+    ACTUAL=$(sha256sum "${TMP_DIR}/dprint.zip" | cut -d' ' -f1)
+    if [ -n "$EXPECTED" ] && [ "$ACTUAL" != "$EXPECTED" ]; then
+        echo "[dprint] ERROR: Checksum verification failed"
+        echo "  Expected: $EXPECTED"
+        echo "  Actual:   $ACTUAL"
+        rm -rf "${TMP_DIR}"
+        exit 1
+    fi
+    echo "[dprint] Checksum verified"
+else
+    echo "[dprint] WARNING: Could not fetch checksums, skipping verification"
+fi
+
+unzip -o "${TMP_DIR}/dprint.zip" -d "${DPRINT_INSTALL}/bin"
+chmod +x "${DPRINT_INSTALL}/bin/dprint"
+rm -rf "${TMP_DIR}"
+
+# Symlink into PATH
+ln -sf "${DPRINT_INSTALL}/bin/dprint" /usr/local/bin/dprint
+
+# ---------- GLOBAL CONFIG ----------
+cat > "${DPRINT_INSTALL}/dprint.json" << 'DPRINT_CONFIG'
+{
+  "lineWidth": 120,
+  "indentWidth": 2,
+  "markdown": {},
+  "yaml": {},
+  "toml": {},
+  "dockerfile": {},
+  "plugins": [
+    "https://plugins.dprint.dev/markdown-0.17.8.wasm",
+    "https://plugins.dprint.dev/g-plane/pretty_yaml-0.5.0.wasm",
+    "https://plugins.dprint.dev/toml-0.6.4.wasm",
+    "https://plugins.dprint.dev/dockerfile-0.3.2.wasm"
+  ]
+}
+DPRINT_CONFIG
+
+echo "[dprint] Global config written to ${DPRINT_INSTALL}/dprint.json"
+
+# ---------- VERIFY ----------
+echo "[dprint] Installed: $(dprint --version 2>/dev/null || echo 'unknown')"

package/.devcontainer/features/hadolint/README.md

@@ -0,0 +1,35 @@
+# hadolint
+
+Dockerfile linter that validates best practices.
+
+## What It Does
+
+Installs [hadolint](https://github.com/hadolint/hadolint) as a static binary. Hadolint parses Dockerfiles and checks them against best-practice rules based on the official Docker documentation.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `v2.14.0` | hadolint version to install. Set `"latest"` for newest, `"none"` to skip. |
+
+## Usage
+
+```bash
+hadolint Dockerfile
+hadolint --ignore DL3008 Dockerfile    # ignore specific rule
+hadolint -f json Dockerfile            # JSON output
+```
+
+## Configuration
+
+Used by the `auto-linter` plugin to lint Dockerfiles on save. For project-specific ignores, create a `.hadolint.yaml` in your project root:
+
+```yaml
+ignored:
+  - DL3008  # Pin versions in apt-get install
+  - DL3009  # Delete apt lists
+```
+
+## Checksum Verification
+
+Downloads are verified against per-binary `.sha256` files published with each GitHub release.

package/.devcontainer/features/hadolint/devcontainer-feature.json

@@ -0,0 +1,13 @@
+{
+  "id": "hadolint",
+  "version": "1.0.0",
+  "name": "hadolint",
+  "description": "Dockerfile linter that validates best practices",
+  "options": {
+    "version": {
+      "type": "string",
+      "default": "v2.14.0",
+      "description": "hadolint version to install. Set 'latest' to always get newest."
+    }
+  }
+}

package/.devcontainer/features/hadolint/install.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+set -euo pipefail
+
+# ==============================
+# hadolint DevContainer Feature
+# Direct binary from GitHub releases
+# ==============================
+
+HADOLINT_VERSION="${VERSION:-latest}"
+
+# Skip installation if version is "none"
+if [ "${HADOLINT_VERSION}" = "none" ]; then
+    echo "[hadolint] Skipping installation (version=none)"
+    exit 0
+fi
+
+echo "[hadolint] Starting installation..."
+
+# ---------- HELPERS ----------
+download_with_retry() {
+    local url="$1" dest="$2" retries="${3:-3}" delay="${4:-2}"
+    local attempt=1
+    while [ $attempt -le $retries ]; do
+        if curl -fsSL ${GITHUB_AUTH_HEADER:-} "$url" -o "$dest" 2>/dev/null; then
+            return 0
+        fi
+        echo "[hadolint] Download attempt $attempt/$retries failed, retrying in ${delay}s..."
+        sleep "$delay"
+        attempt=$((attempt + 1))
+        delay=$((delay * 2))
+    done
+    echo "[hadolint] ERROR: Download failed after $retries attempts: $url"
+    return 1
+}
+
+# GitHub API auth header (avoids rate limiting)
+GITHUB_AUTH_HEADER=""
+if [ -n "${GH_TOKEN:-}" ] || [ -n "${GITHUB_TOKEN:-}" ]; then
+    GITHUB_AUTH_HEADER="-H Authorization: token ${GH_TOKEN:-$GITHUB_TOKEN}"
+fi
+
+ARCH="$(dpkg --print-architecture)"
+case "${ARCH}" in
+    amd64) BINARY_ARCH="x86_64" ;;
+    arm64) BINARY_ARCH="arm64" ;;
+    *)
+        echo "[hadolint] ERROR: Unsupported architecture: ${ARCH}" >&2
+        exit 1
+        ;;
+esac
+
+# Version pinned for reproducible builds. Set "latest" to always get newest.
+if [[ "${HADOLINT_VERSION}" == "latest" ]]; then
+    HADOLINT_VERSION="$(curl -fsSL ${GITHUB_AUTH_HEADER:-} https://api.github.com/repos/hadolint/hadolint/releases/latest | grep -o '"tag_name": *"[^"]*"' | head -1 | cut -d'"' -f4)"
+    echo "[hadolint] Resolved latest version: ${HADOLINT_VERSION}"
+fi
+
+URL="https://github.com/hadolint/hadolint/releases/download/${HADOLINT_VERSION}/hadolint-Linux-${BINARY_ARCH}"
+echo "[hadolint] Downloading from: ${URL}"
+
+TMP_DIR="$(mktemp -d)"
+download_with_retry "${URL}" "${TMP_DIR}/hadolint"
+
+# ---------- CHECKSUM VERIFICATION ----------
+# hadolint publishes per-binary .sha256 files
+CHECKSUM_URL="${URL}.sha256"
+if curl -fsSL "${CHECKSUM_URL}" -o "${TMP_DIR}/checksum.sha256" 2>/dev/null; then
+    EXPECTED=$(awk '{print $1}' "${TMP_DIR}/checksum.sha256")
+    ACTUAL=$(sha256sum "${TMP_DIR}/hadolint" | cut -d' ' -f1)
+    if [ -n "$EXPECTED" ] && [ "$ACTUAL" != "$EXPECTED" ]; then
+        echo "[hadolint] ERROR: Checksum verification failed"
+        echo "  Expected: $EXPECTED"
+        echo "  Actual:   $ACTUAL"
+        rm -rf "${TMP_DIR}"
+        exit 1
+    fi
+    echo "[hadolint] Checksum verified"
+else
+    echo "[hadolint] WARNING: Could not fetch checksum, skipping verification"
+fi
+
+cp "${TMP_DIR}/hadolint" /usr/local/bin/hadolint
+chmod +x /usr/local/bin/hadolint
+rm -rf "${TMP_DIR}"
+
+echo "[hadolint] Installed: $(hadolint --version 2>/dev/null || echo 'unknown')"

package/.devcontainer/features/lsp-servers/devcontainer-feature.json

@@ -6,6 +6,11 @@
   "maintainer": "AnExiledDev",
   "documentationURL": "https://code.claude.com/docs/en/discover-plugins#code-intelligence",
   "options": {
+    "version": {
+      "type": "string",
+      "description": "Set to 'none' to skip installation of all LSP servers",
+      "default": "latest"
+    },
     "pyrightVersion": {
       "type": "string",
       "description": "Pyright npm package version (e.g., 'latest', '1.1.350')",

package/.devcontainer/features/lsp-servers/install.sh

@@ -4,12 +4,19 @@
 
 set -euo pipefail
 
+VERSION="${VERSION:-latest}"
 PYRIGHT_VERSION="${PYRIGHTVERSION:-latest}"
 TSLSP_VERSION="${TYPESCRIPTLSPVERSION:-latest}"
 TS_VERSION="${TYPESCRIPTVERSION:-latest}"
 GOPLS_VERSION="${GOPLSVERSION:-latest}"
 USERNAME="${USERNAME:-automatic}"
 
+# Skip installation if version is "none"
+if [ "${VERSION}" = "none" ]; then
+    echo "[lsp-servers] Skipping installation (version=none)"
+    exit 0
+fi
+
 echo "[lsp-servers] Starting installation..."
 echo "[lsp-servers] Pyright version: ${PYRIGHT_VERSION}"
 echo "[lsp-servers] TypeScript LSP version: ${TSLSP_VERSION}"

package/.devcontainer/features/mcp-qdrant/devcontainer-feature.json

@@ -6,6 +6,11 @@
   "maintainer": "AnExiledDev",
   "documentationURL": "https://github.com/qdrant/mcp-server-qdrant",
   "options": {
+    "version": {
+      "type": "string",
+      "description": "Version to install (or 'none' to skip installation)",
+      "default": "latest"
+    },
     "qdrantUrl": {
       "type": "string",
       "description": "Qdrant instance URL (e.g., https://xyz.cloud.qdrant.io:6333). Leave empty for local instance.",
@@ -52,6 +57,6 @@
   "installsAfter": [
     "ghcr.io/devcontainers/features/python:1",
     "ghcr.io/devcontainers/features/common-utils:2",
-    "./features/claude-code"
+    "ghcr.io/anthropics/devcontainer-features/claude-code:1"
   ]
 }

package/.devcontainer/features/mcp-qdrant/install.sh

@@ -4,6 +4,14 @@ set -euo pipefail
 # Import options from devcontainer-feature.json
 # NOTE: DevContainer converts camelCase options to UPPERCASE without underscores
 # Example: "qdrantUrl" becomes $QDRANTURL (not $QDRANT_URL)
+VERSION="${VERSION:-latest}"
+
+# Skip installation if version is "none"
+if [ "${VERSION}" = "none" ]; then
+    echo "[mcp-qdrant] Skipping installation (version=none)"
+    exit 0
+fi
+
 QDRANT_URL="${QDRANTURL:-}"
 QDRANT_API_KEY="${QDRANTAPIKEY:-}"
 QDRANT_LOCAL_PATH="${QDRANTLOCALPATH:-/workspaces/.qdrant/storage}"
@@ -76,7 +84,7 @@ pip uninstall hf-xet -y 2>/dev/null || true
 # Pre-download the embedding model from GCS (more reliable than HuggingFace Hub in containers)
 # This is critical to avoid network timeouts from huggingface_hub
 echo "[mcp-qdrant] Pre-downloading embedding model from GCS..."
-FASTEMBED_CACHE="/tmp/fastembed_cache"
+FASTEMBED_CACHE="/workspaces/.qdrant/fastembed_cache"
 mkdir -p "${FASTEMBED_CACHE}"
 
 # Map embedding model names to GCS URLs and legacy cache directory names
@@ -117,8 +125,7 @@ if [ -n "${MODEL_URL}" ]; then
             # Remove macOS extended attribute files
             find "${FASTEMBED_CACHE}" -name "._*" -delete 2>/dev/null || true
             rm -f "${TEMP_TAR}"
-            # Make cache world-readable/writable since it's in /tmp
-            chmod -R 777 "${FASTEMBED_CACHE}" 2>/dev/null || true
+            chmod -R 755 "${FASTEMBED_CACHE}" 2>/dev/null || true
             echo "[mcp-qdrant] ✓ Embedding model pre-downloaded to ${FASTEMBED_CACHE}/${MODEL_DIR}"
         else
             echo "[mcp-qdrant] WARNING: Failed to download model from GCS"
@@ -208,7 +215,7 @@ if [ -n "$QDRANT_URL" ]; then
             args: ["mcp-server-qdrant"],
             env: {
                 HF_HUB_OFFLINE: "1",
-                FASTEMBED_CACHE_PATH: "/tmp/fastembed_cache",
+                FASTEMBED_CACHE_PATH: "/workspaces/.qdrant/fastembed_cache",
                 QDRANT_URL: $url,
                 QDRANT_API_KEY: $key,
                 COLLECTION_NAME: $collection
@@ -224,7 +231,7 @@ else
             args: ["mcp-server-qdrant"],
             env: {
                 HF_HUB_OFFLINE: "1",
-                FASTEMBED_CACHE_PATH: "/tmp/fastembed_cache",
+                FASTEMBED_CACHE_PATH: "/workspaces/.qdrant/fastembed_cache",
                 QDRANT_LOCAL_PATH: $path,
                 COLLECTION_NAME: $collection
             }
@@ -250,7 +257,7 @@ fi
 
 # Set proper permissions
 chmod 644 "$SETTINGS_FILE"
-chown vscode:vscode "$SETTINGS_FILE" 2>/dev/null || true
+chown "$(id -un):$(id -gn)" "$SETTINGS_FILE" 2>/dev/null || true
 
 echo "[mcp-qdrant] ✓ Configuration complete"
 HOOK_EOF

package/.devcontainer/features/mcp-reasoner/devcontainer-feature.json

@@ -6,6 +6,11 @@
   "maintainer": "AnExiledDev",
   "documentationURL": "https://github.com/Jacck/mcp-reasoner",
   "options": {
+    "version": {
+      "type": "string",
+      "description": "Version to install (or 'none' to skip installation)",
+      "default": "latest"
+    },
     "username": {
       "type": "string",
       "description": "Container user to install for",
@@ -15,6 +20,6 @@
   "installsAfter": [
     "ghcr.io/devcontainers/features/node:1",
     "ghcr.io/devcontainers/features/common-utils:2",
-    "./features/claude-code"
+    "ghcr.io/anthropics/devcontainer-features/claude-code:1"
   ]
 }

package/.devcontainer/features/mcp-reasoner/install.sh

@@ -4,8 +4,15 @@ set -euo pipefail
 # No cleanup needed - using CLI instead of temp files
 
 # Import options
+VERSION="${VERSION:-latest}"
 USERNAME="${USERNAME:-automatic}"
 
+# Skip installation if version is "none"
+if [ "${VERSION}" = "none" ]; then
+    echo "[mcp-reasoner] Skipping installation (version=none)"
+    exit 0
+fi
+
 echo "[mcp-reasoner] Starting MCP Reasoner installation..."
 
 # Source NVM (Node is installed via NVM by the node feature)
@@ -145,7 +152,7 @@ fi
 
 # Set proper permissions
 chmod 644 "$SETTINGS_FILE"
-chown vscode:vscode "$SETTINGS_FILE" 2>/dev/null || true
+chown "$(id -un):$(id -gn)" "$SETTINGS_FILE" 2>/dev/null || true
 
 echo "[mcp-reasoner] ✓ Configuration complete"
 HOOK_EOF

package/.devcontainer/features/notify-hook/devcontainer-feature.json

@@ -5,6 +5,11 @@
   "description": "Desktop notifications and audio chime when Claude finishes responding",
   "documentationURL": "https://github.com/AnExiledDev/CodeForge",
   "options": {
+    "version": {
+      "type": "string",
+      "description": "Version to install (or 'none' to skip installation)",
+      "default": "latest"
+    },
     "enableBell": {
       "type": "boolean",
       "description": "Enable terminal bell (audio chime) on completion",

package/.devcontainer/features/notify-hook/install.sh

@@ -1,9 +1,16 @@
 #!/bin/bash
 set -euo pipefail
 
+VERSION="${VERSION:-latest}"
 ENABLEBELL="${ENABLEBELL:-true}"
 ENABLEOSC="${ENABLEOSC:-true}"
 
+# Skip installation if version is "none"
+if [ "${VERSION}" = "none" ]; then
+    echo "[notify-hook] Skipping installation (version=none)"
+    exit 0
+fi
+
 echo "[notify-hook] Starting installation..."
 echo "[notify-hook] Bell enabled: ${ENABLEBELL}"
 echo "[notify-hook] OSC notifications enabled: ${ENABLEOSC}"

package/.devcontainer/features/ruff/README.md

@@ -0,0 +1,26 @@
+# Ruff
+
+Fast Python linter and formatter, replacing Black + Flake8.
+
+## What It Does
+
+Installs [Ruff](https://docs.astral.sh/ruff/) via `uv tool install`. Ruff is an extremely fast Python linter and formatter written in Rust, compatible with Flake8, isort, and Black rules.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `latest` | Ruff version to install. Set `"none"` to skip. |
+| `username` | `automatic` | Container user to install for. |
+
+## Usage
+
+```bash
+ruff check .              # lint
+ruff check --fix .        # lint and auto-fix
+ruff format .             # format (Black-compatible)
+```
+
+## Configuration
+
+Used by both `auto-formatter` (formatting) and `auto-linter` (linting) plugins for Python files. For project-specific config, add a `[tool.ruff]` section to `pyproject.toml` or create a `ruff.toml`. See [Ruff docs](https://docs.astral.sh/ruff/configuration/).

package/.devcontainer/features/ruff/devcontainer-feature.json

@@ -0,0 +1,21 @@
+{
+  "id": "ruff",
+  "version": "1.0.0",
+  "name": "Ruff",
+  "description": "Fast Python linter and formatter (replaces Black + Flake8)",
+  "options": {
+    "version": {
+      "type": "string",
+      "default": "latest",
+      "description": "Ruff version to install"
+    },
+    "username": {
+      "type": "string",
+      "default": "automatic",
+      "description": "Container user to install for"
+    }
+  },
+  "installsAfter": [
+    "ghcr.io/devcontainers-extra/features/uv"
+  ]
+}

package/.devcontainer/features/ruff/install.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+set -euo pipefail
+
+# ==============================
+# Ruff DevContainer Feature
+# Installs via uv tool install
+# ==============================
+
+RUFF_VERSION="${VERSION:-latest}"
+USERNAME="${USERNAME:-automatic}"
+
+# Skip installation if version is "none"
+if [ "${RUFF_VERSION}" = "none" ]; then
+    echo "[ruff] Skipping installation (version=none)"
+    exit 0
+fi
+
+echo "[ruff] Starting installation..."
+
+# ---------- USER ----------
+if [[ "${USERNAME}" == "auto" || "${USERNAME}" == "automatic" ]]; then
+    for u in vscode node codespace; do
+        if id -u "$u" >/dev/null 2>&1; then
+            USERNAME="$u"
+            break
+        fi
+    done
+    USERNAME="${USERNAME:-root}"
+fi
+
+USER_HOME="$(eval echo "~${USERNAME}")"
+
+echo "[ruff] Target user: ${USERNAME}"
+echo "[ruff] Version: ${RUFF_VERSION}"
+
+run_as_user() {
+    sudo -u "${USERNAME}" env \
+        HOME="${USER_HOME}" \
+        "$@"
+}
+
+# ---------- UV DISCOVERY ----------
+find_uv() {
+    command -v uv 2>/dev/null && return 0
+    for p in /usr/local/bin/uv /usr/bin/uv /opt/uv/bin/uv; do
+        [[ -x "$p" ]] && echo "$p" && return 0
+    done
+    find /usr /opt -maxdepth 4 -type f -name uv -executable 2>/dev/null | head -n 1
+}
+
+# ---------- INSTALL ----------
+UV_BIN="$(find_uv || true)"
+if [[ -z "${UV_BIN}" ]]; then
+    echo "[ruff] ERROR: uv is not installed" >&2
+    exit 1
+fi
+
+echo "[ruff] Using uv at: ${UV_BIN}"
+
+if [[ "${RUFF_VERSION}" == "latest" ]]; then
+    run_as_user "${UV_BIN}" tool install ruff
+else
+    run_as_user "${UV_BIN}" tool install "ruff==${RUFF_VERSION}"
+fi
+
+# ---------- VERIFY ----------
+BIN_DIR="${USER_HOME}/.local/bin"
+if [[ -x "${BIN_DIR}/ruff" ]]; then
+    INSTALLED="$("${BIN_DIR}/ruff" --version 2>/dev/null || echo "unknown")"
+    echo "[ruff] Installed: ${INSTALLED}"
+else
+    echo "[ruff] ERROR: ruff not found in ${BIN_DIR}" >&2
+    exit 1
+fi

package/.devcontainer/features/shellcheck/README.md

@@ -0,0 +1,38 @@
+# ShellCheck
+
+Static analysis tool for shell scripts.
+
+## What It Does
+
+Installs [ShellCheck](https://www.shellcheck.net/) via apt. ShellCheck finds bugs and style issues in bash/sh/zsh scripts, catching common pitfalls like unquoted variables, incorrect test syntax, and POSIX compatibility issues.
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `version` | `latest` | Version to install (or `"none"` to skip). |
+
+## Usage
+
+```bash
+shellcheck script.sh
+shellcheck -x script.sh           # follow source'd files
+shellcheck -f json script.sh      # JSON output
+shellcheck -e SC2086 script.sh    # exclude specific rule
+```
+
+## Configuration
+
+Used by the `auto-linter` plugin to lint shell scripts. For per-file directives, add comments at the top of your script:
+
+```bash
+# shellcheck disable=SC2086
+# shellcheck shell=bash
+```
+
+For project-wide config, create a `.shellcheckrc`:
+
+```
+disable=SC2086,SC2034
+shell=bash
+```

package/.devcontainer/features/shellcheck/devcontainer-feature.json

@@ -0,0 +1,13 @@
+{
+  "id": "shellcheck",
+  "version": "1.0.0",
+  "name": "ShellCheck",
+  "description": "Static analysis tool for shell scripts",
+  "options": {
+    "version": {
+      "type": "string",
+      "description": "Version to install (or 'none' to skip installation)",
+      "default": "latest"
+    }
+  }
+}

package/.devcontainer/features/shellcheck/install.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+set -euo pipefail
+
+# ==============================
+# ShellCheck DevContainer Feature
+# Installed via apt
+# ==============================
+
+VERSION="${VERSION:-latest}"
+
+# Skip installation if version is "none"
+if [ "${VERSION}" = "none" ]; then
+    echo "[shellcheck] Skipping installation (version=none)"
+    exit 0
+fi
+
+echo "[shellcheck] Starting installation..."
+
+apt-get update -y
+apt-get install -y --no-install-recommends shellcheck
+apt-get clean -y
+rm -rf /var/lib/apt/lists/*
+
+echo "[shellcheck] Installed: $(shellcheck --version 2>/dev/null | head -2 || echo 'unknown')"