clean-room-skill 0.1.0

package/skills/clean-room/scripts/clean_room_tool_manager.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Explicit local tool setup for clean-room source-index preflight."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from typing import Any
+
+import clean_room_tooling
+
+
+LOCAL_INSTALL_TIMEOUT_SECONDS = 600
+NPM_TOOLS = {
+    "ast-grep": {
+        "package": "@ast-grep/cli",
+        "source": "https://www.npmjs.com/package/@ast-grep/cli",
+        "bin": "ast-grep",
+    },
+}
+STATUS_TOOLS = [
+    "node",
+    "npm",
+    "ast-grep",
+    "sg",
+    "ctags",
+    "universal-ctags",
+    "scip",
+]
+STATUS_PACKAGES = ["@ast-grep/cli"]
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Report or explicitly install local clean-room source-index helper tools into the user cache."
+    )
+    parser.add_argument("--status", action="store_true", help="Print tool discovery status as JSON")
+    parser.add_argument(
+        "--install-local",
+        choices=sorted(NPM_TOOLS),
+        help="Install one approved npm-backed tool into ~/.cache/re-skills/clean-room-tools/npm",
+    )
+    parser.add_argument(
+        "--version",
+        help="Exact npm package version to install. Required with --install-local.",
+    )
+    parser.add_argument(
+        "--allow-npm-scripts",
+        action="store_true",
+        help="Allow npm lifecycle scripts during local install. Default is --ignore-scripts.",
+    )
+    parser.add_argument(
+        "--allow-working-project-tools",
+        action="store_true",
+        help="Include project-local .local/bin, .bin, node_modules/.bin, and npm prefix/global tools in --status output.",
+    )
+    parser.add_argument(
+        "--probe-tools",
+        action="store_true",
+        help="Execute discovered tools with version commands in --status output. Default is stat-only.",
+    )
+    args = parser.parse_args()
+    if not args.status and not args.install_local:
+        parser.error("choose --status or --install-local")
+    if args.install_local and not args.version:
+        parser.error("--install-local requires --version")
+    return args
+
+
+def write_json(data: dict[str, Any]) -> None:
+    json.dump(data, sys.stdout, indent=2, sort_keys=True)
+    sys.stdout.write("\n")
+
+
+def package_status(allow_project_tools: bool = False) -> dict[str, Any]:
+    status: dict[str, Any] = {}
+    for package in STATUS_PACKAGES:
+        parts = package.split("/")
+        checked = [
+            (root / "node_modules").joinpath(*parts)
+            for root in clean_room_tooling.node_resolver_roots(allow_project_tools)
+        ]
+        found = next((path for path in checked if path.exists()), None)
+        status[package] = (
+            clean_room_tooling.observed(found.as_posix())
+            if found
+            else clean_room_tooling.unknown(
+                "package unavailable",
+                value={"checked_locations": [path.as_posix() for path in checked]},
+            )
+        )
+    return status
+
+
+def status_report(allow_project_tools: bool = False, probe_tools: bool = False) -> dict[str, Any]:
+    dependency_report = clean_room_tooling.dependency_report(allow_project_tools, probe_tools)
+    return {
+        "schema_version": 1,
+        "policy": dependency_report["external_tools_policy"],
+        "tool_probe_mode": dependency_report["tool_probe_mode"],
+        "tool_trust_mode": clean_room_tooling.tool_trust_mode(allow_project_tools),
+        "local_cache": clean_room_tooling.observed(clean_room_tooling.USER_TOOLS_DIR.as_posix()),
+        "installable_local_tools": {
+            name: {"package": item["package"], "source": item["source"]}
+            for name, item in sorted(NPM_TOOLS.items())
+        },
+        "tools": {
+            name: clean_room_tooling.executable_status(
+                name,
+                allow_project_tools=allow_project_tools,
+                probe_tools=probe_tools,
+            )
+            for name in STATUS_TOOLS
+        },
+        "node_packages": package_status(allow_project_tools),
+    }
+
+
+def npm_package_spec(package: str, version: str) -> str:
+    return f"{package}@{version}"
+
+
+def install_npm_tool(tool: str, version: str, allow_npm_scripts: bool = False) -> dict[str, Any]:
+    spec = NPM_TOOLS[tool]
+    npm = clean_room_tooling.find_executable("npm")
+    if npm is None:
+        return clean_room_tooling.error_fact(
+            "npm unavailable; install Node/npm first or set NPM_BIN",
+            evidence={"checked_locations": clean_room_tooling.checked_executable_locations("npm")},
+        )
+
+    prefix = clean_room_tooling.USER_NPM_PREFIX
+    prefix.mkdir(parents=True, exist_ok=True)
+    package_spec = npm_package_spec(str(spec["package"]), version)
+    argv = [
+        npm.path.as_posix(),
+        "install",
+        "--prefix",
+        prefix.as_posix(),
+        "--save-exact",
+    ]
+    if not allow_npm_scripts:
+        argv.append("--ignore-scripts")
+    argv.append(package_spec)
+
+    completed = subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        timeout=LOCAL_INSTALL_TIMEOUT_SECONDS,
+        check=False,
+    )
+    status = "observed" if completed.returncode == 0 else "error"
+    result: dict[str, Any] = {
+        "schema_version": 1,
+        "tool": tool,
+        "source": spec["source"],
+        "version": version,
+        "package_spec": package_spec,
+        "install_root": clean_room_tooling.observed(prefix.as_posix()),
+        "install_trust_mode": clean_room_tooling.observed(
+            "explicit-version",
+            evidence={"npm_lifecycle_scripts": "allowed" if allow_npm_scripts else "ignored"},
+        ),
+        "command": clean_room_tooling.fact(
+            status,
+            {
+                "argv": argv,
+                "returncode": completed.returncode,
+                "stdout": completed.stdout.strip(),
+                "stderr": completed.stderr.strip(),
+            },
+        ),
+    }
+    resolved = clean_room_tooling.find_executable(str(spec["bin"]))
+    result["resolved_tool"] = (
+        clean_room_tooling.observed({"path": resolved.path.as_posix(), "source": resolved.source})
+        if resolved
+        else clean_room_tooling.unknown("tool installed but executable was not resolved")
+    )
+    return result
+
+
+def main() -> int:
+    args = parse_args()
+    if args.status:
+        write_json(status_report(args.allow_working_project_tools, args.probe_tools))
+    if args.install_local:
+        result = install_npm_tool(args.install_local, args.version, args.allow_npm_scripts)
+        write_json(result)
+        if result.get("command", {}).get("status") == "error":
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/skills/clean-room/scripts/clean_room_tooling.py

@@ -0,0 +1,370 @@
+"""Tool discovery helpers for clean-room source-index preflight."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import subprocess
+from typing import Any
+
+
+COMMAND_TIMEOUT_SECONDS = 30
+SKILL_ROOT = Path(__file__).resolve().parents[1]
+PLUGIN_ROOT = Path(__file__).resolve().parents[3]
+SKILL_TOOLS_DIR = SKILL_ROOT / "tools"
+USER_TOOLS_DIR = Path.home() / ".cache" / "re-skills" / "clean-room-tools"
+USER_NPM_PREFIX = USER_TOOLS_DIR / "npm"
+PROJECT_TOOLS_ENV = "RE_SKILLS_TRUST_PROJECT_TOOLS"
+TRUSTED_PATH_PREFIXES = (
+    Path("/bin"),
+    Path("/usr/bin"),
+    Path("/usr/sbin"),
+    Path("/sbin"),
+    Path("/Library/Apple/usr/bin"),
+    Path("/opt/homebrew"),
+    Path("/usr/local"),
+)
+
+TOOL_ENV = {
+    "ast-grep": "AST_GREP_BIN",
+    "ctags": "CTAGS_BIN",
+    "node": "NODE_BIN",
+    "npm": "NPM_BIN",
+    "scip": "SCIP_BIN",
+    "sg": "SG_BIN",
+    "universal-ctags": "UNIVERSAL_CTAGS_BIN",
+}
+
+BREW_HINTS = {
+    "ast-grep": "Offer to run: brew install ast-grep",
+    "ctags": "Offer to run: brew install universal-ctags",
+    "node": "Offer to run: brew install node",
+    "npm": "Offer to run: brew install node",
+    "scip": "Install scip only when source-index export is explicitly needed.",
+    "sg": "Offer to run: brew install ast-grep",
+    "universal-ctags": "Offer to run: brew install universal-ctags",
+}
+
+LOCAL_HINTS = {
+    "ast-grep": "Or run scripts/clean_room_tool_manager.py --install-local ast-grep --version <exact-version>.",
+    "ctags": "Or place ctags under ~/.cache/re-skills/clean-room-tools/bin/ or set CTAGS_BIN.",
+    "node": "Or place node under ~/.cache/re-skills/clean-room-tools/bin/ or set NODE_BIN.",
+    "npm": "Or place npm under ~/.cache/re-skills/clean-room-tools/bin/ or set NPM_BIN.",
+    "scip": "Or place scip under ~/.cache/re-skills/clean-room-tools/bin/ or set SCIP_BIN.",
+    "sg": "Or place sg under ~/.cache/re-skills/clean-room-tools/bin/ or set SG_BIN.",
+    "universal-ctags": "Or place universal-ctags under ~/.cache/re-skills/clean-room-tools/bin/ or set UNIVERSAL_CTAGS_BIN.",
+}
+
+
+@dataclass(frozen=True)
+class ResolvedTool:
+    path: Path
+    source: str
+
+
+def path_is_relative_to(path: Path, root: Path) -> bool:
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def project_tools_allowed(allow_project_tools: bool = False) -> bool:
+    env_value = os.environ.get(PROJECT_TOOLS_ENV, "")
+    return allow_project_tools or env_value.lower() in {"1", "true", "yes", "on"}
+
+
+def trust_mode_name(allow_project_tools: bool = False) -> str:
+    return "project-tools" if project_tools_allowed(allow_project_tools) else "trusted-only"
+
+
+def fact(status: str, value: Any = None, evidence: Any = None, note: str | None = None) -> dict[str, Any]:
+    item: dict[str, Any] = {"status": status, "value": value}
+    if evidence is not None:
+        item["evidence"] = evidence
+    if note:
+        item["note"] = note
+    return item
+
+
+def observed(value: Any, evidence: Any = None, note: str | None = None) -> dict[str, Any]:
+    return fact("observed", value, evidence, note)
+
+
+def unknown(note: str, value: Any = None) -> dict[str, Any]:
+    return fact("unknown", value, note=note)
+
+
+def error_fact(message: str, evidence: Any = None) -> dict[str, Any]:
+    return fact("error", None, evidence=evidence, note=message)
+
+
+def run_command(argv: list[str], timeout: int = COMMAND_TIMEOUT_SECONDS) -> dict[str, Any]:
+    try:
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return error_fact(f"command timed out after {timeout} seconds", evidence=argv)
+    except Exception as exc:
+        return error_fact(str(exc), evidence=argv)
+
+    return fact(
+        "observed" if completed.returncode == 0 else "error",
+        {
+            "argv": argv,
+            "returncode": completed.returncode,
+            "stdout": completed.stdout.strip(),
+            "stderr": completed.stderr.strip(),
+        },
+    )
+
+
+def probe_command(argv: list[str], timeout: int = COMMAND_TIMEOUT_SECONDS) -> str | None:
+    try:
+        completed = subprocess.run(
+            argv,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=False,
+        )
+    except Exception:
+        return None
+    if completed.returncode != 0:
+        return None
+    value = completed.stdout.strip()
+    return value or None
+
+
+def local_executable_candidates(name: str) -> list[tuple[Path, str]]:
+    candidates: list[tuple[Path, str]] = []
+    for root, source in [(USER_TOOLS_DIR, "user-cache"), (SKILL_TOOLS_DIR, "skill-local")]:
+        candidates.extend(
+            [
+                (root / name, source),
+                (root / "bin" / name, source),
+                (root / name / "bin" / name, source),
+                (root / "npm" / "node_modules" / ".bin" / name, source),
+            ]
+        )
+    return candidates
+
+
+def project_executable_candidates(name: str) -> list[tuple[Path, str]]:
+    return [
+        (Path.cwd() / ".local" / "bin" / name, "working-project-local"),
+        (Path.cwd() / ".bin" / name, "working-project-bin"),
+        (Path.cwd() / "node_modules" / ".bin" / name, "working-project-node-modules"),
+        (SKILL_ROOT / "node_modules" / ".bin" / name, "skill-node-modules"),
+        (PLUGIN_ROOT / "node_modules" / ".bin" / name, "plugin-local"),
+    ]
+
+
+def trusted_path_candidates(name: str) -> list[tuple[Path, str]]:
+    candidates: list[tuple[Path, str]] = []
+    for raw_dir in os.environ.get("PATH", "").split(os.pathsep):
+        if not raw_dir:
+            continue
+        directory = Path(raw_dir).expanduser()
+        candidate = directory / name
+        try:
+            normalized_dir = directory.resolve(strict=False)
+        except RuntimeError:
+            normalized_dir = directory.absolute()
+        if any(path_is_relative_to(normalized_dir, prefix) for prefix in TRUSTED_PATH_PREFIXES):
+            candidates.append((candidate, "trusted-path"))
+    return candidates
+
+
+def npm_path(command: list[str], allow_project_tools: bool = False) -> Path | None:
+    npm = find_executable("npm", allow_project_tools)
+    if npm is None:
+        return None
+    value = probe_command([npm.path.as_posix(), *command])
+    if value is None:
+        return None
+    return Path(value).expanduser()
+
+
+def executable_candidates(
+    name: str,
+    allow_project_tools: bool = False,
+    probe_tools: bool = False,
+) -> list[tuple[Path, str]]:
+    candidates: list[tuple[Path, str]] = []
+    env_name = TOOL_ENV.get(name)
+    if env_name:
+        env_value = os.environ.get(env_name)
+        if env_value:
+            candidates.append((Path(env_value), env_name))
+
+    candidates.extend(local_executable_candidates(name))
+
+    if project_tools_allowed(allow_project_tools):
+        candidates.extend(project_executable_candidates(name))
+        if probe_tools:
+            prefix = npm_path(["prefix"], allow_project_tools=False)
+            if prefix is not None:
+                candidates.append((prefix / "node_modules" / ".bin" / name, "npm-prefix"))
+            root = npm_path(["root"], allow_project_tools=False)
+            if root is not None:
+                candidates.append((root / ".bin" / name, "npm-prefix"))
+            global_prefix = npm_path(["prefix", "-g"], allow_project_tools=False)
+            if global_prefix is not None:
+                candidates.append((global_prefix / "bin" / name, "npm-global"))
+
+    candidates.extend(trusted_path_candidates(name))
+    return candidates
+
+
+def find_executable(
+    name: str,
+    allow_project_tools: bool = False,
+    probe_tools: bool = False,
+) -> ResolvedTool | None:
+    seen: set[Path] = set()
+    for candidate, source in executable_candidates(name, allow_project_tools, probe_tools):
+        candidate = candidate.expanduser()
+        try:
+            normalized = candidate.resolve(strict=False)
+        except RuntimeError:
+            normalized = candidate.absolute()
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        if candidate.is_file() and os.access(candidate, os.X_OK):
+            return ResolvedTool(candidate.resolve(), source)
+    return None
+
+
+def checked_executable_locations(
+    name: str,
+    allow_project_tools: bool = False,
+    probe_tools: bool = False,
+) -> list[str]:
+    locations: list[str] = []
+    env_name = TOOL_ENV.get(name)
+    if env_name:
+        env_value = os.environ.get(env_name)
+        locations.append(f"${env_name}" if not env_value else f"${env_name}={env_value}")
+    locations.extend(path.as_posix() for path, _source in local_executable_candidates(name))
+    if project_tools_allowed(allow_project_tools):
+        locations.extend(path.as_posix() for path, _source in project_executable_candidates(name))
+        locations.append("npm prefix/global bins" if probe_tools else "npm prefix/global bins require --probe-tools")
+    locations.append("trusted PATH allowlist")
+    return locations
+
+
+def missing_tool_hint(name: str) -> str:
+    brew = BREW_HINTS.get(name, f"Install {name} with Homebrew if available.")
+    local = LOCAL_HINTS.get(name, f"Or place {name} under {USER_TOOLS_DIR.as_posix()} or set an explicit env var.")
+    return f"{name} unavailable. {brew}. {local}"
+
+
+def executable_status(
+    name: str,
+    version_args: list[str] | None = None,
+    allow_project_tools: bool = False,
+    probe_tools: bool = False,
+) -> dict[str, Any]:
+    resolved = find_executable(name, allow_project_tools, probe_tools)
+    if resolved is None:
+        return unknown(
+            missing_tool_hint(name),
+            value={
+                "checked_locations": checked_executable_locations(name, allow_project_tools, probe_tools),
+                "brew_option": BREW_HINTS.get(name),
+                "local_option": LOCAL_HINTS.get(name),
+                "tool_trust_mode": trust_mode_name(allow_project_tools),
+            },
+        )
+    if not probe_tools:
+        return observed(
+            {
+                "path": resolved.path.as_posix(),
+                "source": resolved.source,
+                "version": unknown("not probed; pass --probe-tools to execute version commands"),
+            }
+        )
+    argv = [resolved.path.as_posix(), *(version_args or ["--version"])]
+    return observed(
+        {
+            "path": resolved.path.as_posix(),
+            "source": resolved.source,
+            "version": run_command(argv),
+        }
+    )
+
+
+def node_resolver_roots(allow_project_tools: bool = False) -> list[Path]:
+    roots = [
+        USER_NPM_PREFIX,
+        USER_TOOLS_DIR,
+        SKILL_TOOLS_DIR,
+    ]
+    if project_tools_allowed(allow_project_tools):
+        roots.extend([Path.cwd(), SKILL_ROOT, PLUGIN_ROOT])
+    return roots
+
+
+def tool_trust_mode(allow_project_tools: bool = False) -> dict[str, Any]:
+    return observed(
+        trust_mode_name(allow_project_tools),
+        evidence={
+            "explicit_allow_project_tools": bool(allow_project_tools),
+            "env": PROJECT_TOOLS_ENV if os.environ.get(PROJECT_TOOLS_ENV) else None,
+        },
+    )
+
+
+def dependency_report(allow_project_tools: bool = False, probe_tools: bool = False) -> dict[str, Any]:
+    npm_prefix = (
+        npm_path(["prefix"], allow_project_tools=False)
+        if probe_tools and project_tools_allowed(allow_project_tools)
+        else None
+    )
+    npm_root = (
+        npm_path(["root"], allow_project_tools=False)
+        if probe_tools and project_tools_allowed(allow_project_tools)
+        else None
+    )
+    return {
+        "external_tools_policy": observed(
+            "Source-index preflight detects optional AST and indexing tools with filesystem checks by default. "
+            "It executes version probes only when --probe-tools is set, and does not consider project-local "
+            f"executables unless --allow-working-project-tools or {PROJECT_TOOLS_ENV}=1 is set."
+        ),
+        "tool_trust_mode": tool_trust_mode(allow_project_tools),
+        "tool_locations": observed(
+            {
+                "user_cache": USER_TOOLS_DIR.as_posix(),
+                "user_npm_prefix": USER_NPM_PREFIX.as_posix(),
+                "skill_local_tools": SKILL_TOOLS_DIR.as_posix(),
+                "trusted_path_prefixes": [path.as_posix() for path in TRUSTED_PATH_PREFIXES],
+                "project_local_candidates": [
+                    ".local/bin",
+                    ".bin",
+                    "node_modules/.bin",
+                ],
+            }
+        ),
+        "tool_probe_mode": observed("execute-version" if probe_tools else "stat-only"),
+        "node": executable_status("node", allow_project_tools=allow_project_tools, probe_tools=probe_tools),
+        "npm": executable_status("npm", allow_project_tools=allow_project_tools, probe_tools=probe_tools),
+        "ast_grep": executable_status("ast-grep", allow_project_tools=allow_project_tools, probe_tools=probe_tools),
+        "sg": executable_status("sg", allow_project_tools=allow_project_tools, probe_tools=probe_tools),
+        "ctags": executable_status("ctags", allow_project_tools=allow_project_tools, probe_tools=probe_tools),
+        "universal_ctags": executable_status(
+            "universal-ctags", allow_project_tools=allow_project_tools, probe_tools=probe_tools
+        ),
+        "scip": executable_status("scip", allow_project_tools=allow_project_tools, probe_tools=probe_tools),
+        "npm_prefix": observed(npm_prefix.as_posix()) if npm_prefix else unknown("npm prefix not probed"),
+        "npm_root": observed(npm_root.as_posix()) if npm_root else unknown("npm root not probed"),
+    }

package/skills/unattended/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: unattended
+description: Starts the Clean Room startup wizard in bounded unattended controller mode for authorized spec-only source-to-spec work with finite loop limits and safety stops.
+argument-hint: [authorized source scope, separated output roots, optional max iterations]
+disable-model-invocation: true
+---
+
+# Clean Room Unattended
+
+Start the clean-room startup wizard with `controller_policy.mode` fixed to `unattended`.
+
+Use the canonical `clean-room` skill workflow and references in this plugin. Preserve the same spec-only boundary, role separation, artifact schemas, leakage rules, and hook expectations.
+
+Gather only required setup facts:
+
+- Authorization statement, requester, allowed actions, prohibited actions, and evidence handling.
+- Source roots, contaminated artifact root, clean root, and optional public or destination reference roots.
+- Target language or destination constraints, if known.
+- Target schema profile: `openspec-delta`, `gsd-planning-package`, `speckit-feature-folder`, or `kiro-spec-folder`.
+- Finite maximum iteration count. Use `10` when the user does not provide a value.
+
+Before indexing or artifact generation, confirm that source roots, contaminated artifact roots, and clean roots are separate paths. Stop if authorization is unclear, if the requested output includes replacement implementation code, or if clean and contaminated roots overlap.
+
+Record `controller_policy.mode` as `unattended`, `max_units_per_iteration` as `1`, and `max_iterations` as the selected finite value. Include these stop conditions: `authorization-missing`, `scope-change`, `contamination-suspected`, `schema-validation-failed`, `leakage-scan-failed`, `unit-blocked`, `coverage-complete`, and `iteration-limit-reached`.
+
+For multi-file source scope, guide agent zero/controller to run `skills/clean-room/scripts/build_source_index.py` as preflight outside clean-room role sessions. Store `source-index.json` only under the contaminated artifact root and never include it in clean handoff packages.