clean-room-skill 0.1.0

package/hooks/validate-json-schema.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""Lightweight JSON artifact validator for bundled clean-room schemas."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from clean_room_paths import checked_write_paths, load_payload, path_under_env
+
+
+SCHEMA_BY_ARTIFACT = {
+    "task-manifest": "task-manifest.schema.json",
+    "behavior-spec": "behavior-spec.schema.json",
+    "skeleton-manifest": "skeleton-manifest.schema.json",
+    "qc-report": "qc-report.schema.json",
+    "coverage-ledger": "coverage-ledger.schema.json",
+    "evidence-ledger": "evidence-ledger.schema.json",
+    "source-index": "source-index.schema.json",
+    "handoff-package": "handoff-package.schema.json",
+    "contamination-incident": "contamination-incident.schema.json",
+}
+CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST_ENV = "CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST"
+
+
+def schema_dir() -> Path:
+    configured = os.environ.get("CLEAN_ROOM_SCHEMA_DIR")
+    if configured:
+        return Path(configured).expanduser().resolve()
+    return Path(__file__).resolve().parents[1] / "skills" / "clean-room" / "assets"
+
+
+def artifact_kind(path: Path, data: dict) -> str | None:
+    name = path.name.removesuffix(".json")
+    if name in SCHEMA_BY_ARTIFACT:
+        return name
+    if "spec_id" in data:
+        return "behavior-spec"
+    if "manifest_id" in data:
+        return "skeleton-manifest"
+    if "report_id" in data:
+        return "qc-report"
+    if "package_id" in data:
+        return "handoff-package"
+    if "incident_id" in data:
+        return "contamination-incident"
+    if "index_id" in data and data.get("domain") == "contaminated" and "recommended_batches" in data:
+        return "source-index"
+    if "ledger_id" in data:
+        if data.get("domain") == "contaminated" and "entries" in data:
+            return "evidence-ledger"
+        if {"source_units", "behavior_spec_refs", "coverage_status"} & data.keys():
+            return "coverage-ledger"
+    if data.get("from_domain") == "contaminated" and data.get("to_domain") == "clean" and "artifacts" in data:
+        return "handoff-package"
+    for kind in SCHEMA_BY_ARTIFACT:
+        if kind in name:
+            return kind
+    if "task_id" in data:
+        return "task-manifest"
+    return None
+
+
+def auxiliary_json_allowed(path: Path) -> tuple[bool, list[str]]:
+    errors: list[str] = []
+    for item in os.environ.get(CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST_ENV, "").split(os.pathsep):
+        if not item:
+            continue
+        try:
+            allowed = Path(item).expanduser().resolve()
+        except OSError as exc:
+            errors.append(f"{CLEAN_ROOM_AUXILIARY_JSON_ALLOWLIST_ENV} has invalid path {item!r}: {exc}")
+            continue
+        if path == allowed:
+            return True, errors
+    return False, errors
+
+
+def resolve_ref(root_schema: dict, ref: str) -> dict:
+    if not ref.startswith("#/"):
+        raise ValueError(f"unsupported external schema ref {ref}")
+    current: Any = root_schema
+    for part in ref[2:].split("/"):
+        key = part.replace("~1", "/").replace("~0", "~")
+        if not isinstance(current, dict) or key not in current:
+            raise ValueError(f"unresolvable schema ref {ref}")
+        current = current[key]
+    if not isinstance(current, dict):
+        raise ValueError(f"schema ref {ref} did not resolve to an object")
+    return current
+
+
+def path_label(path: tuple[str | int, ...]) -> str:
+    if not path:
+        return "<root>"
+    return "/" + "/".join(str(part) for part in path)
+
+
+def type_matches(value: Any, expected: str) -> bool:
+    if expected == "object":
+        return isinstance(value, dict)
+    if expected == "array":
+        return isinstance(value, list)
+    if expected == "string":
+        return isinstance(value, str)
+    if expected == "boolean":
+        return isinstance(value, bool)
+    if expected == "null":
+        return value is None
+    if expected == "integer":
+        return isinstance(value, int) and not isinstance(value, bool)
+    if expected == "number":
+        return isinstance(value, (int, float)) and not isinstance(value, bool)
+    return True
+
+
+def valid_date_time(value: str) -> bool:
+    candidate = value[:-1] + "+00:00" if value.endswith("Z") else value
+    try:
+        datetime.fromisoformat(candidate)
+    except ValueError:
+        return False
+    return True
+
+
+def validate_value(value: Any, schema: dict, root_schema: dict, path: tuple[str | int, ...] = ()) -> list[str]:
+    errors: list[str] = []
+    if "$ref" in schema:
+        try:
+            errors.extend(validate_value(value, resolve_ref(root_schema, schema["$ref"]), root_schema, path))
+        except ValueError as exc:
+            errors.append(f"{path_label(path)}: {exc}")
+            return errors
+        schema = {key: item for key, item in schema.items() if key != "$ref"}
+        if not schema:
+            return errors
+
+    all_of = schema.get("allOf")
+    if isinstance(all_of, list):
+        for index, subschema in enumerate(all_of):
+            if isinstance(subschema, dict):
+                errors.extend(validate_value(value, subschema, root_schema, path))
+            else:
+                errors.append(f"{path_label(path)}: allOf[{index}] is not a schema object")
+
+    if_schema = schema.get("if")
+    if isinstance(if_schema, dict) and not validate_value(value, if_schema, root_schema, path):
+        then_schema = schema.get("then")
+        if isinstance(then_schema, dict):
+            errors.extend(validate_value(value, then_schema, root_schema, path))
+
+    if "const" in schema and value != schema["const"]:
+        errors.append(f"{path_label(path)}: expected const {schema['const']!r}")
+    if "enum" in schema and value not in schema["enum"]:
+        errors.append(f"{path_label(path)}: expected one of {schema['enum']!r}")
+
+    expected_type = schema.get("type")
+    if isinstance(expected_type, str) and not type_matches(value, expected_type):
+        errors.append(f"{path_label(path)}: expected {expected_type}")
+        return errors
+    if isinstance(expected_type, list) and not any(type_matches(value, item) for item in expected_type):
+        errors.append(f"{path_label(path)}: expected one of types {expected_type!r}")
+        return errors
+
+    if isinstance(value, dict):
+        required = schema.get("required", [])
+        if isinstance(required, list):
+            for field in required:
+                if isinstance(field, str) and field not in value:
+                    errors.append(f"{path_label(path)}: missing required field {field!r}")
+
+        properties = schema.get("properties", {})
+        if isinstance(properties, dict):
+            for field, field_schema in properties.items():
+                if field in value and isinstance(field_schema, dict):
+                    errors.extend(validate_value(value[field], field_schema, root_schema, path + (field,)))
+            if schema.get("additionalProperties") is False:
+                for field in sorted(set(value) - set(properties)):
+                    errors.append(f"{path_label(path + (field,))}: additional property is not allowed")
+
+    if isinstance(value, list):
+        min_items = schema.get("minItems")
+        if isinstance(min_items, int) and len(value) < min_items:
+            errors.append(f"{path_label(path)}: fewer than minItems {min_items}")
+        max_items = schema.get("maxItems")
+        if isinstance(max_items, int) and len(value) > max_items:
+            errors.append(f"{path_label(path)}: more than maxItems {max_items}")
+        if schema.get("uniqueItems") is True:
+            seen: set[str] = set()
+            for item in value:
+                marker = json.dumps(item, sort_keys=True, separators=(",", ":"))
+                if marker in seen:
+                    errors.append(f"{path_label(path)}: duplicate item violates uniqueItems")
+                    break
+                seen.add(marker)
+        item_schema = schema.get("items")
+        if isinstance(item_schema, dict):
+            for index, item in enumerate(value):
+                errors.extend(validate_value(item, item_schema, root_schema, path + (index,)))
+
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        minimum = schema.get("minimum")
+        if isinstance(minimum, (int, float)) and value < minimum:
+            errors.append(f"{path_label(path)}: less than minimum {minimum}")
+        maximum = schema.get("maximum")
+        if isinstance(maximum, (int, float)) and value > maximum:
+            errors.append(f"{path_label(path)}: greater than maximum {maximum}")
+
+    if isinstance(value, str):
+        min_length = schema.get("minLength")
+        if isinstance(min_length, int) and len(value) < min_length:
+            errors.append(f"{path_label(path)}: shorter than minLength {min_length}")
+        pattern = schema.get("pattern")
+        if isinstance(pattern, str) and re.search(pattern, value) is None:
+            errors.append(f"{path_label(path)}: does not match pattern {pattern!r}")
+        if schema.get("format") == "date-time" and not valid_date_time(value):
+            errors.append(f"{path_label(path)}: invalid date-time")
+
+    return errors
+
+
+def main() -> int:
+    payload, payload_error = load_payload()
+    if payload_error:
+        print(f"clean-room schema check failed: {payload_error}", file=sys.stderr)
+        return 1
+    paths, path_errors = checked_write_paths(payload, "clean-room schema check")
+    if path_errors:
+        for error in path_errors:
+            print(f"clean-room schema check failed: {error}", file=sys.stderr)
+        return 1
+    for path in paths:
+        if path.suffix.lower() != ".json" or not path.is_file():
+            continue
+        in_clean_root = path_under_env(path, "CLEAN_ROOM_CLEAN_ROOTS")
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as exc:
+            print(f"clean-room JSON parse failed for {path}: {exc}", file=sys.stderr)
+            return 1
+        if not isinstance(data, dict):
+            if in_clean_root:
+                print(f"clean-room schema check failed for {path}: clean JSON artifact must be an object", file=sys.stderr)
+                return 1
+            continue
+        kind = artifact_kind(path, data)
+        if not kind:
+            allowed, allowlist_errors = auxiliary_json_allowed(path)
+            if allowlist_errors:
+                for error in allowlist_errors:
+                    print(f"clean-room schema check failed: {error}", file=sys.stderr)
+                return 1
+            if in_clean_root and not allowed:
+                print(f"clean-room schema check failed for {path}: unrecognized clean JSON artifact", file=sys.stderr)
+                return 1
+            continue
+        if in_clean_root and kind == "source-index":
+            print(f"clean-room schema check failed for {path}: source-index.json is contaminated-only", file=sys.stderr)
+            return 1
+        schema_path = schema_dir() / SCHEMA_BY_ARTIFACT[kind]
+        try:
+            schema = json.loads(schema_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            print(f"clean-room schema load failed for {schema_path}: {exc}", file=sys.stderr)
+            return 1
+        errors = validate_value(data, schema, schema)
+        if errors:
+            print(f"clean-room schema check failed for {path}:", file=sys.stderr)
+            for error in errors[:20]:
+                print(f"  {error}", file=sys.stderr)
+            if len(errors) > 20:
+                print(f"  ... {len(errors) - 20} more error(s)", file=sys.stderr)
+            return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/lib/fs-utils.cjs

@@ -0,0 +1,123 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+function sha256Bytes(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function fileHash(filePath) {
+  return sha256Bytes(fs.readFileSync(filePath));
+}
+
+function normalizeRelativePath(relPath) {
+  if (typeof relPath !== 'string' || relPath.trim() === '' || relPath.includes('\0')) {
+    return null;
+  }
+  if (path.isAbsolute(relPath) || path.win32.isAbsolute(relPath)) {
+    return null;
+  }
+  const normalized = relPath.replace(/\\/g, '/');
+  const parts = normalized.split('/');
+  if (parts.some((part) => part === '' || part === '.' || part === '..')) {
+    return null;
+  }
+  return parts.join('/');
+}
+
+function resolveInside(root, relPath) {
+  const normalized = normalizeRelativePath(relPath);
+  if (!normalized) {
+    throw new Error(`invalid relative path: ${relPath}`);
+  }
+  const rootPath = path.resolve(root);
+  const fullPath = path.resolve(rootPath, normalized);
+  if (fullPath !== rootPath && !fullPath.startsWith(rootPath + path.sep)) {
+    throw new Error(`path escapes install root: ${relPath}`);
+  }
+  return fullPath;
+}
+
+function atomicWriteFile(filePath, data, options = {}) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const suffix = `${process.pid}-${Date.now()}-${crypto.randomUUID()}`;
+  const tmpPath = `${filePath}.tmp-${suffix}`;
+  try {
+    fs.writeFileSync(tmpPath, data, options);
+    fs.renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      fs.rmSync(tmpPath, { force: true });
+    } catch {
+      // Best effort cleanup only.
+    }
+    throw err;
+  }
+}
+
+function readJsonFile(filePath, fallback) {
+  if (!fs.existsSync(filePath)) {
+    return fallback;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`${filePath} is not valid JSON: ${err.message}`);
+  }
+}
+
+function writeJsonFile(filePath, value) {
+  atomicWriteFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function listFiles(root, options = {}) {
+  if (!fs.existsSync(root)) {
+    return [];
+  }
+  const ignoreNames = new Set(options.ignoreNames || []);
+  const files = [];
+  function walk(dir, relBase) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (ignoreNames.has(entry.name)) {
+        continue;
+      }
+      const fullPath = path.join(dir, entry.name);
+      const relPath = relBase ? `${relBase}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(fullPath, relPath);
+      } else if (entry.isFile()) {
+        files.push(relPath);
+      }
+    }
+  }
+  walk(root, '');
+  return files.sort();
+}
+
+function removeEmptyParents(startDir, stopDir) {
+  let current = path.resolve(startDir);
+  const stop = path.resolve(stopDir);
+  while (current !== stop && current.startsWith(stop + path.sep)) {
+    try {
+      fs.rmdirSync(current);
+    } catch {
+      break;
+    }
+    current = path.dirname(current);
+  }
+}
+
+module.exports = {
+  atomicWriteFile,
+  fileHash,
+  listFiles,
+  normalizeRelativePath,
+  readJsonFile,
+  removeEmptyParents,
+  resolveInside,
+  sha256Bytes,
+  writeJsonFile,
+};

package/lib/hooks.cjs

@@ -0,0 +1,214 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { readJsonFile, writeJsonFile } = require('./fs-utils.cjs');
+
+const HOOK_EVENTS = new Set(['PreToolUse', 'PostToolUse', 'UserPromptSubmit', 'SessionStart']);
+
+const CLEAN_ROOM_HOOKS = [
+  {
+    event: 'PreToolUse',
+    matcher: 'Bash|Shell',
+    checks: ['require-clean-room-env.py', 'deny-clean-room-shell.py'],
+  },
+  {
+    event: 'PreToolUse',
+    matcher: 'Read|Glob|Grep',
+    checks: ['require-clean-room-env.py', 'deny-clean-source-read.py'],
+  },
+  {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit|MultiEdit',
+    checks: ['require-clean-room-env.py', 'deny-contaminated-clean-write.py'],
+  },
+  {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit|MultiEdit',
+    checks: ['require-clean-room-env.py', 'check-artifact-leakage.py', 'validate-json-schema.py'],
+  },
+];
+
+function shellQuote(value) {
+  const text = String(value);
+  if (text === '') {
+    return "''";
+  }
+  return `'${text.replace(/'/g, "'\"'\"'")}'`;
+}
+
+function buildHookCommand({ pythonPath, wrapperPath, mode, checks }) {
+  const parts = [
+    shellQuote(pythonPath),
+    shellQuote(wrapperPath),
+    '--mode',
+    mode,
+  ];
+  for (const check of checks) {
+    parts.push('--check', check);
+  }
+  return parts.join(' ');
+}
+
+function buildHookEntries({ pythonPath, wrapperPath, mode }) {
+  return CLEAN_ROOM_HOOKS.map((entry) => ({
+    event: entry.event,
+    matcher: entry.matcher,
+    hook: {
+      type: 'command',
+      command: buildHookCommand({
+        pythonPath,
+        wrapperPath,
+        mode,
+        checks: entry.checks,
+      }),
+      timeout: 10,
+      statusMessage: 'Checking clean-room guardrails',
+    },
+  }));
+}
+
+function isManagedHook(hook) {
+  return !!(
+    hook &&
+    typeof hook === 'object' &&
+    typeof hook.command === 'string' &&
+    hook.command.includes('clean-room-hook.py')
+  );
+}
+
+function hasTopLevelHookEvents(value) {
+  return Object.keys(value || {}).some((key) => HOOK_EVENTS.has(key));
+}
+
+function hookTableFor(value) {
+  if (value && typeof value.hooks === 'object' && value.hooks !== null && !Array.isArray(value.hooks)) {
+    return value.hooks;
+  }
+  if (hasTopLevelHookEvents(value)) {
+    return value;
+  }
+  if (!value.hooks || typeof value.hooks !== 'object' || Array.isArray(value.hooks)) {
+    value.hooks = {};
+  }
+  return value.hooks;
+}
+
+function removeManagedHookEntriesFromTable(table) {
+  let changed = false;
+  for (const event of Object.keys(table)) {
+    if (!Array.isArray(table[event])) {
+      continue;
+    }
+    const nextEntries = [];
+    for (const entry of table[event]) {
+      if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) {
+        nextEntries.push(entry);
+        continue;
+      }
+      const hooks = entry.hooks.filter((hook) => !isManagedHook(hook));
+      if (hooks.length !== entry.hooks.length) {
+        changed = true;
+      }
+      if (hooks.length > 0) {
+        nextEntries.push({ ...entry, hooks });
+      } else {
+        changed = true;
+      }
+    }
+    if (nextEntries.length > 0) {
+      table[event] = nextEntries;
+    } else {
+      delete table[event];
+    }
+    if (nextEntries.length !== table[event]?.length) {
+      changed = true;
+    }
+  }
+  return changed;
+}
+
+function mergeHookEntries(configPath, entries, options = {}) {
+  const original = readJsonFile(configPath, {});
+  if (!original || typeof original !== 'object' || Array.isArray(original)) {
+    throw new Error(`${configPath} must contain a JSON object`);
+  }
+  const next = structuredClone(original);
+  const table = hookTableFor(next);
+  removeManagedHookEntriesFromTable(table);
+  for (const entry of entries) {
+    if (!Array.isArray(table[entry.event])) {
+      table[entry.event] = [];
+    }
+    table[entry.event].push({
+      matcher: entry.matcher,
+      hooks: [entry.hook],
+    });
+  }
+  if (!options.dryRun) {
+    writeJsonFile(configPath, next);
+  }
+  return next;
+}
+
+function removeHookEntries(configPath, options = {}) {
+  if (!fs.existsSync(configPath)) {
+    return null;
+  }
+  const original = readJsonFile(configPath, {});
+  if (!original || typeof original !== 'object' || Array.isArray(original)) {
+    throw new Error(`${configPath} must contain a JSON object`);
+  }
+  const next = structuredClone(original);
+  const table = hookTableFor(next);
+  const changed = removeManagedHookEntriesFromTable(table);
+  if (changed && !options.dryRun) {
+    writeJsonFile(configPath, next);
+  }
+  return changed ? next : original;
+}
+
+function renderPackageHooksJson(mode) {
+  const hooks = {};
+  for (const entry of CLEAN_ROOM_HOOKS) {
+    if (!Array.isArray(hooks[entry.event])) {
+      hooks[entry.event] = [];
+    }
+    hooks[entry.event].push({
+      matcher: entry.matcher,
+      hooks: [
+        {
+          type: 'command',
+          command: [
+            'python3',
+            'hooks/clean-room-hook.py',
+            '--mode',
+            mode,
+            ...entry.checks.flatMap((check) => ['--check', check]),
+          ].join(' '),
+        },
+      ],
+    });
+  }
+  return `${JSON.stringify({ hooks }, null, 2)}\n`;
+}
+
+function configPathForRuntime(runtime, targetRoot) {
+  if (runtime === 'codex') {
+    return path.join(targetRoot, 'hooks.json');
+  }
+  if (runtime === 'claude') {
+    return path.join(targetRoot, 'settings.json');
+  }
+  return null;
+}
+
+module.exports = {
+  buildHookEntries,
+  configPathForRuntime,
+  renderPackageHooksJson,
+  removeHookEntries,
+  mergeHookEntries,
+  shellQuote,
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "clean-room-skill",
+  "version": "0.1.0",
+  "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
+  "bin": {
+    "clean-room-skill": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "skills",
+    "agents",
+    "hooks",
+    "examples",
+    "plugin.json",
+    ".codex-plugin",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!**/*.pyo",
+    "!**/.DS_Store"
+  ],
+  "keywords": [
+    "clean-room",
+    "specification",
+    "reverse-engineering",
+    "compliance",
+    "codex",
+    "claude"
+  ],
+  "author": {
+    "name": "whit3rabbit"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/whit3rabbit/clean-room-skill",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/whit3rabbit/clean-room-skill.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test",
+    "test:install": "node --test tests/install.test.js"
+  }
+}

package/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "clean-room",
+  "version": "0.1.0",
+  "description": "Spec-first clean-room workflow for authorized source analysis without replacement code.",
+  "author": {
+    "name": "whit3rabbit"
+  },
+  "homepage": "https://github.com/whit3rabbit/clean-room-skill",
+  "repository": "https://github.com/whit3rabbit/clean-room-skill",
+  "license": "MIT",
+  "keywords": [
+    "clean-room",
+    "specification",
+    "reverse-engineering",
+    "compliance"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "hooks": "./hooks/hooks.json"
+}