@vyuhlabs/dxkit 2.4.8 → 2.5.0

package/templates/.devcontainer/devcontainer.json

@@ -0,0 +1,81 @@
+{
+  "name": "dxkit dev environment",
+
+  // Universal base + composable features. Each language pack dxkit
+  // supports has a corresponding feature here so the same image works
+  // for monorepos that span multiple ecosystems. Tune by removing
+  // features your project does not need — smaller image, faster
+  // Codespaces prebuild.
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-22.04",
+
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": {
+      "version": "22",
+      "nvmVersion": "latest"
+    },
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.12",
+      "installTools": true
+    },
+    "ghcr.io/devcontainers/features/go:1": {
+      "version": "1.21"
+    },
+    "ghcr.io/devcontainers/features/dotnet:2": {
+      "version": "8.0"
+    },
+    "ghcr.io/devcontainers/features/ruby:1": {
+      "version": "3.3"
+    },
+    "ghcr.io/devcontainers/features/java:1": {
+      "version": "17",
+      "installGradle": true
+    },
+    "ghcr.io/devcontainers/features/rust:1": {
+      "version": "stable",
+      "profile": "default"
+    },
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+
+  // Reproducibility note: language toolchains are pinned in the
+  // features block above. Scanner tools (gitleaks, semgrep, cloc,
+  // jscpd, ruff, osv-scanner, ...) are pinned in dxkit's TOOL_DEFS
+  // registry and installed by `vyuh-dxkit tools install --yes` in
+  // post-create.sh. Bumping a scanner version is a dxkit upgrade,
+  // not a Dockerfile edit.
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+
+  // Run on every container start (incl. Codespaces resume). Keeps
+  // `dxkit tools list` accurate if a tool was uninstalled or the
+  // registry pinned-versions advanced since last use.
+  "postStartCommand": "command -v vyuh-dxkit >/dev/null 2>&1 && vyuh-dxkit tools list || true",
+
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "ms-python.python",
+        "ms-python.vscode-pylance",
+        "golang.go",
+        "rust-lang.rust-analyzer",
+        "ms-dotnettools.csharp",
+        "redhat.java",
+        "fwcd.kotlin",
+        "rebornix.ruby",
+        "github.vscode-github-actions",
+        "github.vscode-pull-request-github"
+      ],
+      "settings": {
+        "editor.formatOnSave": true,
+        "files.eol": "\n"
+      }
+    }
+  },
+
+  "remoteUser": "vscode",
+
+  // Forward dxkit's HTTP analyzer dashboard if you run it locally.
+  "forwardPorts": []
+}

package/templates/.devcontainer/install-agent-clis.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+#
+# Install the AI coding-agent CLIs that pair with dxkit's commit-time
+# guardrails. Pinned versions so devcontainer rebuilds produce a
+# deterministic environment; bump these intentionally.
+#
+# Both CLIs are published to npm and install globally into the
+# devcontainer image's Node toolchain (provided by the features
+# block in devcontainer.json).
+
+set -euo pipefail
+
+# Pinned at devcontainer template publish time. Loosen to `@latest`
+# if you want each container start to pull the newest CLI — at the
+# cost of non-deterministic builds. Set to `skip` to skip the install
+# entirely (useful if you only use one of the two agents).
+CLAUDE_CODE_VERSION="${CLAUDE_CODE_VERSION:-latest}"
+CODEX_VERSION="${CODEX_VERSION:-latest}"
+
+if [ "${CLAUDE_CODE_VERSION}" = "skip" ]; then
+  echo "==> Claude Code CLI install skipped (CLAUDE_CODE_VERSION=skip)."
+else
+  echo "==> Installing Claude Code CLI..."
+  if command -v claude >/dev/null 2>&1; then
+    echo "    Already installed: $(claude --version 2>&1 | head -n1)"
+  else
+    npm install -g "@anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}" \
+      || echo "WARN: Claude Code install failed — try manually with 'npm install -g @anthropic-ai/claude-code'." >&2
+  fi
+fi
+
+if [ "${CODEX_VERSION}" = "skip" ]; then
+  echo "==> OpenAI Codex CLI install skipped (CODEX_VERSION=skip)."
+else
+  echo "==> Installing OpenAI Codex CLI..."
+  if command -v codex >/dev/null 2>&1; then
+    echo "    Already installed: $(codex --version 2>&1 | head -n1)"
+  else
+    npm install -g "@openai/codex@${CODEX_VERSION}" \
+      || echo "WARN: Codex CLI install failed — try manually with 'npm install -g @openai/codex'." >&2
+  fi
+fi

package/templates/.devcontainer/post-create.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Devcontainer post-create. Runs once after the container is built
+# (and again on Codespaces prebuild). Idempotent — safe to re-run.
+#
+# Responsibilities:
+#   1. Install project dependencies if this is a Node project.
+#   2. Ensure dxkit is on PATH (project-local first, global fallback).
+#   3. Install dxkit's scanner toolchain (gitleaks, semgrep, cloc, etc.)
+#      via the TOOL_DEFS registry — pinned versions, language-aware.
+#   4. Install the AI coding-agent CLIs for the AI-native dev loop.
+#
+# Run from the repo root — the devcontainer's workspaceFolder is set
+# by `devcontainer.json` so the post-create command starts there.
+
+set -euo pipefail
+
+echo "==> dxkit post-create starting in $(pwd)"
+
+# Install project dependencies if this is a Node project. Soft-fail
+# the whole step: a lockfile that won't resolve (tarball moved,
+# private-registry auth not configured yet, peer-dep churn) is
+# annoying but shouldn't take down the rest of the post-create. The
+# user can re-run `npm install` after authenticating or fixing the
+# lockfile.
+if [ -f package.json ]; then
+  echo "==> Installing project dependencies..."
+  if [ -f package-lock.json ]; then
+    npm ci || npm install || {
+      echo "WARN: project dependency install failed — re-run 'npm install' manually if needed." >&2
+    }
+  else
+    npm install || {
+      echo "WARN: project dependency install failed — re-run 'npm install' manually if needed." >&2
+    }
+  fi
+fi
+
+# Resolve dxkit. Prefer the project-local install if a `package.json`
+# pinned dxkit in devDependencies; otherwise install globally so the
+# binary is on PATH for the rest of the script and any subshell.
+if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+  DXKIT="./node_modules/.bin/vyuh-dxkit"
+elif command -v vyuh-dxkit >/dev/null 2>&1; then
+  DXKIT="vyuh-dxkit"
+else
+  echo "==> Installing @vyuhlabs/dxkit globally..."
+  npm install -g @vyuhlabs/dxkit
+  DXKIT="vyuh-dxkit"
+fi
+echo "==> Using dxkit binary: ${DXKIT}"
+
+echo "==> Installing scanner toolchain via dxkit registry..."
+# `tools install --yes` reads the detector's required-tools list and
+# runs the pinned install command for each one. Tools already present
+# are no-ops, so this is fast on warm containers. Soft-fail so a
+# single tool's install hiccup doesn't break the whole container.
+"${DXKIT}" tools install --yes || {
+  echo "WARN: some scanner tools failed to install — run 'vyuh-dxkit tools list' to see status." >&2
+}
+
+echo "==> Installing AI coding-agent CLIs..."
+bash "$(dirname "$0")/install-agent-clis.sh" || {
+  echo "WARN: agent CLI install had issues — install manually if needed." >&2
+}
+
+echo "==> dxkit post-create done. Run 'vyuh-dxkit health' to verify."

package/templates/.githooks/pre-commit

@@ -0,0 +1,55 @@
+#!/usr/bin/env sh
+#
+# dxkit pre-commit hook — fast guardrail check against the baseline.
+#
+# Runs `vyuh-dxkit guardrail check --changed-only` so only findings
+# overlapping lines you just changed can block the commit. The full
+# guardrail (without --changed-only) runs in the pre-push hook and
+# in the CI PR-gate workflow; this one prioritises feedback speed.
+#
+# Install:
+#   git config core.hooksPath .githooks
+#
+# Escape hatches:
+#   DXKIT_SKIP_HOOKS=1 git commit ...     # one-off bypass
+#   git commit --no-verify ...            # standard git bypass
+#
+# First-time setup: this hook does NOT block when no baseline exists
+# yet. Run `vyuh-dxkit baseline create` once to capture today's state,
+# then commits start being gated against it.
+
+set -e
+
+if [ "${DXKIT_SKIP_HOOKS:-0}" = "1" ]; then
+  echo "[dxkit pre-commit] DXKIT_SKIP_HOOKS=1 set — skipping guardrail check."
+  exit 0
+fi
+
+# Resolve the dxkit binary: prefer the project-local install, fall
+# back to a global one. We deliberately do NOT shell out to `npx`
+# here — npx may try to fetch from the registry, which makes the
+# hook fail offline and slow down every commit.
+if [ -x "./node_modules/.bin/vyuh-dxkit" ]; then
+  DXKIT="./node_modules/.bin/vyuh-dxkit"
+elif command -v vyuh-dxkit >/dev/null 2>&1; then
+  DXKIT="vyuh-dxkit"
+else
+  echo "[dxkit pre-commit] vyuh-dxkit not found on PATH or in ./node_modules/.bin." >&2
+  echo "  Install it with: npm install --save-dev @vyuhlabs/dxkit" >&2
+  echo "  Or skip this hook for this commit: DXKIT_SKIP_HOOKS=1 git commit ..." >&2
+  exit 1
+fi
+
+BASELINE_NAME="${DXKIT_BASELINE_NAME:-main}"
+BASELINE_FILE=".dxkit/baselines/${BASELINE_NAME}.json"
+
+if [ ! -f "${BASELINE_FILE}" ]; then
+  echo "[dxkit pre-commit] No baseline at ${BASELINE_FILE} — not blocking."
+  echo "  Run \`${DXKIT} baseline create\` once to start gating commits."
+  exit 0
+fi
+
+# `--changed-only` restricts blocking to findings whose anchor line
+# overlaps the diff between the baseline's anchor commit and HEAD.
+# Pre-commit is fast-mode by design; the pre-push hook runs full.
+"${DXKIT}" guardrail check --changed-only --name "${BASELINE_NAME}"

package/templates/.githooks/pre-push

@@ -0,0 +1,63 @@
+#!/usr/bin/env sh
+#
+# dxkit pre-push hook — full guardrail check against the baseline.
+#
+# Runs the full `vyuh-dxkit guardrail check` (no --changed-only),
+# so every regression introduced since the baseline blocks the push.
+# Slower than pre-commit, but the push boundary is the last point
+# we can stop bad code from leaving the developer's machine.
+#
+# Install:
+#   git config core.hooksPath .githooks
+#
+# Escape hatches:
+#   DXKIT_SKIP_HOOKS=1 git push ...       # one-off bypass
+#   git push --no-verify ...              # standard git bypass
+
+set -e
+
+if [ "${DXKIT_SKIP_HOOKS:-0}" = "1" ]; then
+  echo "[dxkit pre-push] DXKIT_SKIP_HOOKS=1 set — skipping guardrail check."
+  exit 0
+fi
+
+# Delete-only pushes (e.g. `git push origin --delete <branch>`) carry
+# no commits to gate. Git invokes pre-push with stdin lines of the
+# form: <local-ref> <local-sha> <remote-ref> <remote-sha>. A delete
+# has local-sha = 40 zeros. Skip rather than failing the gate on an
+# empty diff.
+all_zero=true
+while read -r _local_ref local_sha _remote_ref _remote_sha; do
+  if [ "${local_sha}" != "0000000000000000000000000000000000000000" ]; then
+    all_zero=false
+    break
+  fi
+done
+if [ "${all_zero}" = "true" ]; then
+  echo "[dxkit pre-push] Delete-only push detected — skipping guardrail check."
+  exit 0
+fi
+
+# Resolve the dxkit binary: prefer the project-local install, fall
+# back to a global one. Match the pre-commit hook's resolution order.
+if [ -x "./node_modules/.bin/vyuh-dxkit" ]; then
+  DXKIT="./node_modules/.bin/vyuh-dxkit"
+elif command -v vyuh-dxkit >/dev/null 2>&1; then
+  DXKIT="vyuh-dxkit"
+else
+  echo "[dxkit pre-push] vyuh-dxkit not found on PATH or in ./node_modules/.bin." >&2
+  echo "  Install it with: npm install --save-dev @vyuhlabs/dxkit" >&2
+  echo "  Or skip this hook for this push: DXKIT_SKIP_HOOKS=1 git push ..." >&2
+  exit 1
+fi
+
+BASELINE_NAME="${DXKIT_BASELINE_NAME:-main}"
+BASELINE_FILE=".dxkit/baselines/${BASELINE_NAME}.json"
+
+if [ ! -f "${BASELINE_FILE}" ]; then
+  echo "[dxkit pre-push] No baseline at ${BASELINE_FILE} — not blocking."
+  echo "  Run \`${DXKIT} baseline create\` once to start gating pushes."
+  exit 0
+fi
+
+"${DXKIT}" guardrail check --name "${BASELINE_NAME}"

package/templates/.github/workflows/dxkit-baseline-refresh.yml

@@ -0,0 +1,78 @@
+name: dxkit baseline refresh
+
+# After every merge to main, regenerate `.dxkit/baselines/main.json`
+# to capture the new "approved" state of the repo. The next PR's
+# guardrail check is gated against this refreshed anchor, so a
+# regression introduced in PR N+1 stands out from the noise of
+# whatever was merged in PR N.
+#
+# The auto-commit carries `[skip ci]` so it doesn't re-trigger this
+# workflow or the guardrails PR-gate.
+
+on:
+  push:
+    branches: [__DXKIT_DEFAULT_BRANCH__]
+    # Ignore pushes that only changed the baseline file — those are
+    # this workflow's own commits, and re-running would be a no-op
+    # anyway. Belt-and-braces with [skip ci] below.
+    paths-ignore:
+      - '.dxkit/baselines/**'
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    # Don't re-run on our own auto-commit (defensive — paths-ignore
+    # above already filters the common case).
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') }}
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          # `persist-credentials: true` (the default) leaves the
+          # token in .git/config so the final `git push` reuses it.
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      - name: Install dxkit
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          else
+            npm install -g @vyuhlabs/dxkit
+          fi
+
+      - name: Install scanner tools
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            ./node_modules/.bin/vyuh-dxkit tools install --yes
+          else
+            vyuh-dxkit tools install --yes
+          fi
+
+      - name: Recompute baseline
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            DXKIT=./node_modules/.bin/vyuh-dxkit
+          else
+            DXKIT=vyuh-dxkit
+          fi
+          "${DXKIT}" baseline create --force
+
+      - name: Commit and push refreshed baseline
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet -- .dxkit/baselines/; then
+            echo "Baseline unchanged — nothing to commit."
+            exit 0
+          fi
+          git add .dxkit/baselines/
+          git commit -m "chore(baseline): refresh main anchor [skip ci]"
+          git push

package/templates/.github/workflows/dxkit-guardrails.yml

@@ -0,0 +1,98 @@
+name: dxkit guardrails
+
+# Runs the dxkit guardrail check on every pull request. New regressions
+# vs. the committed `.dxkit/baselines/main.json` block the PR. Existing
+# findings (your "brownfield debt") are allowed — they were already
+# captured when you ran `vyuh-dxkit baseline create`.
+#
+# Customise by editing your project's `.dxkit/policy.json` (created by
+# `vyuh-dxkit init --with-ci`). The matcher's classifications
+# (added / relocated / tooling_drift / config_drift / persisted /
+# removed / fixed) map to block/warn buckets there.
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  guardrail:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Full history so the git-aware matcher can resolve the
+          # baseline's anchor commit + diff against HEAD.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+
+      # Install dxkit. Prefers a project-local install (devDependencies)
+      # so the version is pinned alongside the project. Falls back to a
+      # global install for non-JS projects.
+      - name: Install dxkit
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          else
+            npm install -g @vyuhlabs/dxkit
+          fi
+
+      # Install the scanner toolchain dxkit needs for this stack
+      # (gitleaks, semgrep, cloc, jscpd, ruff, osv-scanner, etc.).
+      # `--yes` makes the install non-interactive; the registry
+      # decides what to install based on detected languages.
+      - name: Install scanner tools
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            ./node_modules/.bin/vyuh-dxkit tools install --yes
+          else
+            vyuh-dxkit tools install --yes
+          fi
+
+      # Capture the markdown report regardless of exit code so we can
+      # post it as a PR comment even when the guardrail blocks.
+      - name: Run guardrail check
+        id: guardrail
+        run: |
+          if [ -x ./node_modules/.bin/vyuh-dxkit ]; then
+            DXKIT=./node_modules/.bin/vyuh-dxkit
+          else
+            DXKIT=vyuh-dxkit
+          fi
+          set +e
+          "${DXKIT}" guardrail check --markdown > guardrail-report.md
+          echo "exit_code=$?" >> "$GITHUB_OUTPUT"
+
+      - name: Post PR comment
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          # Find a previous dxkit-guardrails comment by marker so we
+          # update in place rather than appending a new one per push.
+          MARKER='<!-- dxkit-guardrails -->'
+          {
+            printf '%s\n' "$MARKER"
+            cat guardrail-report.md
+          } > comment.md
+          existing=$(gh api "repos/${{ github.repository }}/issues/${PR_NUMBER}/comments" \
+            --jq ".[] | select(.body | startswith(\"${MARKER}\")) | .id" \
+            | head -n1)
+          if [ -n "${existing}" ]; then
+            gh api -X PATCH \
+              "repos/${{ github.repository }}/issues/comments/${existing}" \
+              -F body=@comment.md
+          else
+            gh pr comment "${PR_NUMBER}" --body-file comment.md
+          fi
+
+      - name: Fail if guardrail blocked
+        run: exit ${{ steps.guardrail.outputs.exit_code }}