@kaiohenricunha/harness 0.2.0

package/plugins/harness/bin/harness-init.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * harness-init — scaffold the harness template tree into a target repository.
+ *
+ * Flags:
+ *   --project-name <name>    defaults to basename(cwd)
+ *   --project-type <type>    defaults to "unknown"
+ *   --force                  overwrite an already-initialized repo
+ *   --target-dir <path>      scaffolding destination (defaults to cwd)
+ *
+ * Exits: 0 scaffold complete, 1 ValidationError (SCAFFOLD_CONFLICT), 2 env
+ * error, 64 usage error.
+ */
+
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { parse, helpText } from "../src/lib/argv.mjs";
+import { createOutput } from "../src/lib/output.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { formatError, ValidationError } from "../src/lib/errors.mjs";
+import { version } from "../src/index.mjs";
+import { scaffoldHarness } from "../src/index.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const META = {
+  name: "harness-init",
+  synopsis: "harness-init [OPTIONS]",
+  description: "Scaffold the harness template tree (.claude/, docs/, .github/workflows/, githooks/) into the current repo.",
+  flags: {
+    "project-name": { type: "string" },
+    "project-type": { type: "string" },
+    "target-dir": { type: "string" },
+    force: { type: "boolean" },
+  },
+};
+
+let argv;
+try {
+  argv = parse(process.argv.slice(2), META.flags);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(EXIT_CODES.USAGE);
+}
+
+if (argv.help) {
+  process.stdout.write(`${helpText(META)}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+if (argv.version) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const out = createOutput({ json: argv.json, noColor: argv.noColor });
+
+const targetDir = /** @type {string} */ (argv.flags["target-dir"] ?? process.cwd());
+const projectName = /** @type {string} */ (argv.flags["project-name"] ?? path.basename(targetDir));
+const projectType = /** @type {string} */ (argv.flags["project-type"] ?? "unknown");
+const force = Boolean(argv.flags.force);
+
+const templatesDir = path.resolve(__dirname, "..", "templates");
+const today = new Date().toISOString().slice(0, 10);
+
+try {
+  const { filesWritten } = scaffoldHarness(
+    {
+      templatesDir,
+      targetDir,
+      placeholders: { project_name: projectName, project_type: projectType, today },
+    },
+    { force }
+  );
+  out.pass(`harness initialized in ${targetDir} (${filesWritten.length} files)`);
+  if (argv.verbose) {
+    for (const f of filesWritten) out.info(`  ${f}`);
+  }
+  out.flush();
+  process.exit(EXIT_CODES.OK);
+} catch (err) {
+  if (err instanceof ValidationError) {
+    out.fail(formatError(err, { verbose: argv.verbose }), err.toJSON());
+    out.flush();
+    process.exit(EXIT_CODES.VALIDATION);
+  }
+  out.fail(`scaffold failed: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}

package/plugins/harness/bin/harness-validate-skills.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+/**
+ * harness-validate-skills — validates `.claude/skills-manifest.json` against
+ * the sha256 checksums recorded for every indexed skill/command, and flags
+ * orphan files on disk + dependency cycles.
+ *
+ * Exits: 0 manifest valid, 1 one or more violations, 2 env error, 64 usage
+ * error.
+ */
+
+import { parse, helpText } from "../src/lib/argv.mjs";
+import { createOutput } from "../src/lib/output.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { formatError } from "../src/lib/errors.mjs";
+import { version } from "../src/index.mjs";
+import {
+  createHarnessContext,
+  validateManifest,
+  refreshChecksums,
+} from "../src/index.mjs";
+
+const META = {
+  name: "harness-validate-skills",
+  synopsis: "harness-validate-skills [OPTIONS]",
+  description: "Validate .claude/skills-manifest.json checksums, orphans, and DAG. Use --update to rewrite checksums in place.",
+  flags: {
+    "repo-root": { type: "string" },
+    update: { type: "boolean" },
+  },
+};
+
+let argv;
+try {
+  argv = parse(process.argv.slice(2), META.flags);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(EXIT_CODES.USAGE);
+}
+
+if (argv.help) {
+  process.stdout.write(`${helpText(META)}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+if (argv.version) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const out = createOutput({ json: argv.json, noColor: argv.noColor });
+
+let ctx;
+try {
+  ctx = createHarnessContext({ repoRoot: argv.flags["repo-root"] });
+} catch (err) {
+  out.fail(`could not resolve repo root: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+if (argv.flags.update) {
+  try {
+    refreshChecksums(ctx);
+    out.pass(`manifest refreshed at ${ctx.manifestPath}`);
+    out.flush();
+    process.exit(EXIT_CODES.OK);
+  } catch (err) {
+    out.fail(`refresh failed: ${err.message}`);
+    out.flush();
+    process.exit(EXIT_CODES.ENV);
+  }
+}
+
+let result;
+try {
+  result = validateManifest(ctx);
+} catch (err) {
+  out.fail(err.message);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+if (result.ok) {
+  out.pass(`manifest valid (${result.manifest.skills.length} skills)`);
+  out.flush();
+  process.exit(EXIT_CODES.OK);
+}
+
+for (const err of result.errors) {
+  out.fail(formatError(err, { verbose: argv.verbose }), err.toJSON ? err.toJSON() : undefined);
+}
+out.flush();
+process.exit(EXIT_CODES.VALIDATION);

package/plugins/harness/bin/harness-validate-specs.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * harness-validate-specs — validates every `docs/specs/<id>/spec.json` in the
+ * repo against the structured-error contract from `validate-specs.mjs`.
+ *
+ * Exits: 0 all specs valid, 1 one or more validation failures, 2 env error,
+ * 64 usage error.
+ */
+
+import { parse, helpText } from "../src/lib/argv.mjs";
+import { createOutput } from "../src/lib/output.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+import { formatError } from "../src/lib/errors.mjs";
+import { version } from "../src/index.mjs";
+import {
+  createHarnessContext,
+  listSpecDirs,
+  validateSpecs,
+} from "../src/index.mjs";
+
+const META = {
+  name: "harness-validate-specs",
+  synopsis: "harness-validate-specs [OPTIONS]",
+  description: "Validate every spec.json under docs/specs/ against the StructuredError contract.",
+  flags: {
+    "repo-root": { type: "string" },
+  },
+};
+
+let argv;
+try {
+  argv = parse(process.argv.slice(2), META.flags);
+} catch (err) {
+  process.stderr.write(`${err.message}\n`);
+  process.exit(EXIT_CODES.USAGE);
+}
+
+if (argv.help) {
+  process.stdout.write(`${helpText(META)}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+if (argv.version) {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const out = createOutput({ json: argv.json, noColor: argv.noColor });
+
+let ctx;
+try {
+  ctx = createHarnessContext({ repoRoot: argv.flags["repo-root"] });
+} catch (err) {
+  out.fail(`could not resolve repo root: ${err.message}`);
+  out.flush();
+  process.exit(EXIT_CODES.ENV);
+}
+
+const result = validateSpecs(ctx);
+if (result.ok) {
+  const count = listSpecDirs(ctx).length;
+  out.pass(`${count} spec(s) valid`);
+  out.flush();
+  process.exit(EXIT_CODES.OK);
+}
+
+for (const err of result.errors) {
+  out.fail(formatError(err, { verbose: argv.verbose }), err.toJSON ? err.toJSON() : undefined);
+}
+out.flush();
+process.exit(EXIT_CODES.VALIDATION);

package/plugins/harness/bin/harness.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Umbrella dispatcher. Usage:
+ *
+ *   harness --version
+ *   harness --help
+ *   harness <subcommand> [args...]      # delegates to harness-<subcommand>.mjs
+ *
+ * Known subcommands mirror the bin/* entries shipped by the package:
+ *   validate-skills, validate-specs, check-spec-coverage,
+ *   check-instruction-drift, detect-drift, doctor, init.
+ *
+ * Exits: 0 ok, 1 delegated failure, 2 env error, 64 usage error.
+ */
+
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { version } from "../src/index.mjs";
+import { EXIT_CODES } from "../src/lib/exit-codes.mjs";
+
+const SUBCOMMANDS = [
+  "validate-skills",
+  "validate-specs",
+  "check-spec-coverage",
+  "check-instruction-drift",
+  "detect-drift",
+  "doctor",
+  "init",
+];
+
+function printUsage() {
+  process.stdout.write(
+    [
+      "harness — structured-error-emitting CLI for @kaiohenricunha/harness",
+      "",
+      "Usage:",
+      "  harness <subcommand> [options]",
+      "  harness --version",
+      "  harness --help",
+      "",
+      "Subcommands:",
+      ...SUBCOMMANDS.map((s) => `  ${s.padEnd(26)}runs harness-${s}`),
+      "",
+      "Every subcommand also exists as a standalone bin (e.g. `npx harness-doctor`).",
+      "Each subcommand supports --help / --version / --json / --verbose / --no-color.",
+      "",
+      "Exit codes: 0 ok, 1 validation failure, 2 env error, 64 usage error.",
+      "",
+    ].join("\n")
+  );
+}
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+  printUsage();
+  process.exit(EXIT_CODES.OK);
+}
+
+if (args[0] === "--version" || args[0] === "-V") {
+  process.stdout.write(`${version}\n`);
+  process.exit(EXIT_CODES.OK);
+}
+
+const sub = args[0];
+if (!SUBCOMMANDS.includes(sub)) {
+  process.stderr.write(
+    `harness: unknown subcommand '${sub}'. Run 'harness --help' for the list.\n`
+  );
+  process.exit(EXIT_CODES.USAGE);
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const binPath = resolve(__dirname, `harness-${sub}.mjs`);
+if (!existsSync(binPath)) {
+  process.stderr.write(
+    `harness: bin 'harness-${sub}' not found at ${binPath}. Did the package install correctly?\n`
+  );
+  process.exit(EXIT_CODES.ENV);
+}
+
+const child = spawn(process.execPath, [binPath, ...args.slice(1)], {
+  stdio: "inherit",
+});
+child.on("exit", (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  process.exit(code ?? EXIT_CODES.ENV);
+});

package/plugins/harness/hooks/guard-destructive-git.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# PreToolUse hook: block destructive git operations.
+# Reads JSON from stdin (Claude Code hook protocol).
+# Exit 2 = block the tool call (Claude Code hook protocol — NOT the harness
+# validator exit convention). Exit 0 = allow.
+#
+# Bypass: set BYPASS_DESTRUCTIVE_GIT=1 in the command's environment when you
+# genuinely need to run a destructive git invocation. Use sparingly — the
+# block exists because these operations are silently destructive.
+
+# Fail open if jq is not installed (don't break all Bash tool calls).
+if ! command -v jq >/dev/null 2>&1; then
+  exit 0
+fi
+
+if [ "${BYPASS_DESTRUCTIVE_GIT:-0}" = "1" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty')
+[ "$TOOL" = "Bash" ] || exit 0
+
+CMD=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // empty')
+# Normalize whitespace: tabs -> space, collapse runs of whitespace so regex
+# anchors only have to reason about single spaces.
+NORM=$(printf '%s' "$CMD" | tr '\t' ' ' | tr -s ' ')
+
+# Boundary before the `git` token is one of: start-of-line, whitespace, or a
+# command-chaining separator (`;`, `&&`, `||`, `|`). This prevents false
+# positives like `echo git` inside a quoted string while still catching
+# `foo && git reset --hard`.
+BOUNDARY='(^|[[:space:];&|])'
+G='git[[:space:]]+'
+
+# Destructive verbs. Each alternative is anchored on the right by at least one
+# flag/keyword that makes the call unambiguously destructive.
+PATTERNS=(
+  "${BOUNDARY}${G}reset[[:space:]]+--hard(\b|[[:space:]]|$)"
+  "${BOUNDARY}${G}push[[:space:]][^&;|]*(-f|--force|--force-with-lease)(\b|=|[[:space:]]|$)"
+  "${BOUNDARY}${G}clean[[:space:]][^&;|]*(-[a-zA-Z]*f[a-zA-Z]*|--force)(\b|=|[[:space:]]|$)"
+  "${BOUNDARY}${G}checkout[[:space:]]+\.(\b|$)"
+  "${BOUNDARY}${G}restore[[:space:]]+\.(\b|$)"
+  "${BOUNDARY}${G}branch[[:space:]]+-D\b"
+  "${BOUNDARY}${G}worktree[[:space:]]+remove[[:space:]]+--force\b"
+)
+
+for rx in "${PATTERNS[@]}"; do
+  if printf '%s' "$NORM" | grep -qE "$rx"; then
+    {
+      echo "BLOCKED: Destructive git operation detected. Get explicit user confirmation first."
+      echo "         Bypass (only with user confirmation): BYPASS_DESTRUCTIVE_GIT=1 <your command>"
+    } >&2
+    exit 2
+  fi
+done
+
+exit 0

package/plugins/harness/scripts/auto-update-manifest.mjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+// auto-update-manifest.mjs — thin pre-commit wrapper.
+// Invokes harness-validate-skills --update from the package bin,
+// using the current working directory as repo root.
+
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { join, dirname } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const bin = join(__dirname, '..', 'bin', 'harness-validate-skills.mjs');
+
+try {
+  execFileSync(process.execPath, [bin, '--update'], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+} catch (e) {
+  process.exit(e.status ?? 1);
+}

package/plugins/harness/scripts/detect-branch-drift.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// detect-branch-drift.mjs — walk .claude/commands/*.md on HEAD,
+// diff each against origin/main, report a table. Exit 1 if any file
+// has diverged AND its last-main-commit is >14 days old.
+
+import { execFileSync } from 'child_process';
+
+const DAY_S = 86400;
+const STALE_DAYS = 14;
+
+function exec(cmd, args, cwd) {
+  try {
+    return execFileSync(cmd, args, { cwd, encoding: 'utf8' }).trim();
+  } catch (e) {
+    return '';
+  }
+}
+
+// Parse --repo-root flag
+const args = process.argv.slice(2);
+let repoRoot;
+const flagIdx = args.indexOf('--repo-root');
+if (flagIdx !== -1) {
+  repoRoot = args[flagIdx + 1];
+} else {
+  repoRoot = exec('git', ['rev-parse', '--show-toplevel'], process.cwd());
+}
+
+if (!repoRoot) {
+  console.error('Could not determine repo root. Use --repo-root <path>.');
+  process.exit(2);
+}
+
+// List .claude/commands/*.md files tracked on HEAD
+const lsTree = exec('git', ['ls-tree', '-r', '--name-only', 'HEAD', '.claude/commands/'], repoRoot);
+const files = lsTree.split('\n').filter(f => f.endsWith('.md'));
+
+if (files.length === 0) {
+  console.log('no drift detected (no .claude/commands/*.md on HEAD)');
+  process.exit(0);
+}
+
+const now = Math.floor(Date.now() / 1000);
+const rows = [];
+let anyStale = false;
+
+for (const file of files) {
+  const diff = exec('git', ['diff', 'origin/main', '--', file], repoRoot);
+  const diverged = diff.length > 0;
+
+  let daysBehind = 0;
+  if (diverged) {
+    const tsStr = exec('git', ['log', '-1', '--format=%ct', 'origin/main', '--', file], repoRoot);
+    const ts = parseInt(tsStr, 10);
+    if (!isNaN(ts) && ts > 0) {
+      daysBehind = Math.floor((now - ts) / DAY_S);
+    }
+    if (daysBehind > STALE_DAYS) anyStale = true;
+  }
+
+  rows.push({ file, diverged, daysBehind });
+}
+
+const anyDiverged = rows.some(r => r.diverged);
+if (!anyDiverged) {
+  console.log('no drift detected');
+  process.exit(0);
+}
+
+// Print table
+const header = `${'FILE'.padEnd(50)} ${'DIVERGED'.padEnd(10)} DAYS-BEHIND-MAIN`;
+console.log(header);
+console.log('-'.repeat(header.length));
+for (const r of rows) {
+  const name = r.file.padEnd(50);
+  const div  = (r.diverged ? 'yes' : 'no').padEnd(10);
+  const days = r.diverged ? String(r.daysBehind) : '-';
+  console.log(`${name} ${div} ${days}`);
+}
+
+process.exit(anyStale ? 1 : 0);

package/plugins/harness/scripts/lib/output.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# output.sh — shared ✓/✗/⚠ helpers for every harness shell script.
+#
+# Gold-standard originates from plugins/harness/scripts/validate-settings.sh:43-45.
+# Every consumer should:
+#
+#   # shellcheck source=plugins/harness/scripts/lib/output.sh
+#   source "$(dirname "${BASH_SOURCE[0]}")/lib/output.sh"
+#   out_init            # sets G/R/Y/N + FAIL/WARN globals, honors --json + NO_COLOR
+#   pass "JSON well-formed"
+#   fail "SEC-2 skipDangerousModePermissionPrompt is set"
+#   warn "projects/ close to budget"
+#   out_summary         # prints "Summary: N failure(s), N warning(s)"
+#
+# When HARNESS_JSON=1 is set, pass/fail/warn buffer JSON objects with the shape
+#   { "check": "...", "category": "...", "status": "pass|fail|warn", "message": "..." }
+# into HARNESS_JSON_BUFFER; callers flush with `out_flush`. The `category`
+# defaults to the CATEGORY env; individual calls can override with the
+# two-argument form: `fail SEC-2 "skipDangerous... is set"`.
+
+# Shell-scoped globals are set by out_init. Declaring defaults here keeps
+# callers working even if they forget out_init and lets linters see the
+# assignments.
+FAIL=${FAIL:-0}
+WARN=${WARN:-0}
+G=""; R=""; Y=""; N=""
+HARNESS_JSON=${HARNESS_JSON:-0}
+HARNESS_JSON_BUFFER=""
+# shellcheck disable=SC2034  # CATEGORY is consumed by sourced scripts
+CATEGORY=${CATEGORY:-general}
+
+out_init() {
+  FAIL=0
+  WARN=0
+  HARNESS_JSON_BUFFER=""
+  if [ "${HARNESS_JSON:-0}" = "1" ] || [ "${NO_COLOR:-}" != "" ] || [ ! -t 1 ]; then
+    G=""; R=""; Y=""; N=""
+  else
+    G=$'\033[32m'; R=$'\033[31m'; Y=$'\033[33m'; N=$'\033[0m'
+  fi
+}
+
+# Internal: buffer one JSON object. Escapes the double-quotes and backslashes in $message.
+_out_json_push() {
+  local status="$1" check="$2" message="$3"
+  local cat="${4:-$CATEGORY}"
+  # Escape backslash then double-quote for safe JSON inclusion.
+  message=${message//\\/\\\\}
+  message=${message//\"/\\\"}
+  check=${check//\\/\\\\}
+  check=${check//\"/\\\"}
+  local entry
+  entry=$(printf '{"check":"%s","category":"%s","status":"%s","message":"%s"}' \
+    "$check" "$cat" "$status" "$message")
+  if [ -z "$HARNESS_JSON_BUFFER" ]; then
+    HARNESS_JSON_BUFFER="$entry"
+  else
+    HARNESS_JSON_BUFFER="$HARNESS_JSON_BUFFER,$entry"
+  fi
+}
+
+pass() {
+  local msg="$1"
+  if [ "${HARNESS_JSON:-0}" = "1" ]; then
+    _out_json_push pass "${2:-$msg}" "$msg"
+  else
+    printf '  %s✓%s %s\n' "$G" "$N" "$msg"
+  fi
+}
+
+fail() {
+  local msg="$1"
+  FAIL=$((FAIL+1))
+  if [ "${HARNESS_JSON:-0}" = "1" ]; then
+    _out_json_push fail "${2:-$msg}" "$msg"
+  else
+    printf '  %s✗%s %s\n' "$R" "$N" "$msg"
+  fi
+}
+
+warn() {
+  local msg="$1"
+  WARN=$((WARN+1))
+  if [ "${HARNESS_JSON:-0}" = "1" ]; then
+    _out_json_push warn "${2:-$msg}" "$msg"
+  else
+    printf '  %s⚠%s %s\n' "$Y" "$N" "$msg"
+  fi
+}
+
+out_flush() {
+  if [ "${HARNESS_JSON:-0}" = "1" ]; then
+    printf '{"events":[%s],"counts":{"fail":%d,"warn":%d}}\n' \
+      "$HARNESS_JSON_BUFFER" "$FAIL" "$WARN"
+  fi
+}
+
+out_summary() {
+  if [ "${HARNESS_JSON:-0}" = "1" ]; then
+    out_flush
+  else
+    echo
+    echo "Summary: $FAIL failure(s), $WARN warning(s)"
+  fi
+}

package/plugins/harness/scripts/refresh-worktrees.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# refresh-worktrees.sh — for each active worktree under .claude/worktrees/,
+# run `git fetch origin main` and `git merge --ff-only origin/main` if the
+# worktree is clean. Report (and skip) any dirty worktree.
+
+set -euo pipefail
+
+ROOT="${1:-$(git rev-parse --show-toplevel)}"
+cd "$ROOT"
+
+WT_BASE="$ROOT/.claude/worktrees"
+[ -d "$WT_BASE" ] || { echo "no worktrees at $WT_BASE"; exit 0; }
+
+git fetch origin main
+
+for wt in "$WT_BASE"/*/; do
+  [ -d "$wt" ] || continue
+  name=$(basename "$wt")
+  (
+    cd "$wt"
+    if ! git diff --quiet || ! git diff --cached --quiet; then
+      echo "SKIP (dirty): $name"
+      exit 0
+    fi
+    if git merge-base --is-ancestor origin/main HEAD; then
+      echo "OK:   $name (up to date)"
+      exit 0
+    fi
+    if git merge --ff-only origin/main; then
+      echo "FF:   $name"
+    else
+      echo "CONFLICT: $name (manual resolution needed)"
+    fi
+  )
+done