@jesdi/skills 0.0.14 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/crap-gate/SKILL.md

@@ -2,7 +2,7 @@
 name: crap-gate
 description: >-
   Score every function a branch changed with CRAP (cyclomatic complexity ×
-  untested fraction), fail on existing functions > 15 and new functions > 9,
+  untested fraction), fail on existing functions above 15 and new functions above 9,
   and drive a fixer + independent reviewer loop until the gate passes. Use
   when implementation is done and before pushing, when the user says "run the
   crap gate", "check CRAP", "is this change tested enough", or when a push
@@ -21,16 +21,19 @@ is the human approval gate at push time.
 
 ## Running the engine
 
-The engine ships with this skill and is stdlib-only Python (plus `node` and
-the project's own `typescript` package for TS/TSX targets). Run it from
-anywhere inside the repo — it walks up to `.crap-gate.json`:
+Use the bundled launcher on macOS or Linux (x86_64/ARM64; Windows via WSL).
+It downloads checksum-verified uv 0.12.13 and provisions private Python 3.13.7
+on first use, then reuses them across repositories. No global Python, uv,
+virtualenv activation, or pip installation is needed. The engine uses only
+Python's standard library and supports Python source syntax through 3.13.
+Run from anywhere inside the repo — it walks up to `.crap-gate.json`:
 
 ```bash
-python3 <skill-dir>/crap.py            # human table, exit 1 on violations
-python3 <skill-dir>/crap.py --json     # same data for a subagent prompt
-python3 <skill-dir>/crap.py --no-run   # reuse the last coverage reports
-python3 <skill-dir>/crap.py --all      # whole-repo baseline (exploration only)
-python3 <skill-dir>/crap.py --base main --threshold-new 7   # local what-ifs
+sh "<skill-dir>/run.sh"            # human table, exit 1 on violations
+sh "<skill-dir>/run.sh" --json     # same data for a subagent prompt
+sh "<skill-dir>/run.sh" --no-run   # reuse the last coverage reports
+sh "<skill-dir>/run.sh" --all      # whole-repo baseline (exploration only)
+sh "<skill-dir>/run.sh" --base main --threshold-new 7   # local what-ifs
 ```
 
 `<skill-dir>` is wherever this skill is installed (`.agents/skills/crap-gate`,
@@ -40,13 +43,37 @@ wrap it (`make crap`); prefer the wrapper when one exists.
 When you point a wrapper at an agent symlink, that symlink only exists after
 `skills-cli sync` if the matching agent is declared for the skill in
 `.my-skills.json` — `claude` → `.claude/skills/crap-gate`, `opencode` →
-`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/crap.py`
+`.agents/skills/crap-gate`. A wrapper that runs `.agents/skills/crap-gate/run.sh`
 therefore needs `"agents": ["opencode"]` (or `["claude", "opencode"]`) on the
 `crap-gate` entry, or a fresh checkout/worktree will lack that path after `sync`.
-The store copy `.my-skills/crap-gate/crap.py` is always materialized regardless
+The store copy `.my-skills/crap-gate/run.sh` is always materialized regardless
 of declared agents, so wrapping against it avoids the agent/path coupling
 entirely.
 
+Existing `make crap` / `make crap-gate` wrappers must replace `python3 .../crap.py`
+with `sh .../run.sh` (quote the path). Prefer the store path, for example:
+
+```makefile
+crap crap-gate:
+	sh "$(CURDIR)/.my-skills/crap-gate/run.sh"
+```
+
+The launcher needs standard shell utilities, `curl`, `tar`, and `sha256sum`
+or `shasum`. Its cache defaults to `${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate`;
+set `CRAP_GATE_CACHE_DIR` to an absolute path to relocate it. To pre-provision,
+run the launcher with `--help` while online. `CRAP_GATE_OFFLINE=1` then requires
+that populated cache and prevents runtime downloads. Runtime setup messages go
+to stderr; `--json` returns a structured error on setup failure, with exit 2.
+Do not bypass the gate or repair global Python when setup fails; resolve the
+reported download/cache problem and rerun the launcher.
+
+TypeScript targets still need `node` and the project's own `typescript` package.
+Coverage commands still need the project's test dependencies; configure them
+with its normal runner (for example, `cd backend && pipenv run pytest ...`).
+The launcher preserves PATH and the caller's environment for these commands;
+its private Python is only for the gate engine. It does not install project
+dependencies or edit project environments.
+
 By default the engine runs each target's coverage command only when that
 target has changed files, so a backend-only change never runs the frontend
 suite. Coverage command output goes to `.crap/<target>.log`.

package/skills/crap-gate/crap.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """crap-gate engine: CRAP score for every function a branch changed.
 
-    python3 crap.py [--config PATH] [--base REF] [--threshold-existing N]
+    sh run.sh [--config PATH] [--base REF] [--threshold-existing N]
                     [--threshold-new N] [--run | --no-run] [--all] [--json]
 
 Exit 0 = no violations, 1 = violations, 2 = configuration/tool error.
@@ -11,12 +11,22 @@ project's own `typescript` package.
 from __future__ import annotations
 
 import argparse
+import json
 import subprocess
 import sys
 import tempfile
 import time
 from pathlib import Path
 
+# Direct invocation remains useful for development, but should fail clearly
+# before importing an analyzer that requires newer AST nodes.
+if sys.version_info < (3, 10):
+    message = "Use the bundled run.sh launcher; direct execution requires Python >= 3.10"
+    print(f"crap: {message}", file=sys.stderr)
+    if "--json" in sys.argv:
+        print(json.dumps({"error": {"kind": "tooling", "message": message}}))
+    sys.exit(2)
+
 import crap_git
 import crap_python
 import crap_typescript
@@ -201,6 +211,8 @@ def main(argv: list[str] | None = None) -> int:
         result = run(cfg, run_mode=args.run_mode, all_functions=args.all)
     except ToolError as exc:
         print(f"crap: {exc}", file=sys.stderr)
+        if args.json:
+            print(json.dumps({"error": {"kind": "tooling", "message": str(exc)}}))
         return 2
     sys.stdout.write(render_json(result) if args.json else render_text(result))
     return 1 if result.summary["fail"] else 0

package/skills/crap-gate/run.sh

@@ -0,0 +1,87 @@
+#!/bin/sh
+# Keep bootstrap dependencies to POSIX tools, curl, tar, and SHA-256.
+set -eu
+
+json=false
+for arg in "$@"; do
+    [ "$arg" != --json ] || json=true
+done
+fail() {
+    printf 'crap: %s\n' "$1" >&2
+    if "$json"; then
+        printf '%s\n' '{"error":{"kind":"tooling","message":"Runtime setup failed; see stderr. Run the launcher again after resolving the setup error."}}'
+    fi
+    exit 2
+}
+
+# Resolve file symlinks as well as symlinked skill directories.
+entry=$0
+while [ -L "$entry" ]; do
+    parent=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+    entry=$(readlink "$entry")
+    case "$entry" in /*) ;; *) entry=$parent/$entry ;; esac
+done
+skill_dir=$(CDPATH= cd -- "$(dirname -- "$entry")" && pwd)
+cache=${CRAP_GATE_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/crap-gate}
+case "$cache" in /*) ;; *) fail 'CRAP_GATE_CACHE_DIR must be an absolute path' ;; esac
+uv_version=0.12.13
+python_version=3.13.7
+case "$(uname -s):$(uname -m)" in
+    Darwin:arm64|Darwin:aarch64)
+        target=aarch64-apple-darwin
+        digest=7e6ddb9316acc00f2296c82ff4d99977870ee34b2f0ddcae9444d714db9364ed ;;
+    Darwin:x86_64)
+        target=x86_64-apple-darwin
+        digest=5e287ef61cb6a9b61b3a83fef124fd143e400468a7dac794230147a810e17119 ;;
+    Linux:aarch64|Linux:arm64)
+        target=aarch64-unknown-linux-musl
+        digest=f44bc1037a17889fe562fffd2002d4ed108e499fbe68b4f022af244dc7b8244f ;;
+    Linux:x86_64)
+        target=x86_64-unknown-linux-musl
+        digest=4e2bfd0c9007b1032a50e539e965fd0a6037d87ad93ae1580d220a92d4c94098 ;;
+    *) fail 'Unsupported platform: use macOS or Linux on x86_64 or ARM64 (Windows: WSL)' ;;
+esac
+uv_dir=$cache/uv/$uv_version/$target
+uv=$uv_dir/uv
+if [ ! -x "$uv" ]; then
+    [ "${CRAP_GATE_OFFLINE:-0}" != 1 ] || fail 'uv is not cached; provision this cache online first'
+    mkdir -p "$uv_dir" || fail 'Cannot create runtime cache'
+    stage=$(mktemp -d "$uv_dir/.download.XXXXXX") || fail 'Cannot create download directory'
+    trap 'rm -rf "$stage"' EXIT
+    trap 'exit 2' HUP INT TERM
+    printf 'crap: downloading uv %s\n' "$uv_version" >&2
+    curl --fail --location --silent --show-error --connect-timeout 15 --max-time 300 \
+        "https://github.com/astral-sh/uv/releases/download/$uv_version/uv-$target.tar.gz" \
+        -o "$stage/uv.tar.gz" || fail 'Cannot download uv; check network access and retry'
+    if command -v sha256sum >/dev/null 2>&1; then
+        actual=$(sha256sum "$stage/uv.tar.gz")
+    elif command -v shasum >/dev/null 2>&1; then
+        actual=$(shasum -a 256 "$stage/uv.tar.gz")
+    else
+        fail 'SHA-256 verification requires sha256sum or shasum'
+    fi
+    [ "${actual%% *}" = "$digest" ] || fail 'uv archive checksum mismatch'
+    tar -xzf "$stage/uv.tar.gz" -C "$stage" || fail 'Cannot extract uv'
+    # Atomic publication: concurrent first runs never see a partial executable.
+    mv -f "$stage/uv-$target/uv" "$uv" || fail 'Cannot install cached uv'
+    rm -rf "$stage"
+    trap - EXIT HUP INT TERM
+fi
+
+# Limit uv settings to this subprocess. Do not activate a venv or change PATH:
+# coverage commands must inherit the caller's project environment unchanged.
+managed_uv() (
+    unset UV_NO_MANAGED_PYTHON UV_PYTHON UV_PYTHON_DOWNLOADS UV_PYTHON_BIN_DIR
+    export UV_PYTHON_INSTALL_DIR="$cache/python"
+    export UV_CACHE_DIR="$cache/uv-cache"
+    export UV_MANAGED_PYTHON=true
+    "$uv" --no-config "$@"
+)
+python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version" 2>/dev/null) || {
+    [ "${CRAP_GATE_OFFLINE:-0}" != 1 ] || fail 'Python is not cached; provision this cache online first'
+    managed_uv python install --no-bin "$python_version" >&2 || fail 'Cannot provision Python; check network access and retry'
+    python=$(managed_uv python find --no-project --system --managed-python --no-python-downloads "$python_version") || fail 'Cannot locate managed Python'
+}
+# Ignore Python-specific ambient settings for the engine, but preserve them for
+# child coverage processes. -I would also remove the sibling module directory.
+exec "$python" -E -s "$skill_dir/crap.py" "$@"

package/skills/crap-gate/test_launcher.py

@@ -0,0 +1,116 @@
+"""Launcher regressions. Real-runtime cases use a pre-provisioned cache in CI."""
+import json
+import os
+from pathlib import Path
+import shutil
+import subprocess
+
+import pytest
+
+from test_cli import BASE_SRC, repo  # noqa: F401 — shared git repository fixture
+
+LAUNCHER = Path(__file__).with_name("run.sh").resolve()
+
+
+def launch(env, *args, cwd=None, script=LAUNCHER):
+    return subprocess.run(
+        ["/bin/sh", str(script), *args], env=env, cwd=cwd,
+        text=True, capture_output=True, timeout=60,
+    )
+
+
+def test_empty_offline_cache_is_json_tool_error(tmp_path):
+    env = dict(os.environ, CRAP_GATE_CACHE_DIR=str(tmp_path / "cache"), CRAP_GATE_OFFLINE="1")
+    proc = launch(env, "--json")
+    assert proc.returncode == 2
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+    assert "not cached" in proc.stderr
+    assert not (tmp_path / "cache").exists()
+
+
+def test_bad_download_is_rejected_before_execution(tmp_path):
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir()
+    curl = bin_dir / "curl"
+    curl.write_text('#!/bin/sh\nwhile [ "$1" != -o ]; do shift; done\nprintf corrupt > "$2"\n')
+    curl.chmod(0o755)
+    env = dict(os.environ, PATH=f"{bin_dir}:{os.environ['PATH']}",
+               CRAP_GATE_CACHE_DIR=str(tmp_path / "cache"), CRAP_GATE_OFFLINE="0")
+    proc = launch(env, "--json")
+    assert proc.returncode == 2
+    assert "checksum mismatch" in proc.stderr
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+    assert not list((tmp_path / "cache").rglob("uv.tar.gz"))
+    assert not list((tmp_path / "cache").rglob(".download.*"))
+
+
+@pytest.fixture
+def runtime_env():
+    cache = os.environ.get("CRAP_GATE_TEST_CACHE")
+    if not cache:
+        pytest.skip("Set CRAP_GATE_TEST_CACHE to a cache provisioned by run.sh --help")
+    return dict(os.environ, CRAP_GATE_CACHE_DIR=cache, CRAP_GATE_OFFLINE="1")
+
+
+@pytest.mark.parametrize("python_on_path", ["absent", "incompatible"])
+def test_runtime_ignores_host_python_and_preserves_coverage_environment(
+    repo, tmp_path, runtime_env, python_on_path,
+):
+    bin_dir = tmp_path / "host bin"
+    bin_dir.mkdir()
+    for name in ("uname", "dirname", "git", "sh", "env"):
+        (bin_dir / name).symlink_to(shutil.which(name))
+    if python_on_path == "incompatible":
+        for name in ("python", "python3"):
+            executable = bin_dir / name
+            executable.write_text("#!/bin/sh\necho wrong-python >&2\nexit 99\n")
+            executable.chmod(0o755)
+    runtime_env.update(PATH=str(bin_dir), VIRTUAL_ENV=str(tmp_path / "wrong venv"),
+                       PYTHONHOME="/nonexistent-python", PYTHONPATH="/nonexistent-modules")
+    # Both files must be ignored by runtime discovery.
+    (repo / ".python-version").write_text("3.9.6\n")
+    (repo / "uv.toml").write_text("deliberately invalid configuration\n")
+    (repo / "pkg/m.py").write_text(BASE_SRC + "\ndef added():\n    return 1\n")
+    (repo / ".crap").mkdir()
+    cfg = json.loads((repo / ".crap-gate.json").read_text())
+    cfg["targets"][0]["coverage"]["command"] = (
+        "env > coverage-env.txt; printf '%s' '{\"files\":{}}' > .crap/coverage.json"
+    )
+    (repo / ".crap-gate.json").write_text(json.dumps(cfg))
+    proc = launch(runtime_env, "--json", cwd=repo)
+    assert proc.returncode == 0, proc.stderr
+    assert json.loads(proc.stdout)["functions"][0]["name"] == "added"
+    inherited = dict(line.split("=", 1) for line in (repo / "coverage-env.txt").read_text().splitlines())
+    for name in ("PATH", "VIRTUAL_ENV", "PYTHONHOME", "PYTHONPATH"):
+        assert inherited[name] == runtime_env[name]
+    assert "UV_PYTHON_INSTALL_DIR" not in inherited or inherited["UV_PYTHON_INSTALL_DIR"] == os.environ.get("UV_PYTHON_INSTALL_DIR")
+    assert not (repo / ".venv").exists()
+
+
+def test_symlink_spaces_and_exit_codes(repo, tmp_path, runtime_env):
+    link = tmp_path / "launcher link"
+    link.symlink_to(LAUNCHER)
+    (repo / "pkg/m.py").write_text(BASE_SRC + "\ndef unnew(a, b):\n    return a if b else (b if a else 0)\n")
+    (repo / ".crap").mkdir()
+    (repo / ".crap/coverage.json").write_text('{"files":{}}')
+    proc = launch(runtime_env, "--json", "--no-run", cwd=repo, script=link)
+    assert proc.returncode == 1, proc.stderr
+    assert json.loads(proc.stdout)["summary"]["fail"] == 1
+    proc = launch(runtime_env, "--json", "--base", "missing-ref", cwd=repo, script=link)
+    assert proc.returncode == 2
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"
+
+
+def test_offline_cache_missing_python_is_tool_error(tmp_path, runtime_env):
+    original = Path(runtime_env["CRAP_GATE_CACHE_DIR"])
+    cache = tmp_path / "uv only cache"
+    for executable in (original / "uv").rglob("uv"):
+        if executable.is_file():
+            target = cache / executable.relative_to(original)
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.symlink_to(executable)
+    runtime_env["CRAP_GATE_CACHE_DIR"] = str(cache)
+    proc = launch(runtime_env, "--json")
+    assert proc.returncode == 2
+    assert "Python is not cached" in proc.stderr
+    assert json.loads(proc.stdout)["error"]["kind"] == "tooling"

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-07T15:08:46.060Z",
+  "generatedAt": "2026-09-13T13:58:48.949Z",
   "skills": [
     {
       "name": "backlog",
@@ -22,9 +22,9 @@
     },
     {
       "name": "crap-gate",
-      "version": "0.1.2",
-      "hash": "sha256-6f1e0de08917f0b0166959dd25328ed098ce1185cf52996093f2b18b151a9c0a",
-      "description": "Score every function a branch changed with CRAP (cyclomatic complexity × untested fraction), fail on existing functions > 15 and new functions > 9, and drive a fixer + independent reviewer loop until the gate passes. Use when implementation is done and before pushing, when the user says \"run the crap gate\", \"check CRAP\", \"is this change tested enough\", or when a push gate reports CRAP violations."
+      "version": "0.1.3",
+      "hash": "sha256-39041927a985061599a39bb287232b83655ecbac61b7de52486f485991a99d30",
+      "description": "Score every function a branch changed with CRAP (cyclomatic complexity × untested fraction), fail on existing functions above 15 and new functions above 9, and drive a fixer + independent reviewer loop until the gate passes. Use when implementation is done and before pushing, when the user says \"run the crap gate\", \"check CRAP\", \"is this change tested enough\", or when a push gate reports CRAP violations."
     },
     {
       "name": "deep-quality-review",