@kaiohenricunha/harness 0.2.0

package/plugins/harness/scripts/validate-settings.sh

@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# validate-settings.sh — enforce the contract in
+# docs/specs/claude-hardening/spec/7-non-functional-requirements.md.
+#
+# Usage:
+#   validate-settings.sh                      # validates ~/.claude/settings.json
+#   validate-settings.sh <path-to-settings>   # validates an alternative file
+#   validate-settings.sh --json [<path>]      # emit JSON events on stdout
+#
+# Exit codes:
+#   0 — all hard checks pass
+#   1 — at least one hard check failed
+#
+# Hard checks:
+#   SEC-1  no secret literals in *_KEY/*_TOKEN/*_SECRET fields (unless ${VAR})
+#   SEC-2  skipDangerousModePermissionPrompt must not be present
+#   SEC-3  no @latest in mcpServers[*].args
+#   SEC-4  .credentials.json mode == 600
+#   OPS-1  JSON well-formed
+#          every mcpServers[*].command resolves on PATH or as existing absolute path
+#          every hooks[*].command + statusLine.command path exists
+#          every enabledPlugins key exists in installed_plugins.json
+#
+# Soft checks (warn, exit 0):
+#   OPS-2  ~/.claude/projects/ ≤ 1.5 GB, ~/.claude/file-history/ ≤ 100 MB
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=plugins/harness/scripts/lib/output.sh
+source "$SCRIPT_DIR/lib/output.sh"
+
+# Argv: --json flag is order-independent but must precede the positional path.
+HARNESS_JSON=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --json)  HARNESS_JSON=1; shift ;;
+    --help|-h)
+      grep -E '^# ' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+      exit 0
+      ;;
+    *) break ;;
+  esac
+done
+export HARNESS_JSON
+
+SETTINGS="${1:-$HOME/.claude/settings.json}"
+PLUGINS_REG="$HOME/.claude/plugins/installed_plugins.json"
+CREDS="$HOME/.claude/.credentials.json"
+PROJECTS_DIR="$HOME/.claude/projects"
+FILE_HISTORY_DIR="$HOME/.claude/file-history"
+
+out_init
+
+if [ "$HARNESS_JSON" != "1" ]; then
+  echo "Validating $SETTINGS"
+  echo
+fi
+
+# --- JSON validity (blocking) ---
+CATEGORY=OPS-1
+if jq -e . < "$SETTINGS" > /dev/null 2>&1; then
+  pass "JSON well-formed"
+else
+  fail "JSON malformed"
+  out_summary
+  exit 1
+fi
+
+# --- SEC-2: no skipDangerousModePermissionPrompt ---
+CATEGORY=SEC-2
+if jq -e 'has("skipDangerousModePermissionPrompt")' < "$SETTINGS" > /dev/null 2>&1; then
+  fail "SEC-2 skipDangerousModePermissionPrompt is set"
+else
+  pass "SEC-2 skipDangerousModePermissionPrompt absent"
+fi
+
+# --- SEC-1: no secret literals ---
+CATEGORY=SEC-1
+SECRET_LEAKS=$(jq -r '
+  . as $root
+  | [paths(scalars)] as $ps
+  | $ps[]
+  | select((last | tostring) | test("(_KEY|_TOKEN|_SECRET)$"; "i"))
+  | . as $p
+  | ($root | getpath($p)) as $v
+  | select(($v | type) == "string")
+  | select($v | test("^[A-Za-z0-9_-]{20,}$"))
+  | ($p | map(tostring) | join("."))
+' < "$SETTINGS" || true)
+
+if [ -z "$SECRET_LEAKS" ]; then
+  pass "SEC-1 no secret literals in *_KEY/*_TOKEN/*_SECRET fields"
+else
+  while IFS= read -r p; do fail "SEC-1 secret literal at: $p"; done <<< "$SECRET_LEAKS"
+fi
+
+# --- SEC-3: no @latest in MCP args ---
+CATEGORY=SEC-3
+LATEST_REFS=$(jq -r '
+  .mcpServers // {} | to_entries[]
+  | . as $s
+  | ($s.value.args // [])[]
+  | select(. | test("@latest$"))
+  | $s.key + " -> " + .
+' < "$SETTINGS" || true)
+
+if [ -z "$LATEST_REFS" ]; then
+  pass "SEC-3 no @latest in MCP args"
+else
+  while IFS= read -r l; do fail "SEC-3 @latest pinned in: $l"; done <<< "$LATEST_REFS"
+fi
+
+# --- MCP command resolvable ---
+CATEGORY=OPS-1
+while IFS= read -r cmd; do
+  [ -z "$cmd" ] && continue
+  if [[ "$cmd" == /* ]]; then
+    if [ -x "$cmd" ]; then
+      pass "MCP command executable: $cmd"
+    else
+      fail "MCP command missing or not executable: $cmd"
+    fi
+  else
+    if command -v "$cmd" > /dev/null 2>&1; then
+      pass "MCP command on PATH: $cmd"
+    else
+      fail "MCP command not on PATH: $cmd"
+    fi
+  fi
+done < <(jq -r '.mcpServers // {} | to_entries[] | .value.command' < "$SETTINGS")
+
+# --- hooks + statusLine target paths ---
+CATEGORY=OPS-1
+while IFS= read -r cmd; do
+  [ -z "$cmd" ] && continue
+  script=$(echo "$cmd" | awk '{for(i=1;i<=NF;i++) if($i ~ /^\//) {print $i; exit}}')
+  [ -z "$script" ] && script="$cmd"
+  if [ -f "$script" ]; then
+    pass "hook/statusLine target exists: $script"
+  else
+    fail "hook/statusLine target missing: $script"
+  fi
+done < <(jq -r '
+  [
+    (.hooks // {} | to_entries[] | .value[] | .hooks[] | .command),
+    (.statusLine.command // empty)
+  ][] // empty
+' < "$SETTINGS")
+
+# --- enabledPlugins installed? ---
+CATEGORY=OPS-1
+if [ -f "$PLUGINS_REG" ]; then
+  while IFS= read -r plugin; do
+    [ -z "$plugin" ] && continue
+    if jq -e --arg p "$plugin" '.plugins | has($p)' < "$PLUGINS_REG" > /dev/null 2>&1; then
+      pass "enabled plugin installed: $plugin"
+    else
+      fail "enabled plugin NOT installed: $plugin"
+    fi
+  done < <(jq -r '.enabledPlugins // {} | to_entries[] | select(.value == true) | .key' < "$SETTINGS")
+else
+  warn "plugin registry not found at $PLUGINS_REG"
+fi
+
+# --- SEC-4: .credentials.json mode 600 ---
+CATEGORY=SEC-4
+if [ -f "$CREDS" ]; then
+  MODE=$(stat -c '%a' "$CREDS" 2>/dev/null || echo "?")
+  if [ "$MODE" = "600" ]; then
+    pass "SEC-4 .credentials.json mode 600"
+  else
+    fail "SEC-4 .credentials.json mode is $MODE (expected 600)"
+  fi
+else
+  warn ".credentials.json not found (may not be logged in)"
+fi
+
+# --- OPS-2 disk budgets (soft) ---
+CATEGORY=OPS-2
+if [ -d "$PROJECTS_DIR" ]; then
+  PROJECTS_MB=$(du -sm "$PROJECTS_DIR" 2>/dev/null | awk '{print $1}')
+  if [ "$PROJECTS_MB" -gt 1536 ]; then
+    # shellcheck disable=SC2088  # literal ~ is user-readable text, not a filesystem path
+    warn "~/.claude/projects/ is ${PROJECTS_MB} MB (budget: 1536 MB). Prune: find ~/.claude/projects -mindepth 2 -maxdepth 2 -type f -mtime +60 -delete"
+  else
+    pass "projects/ size OK (${PROJECTS_MB} MB / 1536)"
+  fi
+fi
+
+if [ -d "$FILE_HISTORY_DIR" ]; then
+  FH_MB=$(du -sm "$FILE_HISTORY_DIR" 2>/dev/null | awk '{print $1}')
+  if [ "$FH_MB" -gt 100 ]; then
+    # shellcheck disable=SC2088  # literal ~ is user-readable text, not a filesystem path
+    warn "~/.claude/file-history/ is ${FH_MB} MB (budget: 100 MB)"
+  else
+    pass "file-history/ size OK (${FH_MB} MB / 100)"
+  fi
+fi
+
+out_summary
+[ "$FAIL" -eq 0 ] && exit 0 || exit 1

package/plugins/harness/src/check-instruction-drift.mjs

@@ -0,0 +1,127 @@
+import path from "path";
+import {
+  loadFacts,
+  pathExists,
+  readText,
+} from "./spec-harness-lib.mjs";
+import { ValidationError, ERROR_CODES } from "./lib/errors.mjs";
+
+/**
+ * Cross-reference docs/repo-facts.json against instruction files (CLAUDE.md, README.md, etc.).
+ *
+ * Checks performed:
+ *  - instruction_files is a non-empty array in repo-facts.json
+ *  - each instruction file listed in repo-facts.json exists on disk
+ *  - each instruction file mentions the team_count value (stale-number detection)
+ *  - each entry in protected_paths appears literally in CLAUDE.md (so docs don't drift from facts)
+ *  - protected_paths entries are non-empty strings
+ *
+ * The port omits the loadSourceFacts() cross-check from squadranks (which reads src/data.js
+ * and src/i18n.js — project-specific to wc-squad-rankings). The harness treats repo-facts.json
+ * itself as the authoritative source and checks that instruction files stay in sync with it.
+ *
+ * @param {object} ctx  Harness context from createHarnessContext().
+ * @returns {{ ok: boolean, errors: ValidationError[] }}
+ */
+export function checkInstructionDrift(ctx) {
+  const errors = [];
+  const facts = loadFacts(ctx);
+
+  // instruction_files must be a non-empty array.
+  if (!Array.isArray(facts.instruction_files) || facts.instruction_files.length === 0) {
+    errors.push(new ValidationError({
+      code: ERROR_CODES.DRIFT_INSTRUCTION_FILES,
+      category: "drift",
+      file: "docs/repo-facts.json",
+      pointer: "instruction_files",
+      message: "instruction_files must be a non-empty array of file paths",
+    }));
+    // Can't proceed without knowing which files to check.
+    return { ok: false, errors };
+  }
+
+  // protected_paths entries must be non-empty strings.
+  for (const protectedPath of facts.protected_paths ?? []) {
+    if (typeof protectedPath !== "string" || !protectedPath.trim()) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.DRIFT_PROTECTED_PATH,
+        category: "drift",
+        file: "docs/repo-facts.json",
+        pointer: "protected_paths[]",
+        got: JSON.stringify(protectedPath),
+        message: `protected_paths entries must be non-empty strings (got ${JSON.stringify(protectedPath)})`,
+      }));
+    }
+  }
+
+  const teamCount = facts.team_count;
+
+  // Check each instruction file.
+  for (const instructionFile of facts.instruction_files) {
+    if (typeof instructionFile !== "string" || !instructionFile.trim()) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.DRIFT_INSTRUCTION_FILES,
+        category: "drift",
+        file: "docs/repo-facts.json",
+        pointer: "instruction_files[]",
+        message: "instruction_files entries must be non-empty strings",
+      }));
+      continue;
+    }
+
+    if (!pathExists(ctx, instructionFile)) {
+      errors.push(new ValidationError({
+        code: ERROR_CODES.DRIFT_INSTRUCTION_FILE_MISSING,
+        category: "drift",
+        file: "docs/repo-facts.json",
+        pointer: "instruction_files[]",
+        got: instructionFile,
+        message: `instruction file does not exist -> ${instructionFile}`,
+        hint: "create the file on disk or remove it from repo-facts.json",
+      }));
+      continue;
+    }
+
+    const text = readText(ctx, instructionFile);
+
+    // team_count drift: if any "N team(s)" phrase exists in the file with N != team_count, flag it.
+    if (typeof teamCount === "number") {
+      const teamPhrasePattern = /(\d+)\s+teams?/gi;
+      for (const match of text.matchAll(teamPhrasePattern)) {
+        const mentioned = parseInt(match[1], 10);
+        if (mentioned !== teamCount) {
+          errors.push(new ValidationError({
+            code: ERROR_CODES.DRIFT_TEAM_COUNT,
+            category: "drift",
+            file: instructionFile,
+            expected: String(teamCount),
+            got: match[0],
+            message: `stale team_count claim — file mentions "${match[0]}" but docs/repo-facts.json has team_count=${teamCount}`,
+          }));
+        }
+      }
+    }
+  }
+
+  // protected_paths drift: every protected path in repo-facts must appear literally in CLAUDE.md.
+  // This ensures the canonical instruction doc stays in sync when facts change.
+  const claudeMdPath = "CLAUDE.md";
+  if (pathExists(ctx, claudeMdPath) && Array.isArray(facts.protected_paths)) {
+    const claudeText = readText(ctx, claudeMdPath);
+    for (const protectedPath of facts.protected_paths) {
+      if (typeof protectedPath !== "string" || !protectedPath.trim()) continue;
+      if (!claudeText.includes(protectedPath)) {
+        errors.push(new ValidationError({
+          code: ERROR_CODES.DRIFT_PROTECTED_PATH,
+          category: "drift",
+          file: "CLAUDE.md",
+          expected: protectedPath,
+          message: `protected path "${protectedPath}" from docs/repo-facts.json is not documented`,
+          hint: "add the protected path entry to CLAUDE.md or remove it from repo-facts.json",
+        }));
+      }
+    }
+  }
+
+  return { ok: errors.length === 0, errors };
+}

package/plugins/harness/src/check-spec-coverage.mjs

@@ -0,0 +1,95 @@
+import {
+  anyPathMatches,
+  extractTemplateSection,
+  isBotActor,
+  isMeaningfulSection,
+  listSpecDirs,
+  loadFacts,
+  readJson,
+} from "./spec-harness-lib.mjs";
+import { ValidationError, ERROR_CODES } from "./lib/errors.mjs";
+
+const COVERAGE_STATUSES = new Set(["approved", "implementing", "done"]);
+
+function normalizeSpecId(v) {
+  return v.replace(/^[`'"#]+|[`'"]+$/g, "").trim();
+}
+
+/**
+ * Enforce the spec-coverage contract for a PR: every protected-path change
+ * must be covered by an approved/implementing/done spec, or the PR body must
+ * carry a meaningful `## No-spec rationale` section. Known bot actors bypass
+ * the body contract.
+ *
+ * @param {import('./spec-harness-lib.mjs').HarnessContext} ctx
+ * @param {{ changedFiles: string[], isPullRequest: boolean, body: string, actor: string }} input
+ * @returns {{
+ *   ok: boolean,
+ *   errors: import('./lib/errors.mjs').ValidationError[],
+ *   protectedFiles: string[],
+ *   uncovered: string[],
+ *   note?: string
+ * }}
+ */
+export function checkSpecCoverage(ctx, input) {
+  const { changedFiles, isPullRequest, body, actor } = input;
+  const errors = [];
+  const facts = loadFacts(ctx);
+  const protectedFiles = changedFiles.filter((f) =>
+    (facts.protected_paths ?? []).some((pat) => anyPathMatches(pat, [f])),
+  );
+
+  const specs = listSpecDirs(ctx)
+    .map((d) => ({ dir: d, metadata: readJson(ctx, `docs/specs/${d}/spec.json`) }))
+    .filter(({ metadata }) => COVERAGE_STATUSES.has(metadata.status));
+
+  const uncovered = protectedFiles.filter((file) =>
+    !specs.some(({ metadata }) =>
+      (metadata.linked_paths ?? []).some((pat) => anyPathMatches(pat, [file])),
+    ),
+  );
+
+  const specSection = extractTemplateSection(body, "Spec ID");
+  const rationaleSection = extractTemplateSection(body, "No-spec rationale");
+
+  if (isBotActor(actor)) {
+    return { ok: true, errors: [], protectedFiles, uncovered, note: "bot bypass" };
+  }
+
+  if (isPullRequest && !isMeaningfulSection(specSection) && !isMeaningfulSection(rationaleSection) && protectedFiles.length > 0) {
+    errors.push(new ValidationError({
+      code: ERROR_CODES.COVERAGE_NO_SPEC_RATIONALE,
+      category: "coverage",
+      message: "pull request body must include either a Spec ID or a No-spec rationale section",
+      hint: "add `## Spec ID\\n<id>` or `## No-spec rationale\\n<reason>` to the PR body",
+    }));
+  }
+
+  if (isMeaningfulSection(specSection)) {
+    const known = new Set(specs.map(({ metadata }) => metadata.id));
+    const requested = specSection.split(/[\s,]+/).map(normalizeSpecId).filter(Boolean);
+    for (const id of requested) {
+      if (!known.has(id)) {
+        errors.push(new ValidationError({
+          code: ERROR_CODES.COVERAGE_UNKNOWN_SPEC_ID,
+          category: "coverage",
+          got: id,
+          message: `pull request body references unknown Spec ID "${id}"`,
+          hint: "check the spec directory under docs/specs/ or create the spec first",
+        }));
+      }
+    }
+  }
+
+  if (uncovered.length > 0 && !isMeaningfulSection(rationaleSection)) {
+    errors.push(new ValidationError({
+      code: ERROR_CODES.COVERAGE_UNCOVERED,
+      category: "coverage",
+      got: uncovered.join(", "),
+      message: "protected files changed without an approved, implementing, or done spec",
+      hint: "add a covering spec (status: approved/implementing/done) or a `## No-spec rationale` section",
+    }));
+  }
+
+  return { ok: errors.length === 0, errors, protectedFiles, uncovered };
+}

package/plugins/harness/src/index.mjs

@@ -0,0 +1,57 @@
+/**
+ * Public barrel for `@kaiohenricunha/harness`.
+ *
+ * Consumer contract:
+ *   import { createHarnessContext, validateSpecs, EXIT_CODES, ValidationError } from "@kaiohenricunha/harness";
+ *
+ * The surface intentionally stays small — deep imports are NOT a supported
+ * contract. If you find yourself reaching for an internal helper that is not
+ * re-exported here, open an issue.
+ */
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+
+// --- spec-harness-lib (18 exports) ---
+export {
+  createHarnessContext,
+  toPosix,
+  readJson,
+  readText,
+  pathExists,
+  git,
+  loadFacts,
+  listSpecDirs,
+  listRepoPaths,
+  escapeRegex,
+  globToRegExp,
+  matchesGlob,
+  anyPathMatches,
+  extractTemplateSection,
+  isMeaningfulSection,
+  getPullRequestContext,
+  isBotActor,
+  getChangedFiles,
+} from "./spec-harness-lib.mjs";
+
+// --- validators (6 entry points) ---
+export { validateSpecs } from "./validate-specs.mjs";
+export {
+  validateManifest,
+  refreshChecksums,
+} from "./validate-skills-inventory.mjs";
+export { checkInstructionDrift } from "./check-instruction-drift.mjs";
+export { checkSpecCoverage } from "./check-spec-coverage.mjs";
+export { scaffoldHarness } from "./init-harness-scaffold.mjs";
+
+// --- error taxonomy + exit codes ---
+export { ValidationError, ERROR_CODES, formatError } from "./lib/errors.mjs";
+export { EXIT_CODES } from "./lib/exit-codes.mjs";
+
+// --- package version (read from root package.json) ---
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkgPath = resolve(__dirname, "..", "..", "..", "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+/** The `@kaiohenricunha/harness` package version at import time. */
+export const version = pkg.version;

package/plugins/harness/src/init-harness-scaffold.mjs

@@ -0,0 +1,121 @@
+import fs from "fs";
+import path from "path";
+import { ValidationError, ERROR_CODES } from "./lib/errors.mjs";
+
+// Map template subtree prefixes to target prefixes
+const PREFIX_MAP = [
+  { from: "claude/", to: ".claude/" },
+  { from: "docs/", to: "docs/" },
+  { from: "workflows/", to: ".github/workflows/" },
+];
+
+function applyPrefixMap(relFromTemplates) {
+  for (const { from, to } of PREFIX_MAP) {
+    if (relFromTemplates.startsWith(from)) {
+      return to + relFromTemplates.slice(from.length);
+    }
+  }
+  // Fallback: keep as-is (shouldn't happen with well-formed templates/)
+  return relFromTemplates;
+}
+
+function substitutePlaceholders(content, placeholders) {
+  return content.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return Object.prototype.hasOwnProperty.call(placeholders, key)
+      ? placeholders[key]
+      : match;
+  });
+}
+
+/**
+ * Walk a directory recursively, yielding file paths.
+ * @param {string} dir - Absolute directory path to walk
+ * @returns {string[]} Sorted list of absolute file paths
+ */
+function walkFiles(dir) {
+  const results = [];
+  const SKIP_DIRS = new Set([".git", "node_modules"]);
+
+  function walk(current) {
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SKIP_DIRS.has(entry.name)) {
+          walk(path.join(current, entry.name));
+        }
+      } else if (entry.isFile()) {
+        results.push(path.join(current, entry.name));
+      }
+    }
+  }
+
+  walk(dir);
+  return results.sort();
+}
+
+/**
+ * Scaffold the harness template tree into a target repository.
+ *
+ * @param {{ templatesDir: string, targetDir: string, placeholders: object }} opts
+ * @param {{ force?: boolean }} [options]
+ * @returns {{ filesWritten: string[] }}
+ */
+export function scaffoldHarness(
+  { templatesDir, targetDir, placeholders },
+  { force = false } = {}
+) {
+  // Guard: refuse if already initialized
+  if (!force) {
+    const manifestPath = path.join(targetDir, ".claude", "skills-manifest.json");
+    const specsPath = path.join(targetDir, "docs", "specs");
+    if (fs.existsSync(manifestPath)) {
+      throw new ValidationError({
+        code: ERROR_CODES.SCAFFOLD_CONFLICT,
+        category: "scaffold",
+        file: manifestPath,
+        message:
+          `Repo already initialized: ${manifestPath} already exists. ` +
+          `Use --force to overwrite.`,
+        hint: "pass `{ force: true }` or remove .claude/skills-manifest.json",
+      });
+    }
+    if (fs.existsSync(specsPath)) {
+      throw new ValidationError({
+        code: ERROR_CODES.SCAFFOLD_CONFLICT,
+        category: "scaffold",
+        file: specsPath,
+        message:
+          `Repo already initialized: ${specsPath} already exists. ` +
+          `Use --force to overwrite.`,
+        hint: "pass `{ force: true }` or remove docs/specs/",
+      });
+    }
+  }
+
+  const sourceFiles = walkFiles(templatesDir);
+  const filesWritten = [];
+
+  for (const srcAbs of sourceFiles) {
+    const relFromTemplates = path.relative(templatesDir, srcAbs);
+    const targetRel = applyPrefixMap(relFromTemplates);
+    const destAbs = path.join(targetDir, targetRel);
+
+    // Create parent directories
+    fs.mkdirSync(path.dirname(destAbs), { recursive: true });
+
+    // Read, substitute, write
+    const raw = fs.readFileSync(srcAbs, "utf8");
+    const content = substitutePlaceholders(raw, placeholders);
+    fs.writeFileSync(destAbs, content, "utf8");
+
+    // Preserve executable bit from source
+    const srcMode = fs.statSync(srcAbs).mode;
+    if (srcMode & 0o111) {
+      fs.chmodSync(destAbs, srcMode & 0o777);
+    }
+
+    filesWritten.push(targetRel);
+  }
+
+  return { filesWritten: filesWritten.sort() };
+}