@hone-ai/cli 1.4.0

package/lib/autofix-guardrails.js

@@ -0,0 +1,124 @@
+'use strict';
+/**
+ * autofix-guardrails.js — H-016 CI auto-fix safety guardrails.
+ *
+ * Pure helpers — no I/O. Caller (.github/scripts/check-autofix-safety.js
+ * adopter-side) reads the diff via `git diff` + counts recent auto-fix
+ * commits via `git log --grep '\\[auto-fix\\]'`; passes both to
+ * evaluateAutofixSafety.
+ *
+ * Three guardrails per OptionsFlow E27-E:
+ *   - Max-attempts: refuse 3rd auto-fix push on same PR (loop guard)
+ *   - Snapshot-capitulation: reject `assert` line edits in test files
+ *     ("just update the snapshot" is the wrong fix)
+ *   - Scope allowlist: reject diffs outside src/, tests/, scripts/,
+ *     .github/, README.md, docs/
+ *
+ * Closes #60 sub-task (a). Sub-tasks (e/f) auto-install + (g) stack-aware
+ * lint tokens deferred to follow-up.
+ *
+ * 14th instance of pure-helpers + thin-CLI-shell pattern.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// Constants — exposed for adopter-side scripts that need to align
+// ─────────────────────────────────────────────────────────────────────
+
+// Refuse the 3rd auto-fix push on the same PR (count >= 2 blocks).
+const MAX_AUTOFIX_ATTEMPTS = 2;
+
+// Default scope allowlist. Adopters can extend via .pipeline-config.yml
+// (deferred — sub-task D4).
+const ALLOWED_SCOPE_PATTERNS = [
+  /^src\//,
+  /^tests?\//,         // tests/ or test/
+  /^scripts\//,
+  /^\.github\//,
+  /^README\.md$/,
+  /^docs\//,
+];
+
+// Detect snapshot-capitulation: a + or - line that starts with `assert`.
+// Only trips when the diff hunk is in a test path.
+const SNAPSHOT_CAPITULATION_RE = /^[+-]\s*assert\b/m;
+
+// Test path detector for snapshot-capitulation rule.
+const TEST_PATH_RE = /^\+\+\+ b\/(tests?\/|.*?\/__tests__\/)/m;
+
+// ─────────────────────────────────────────────────────────────────────
+// hasSnapshotCapitulation — detect assert-line edits in test diffs
+// ─────────────────────────────────────────────────────────────────────
+//   Walks the diff hunk by hunk. For each hunk targeting a test path,
+//   check for + or - lines starting with `assert`. Either form is
+//   capitulation: removing an assert weakens the test; changing one
+//   updates it to match buggy code.
+function hasSnapshotCapitulation(diff) {
+  if (typeof diff !== 'string' || diff.length === 0) return false;
+  // Split diff into per-file blocks (each `diff --git` starts a new block)
+  const blocks = diff.split(/^diff --git /m);
+  for (const block of blocks) {
+    if (!block || !block.includes('+++')) continue;
+    // Get the +++ b/<path> line — that's the destination path
+    const pathMatch = block.match(/^\+\+\+ b\/(.+)$/m);
+    if (!pathMatch) continue;
+    const dstPath = pathMatch[1];
+    // Is this a test file?
+    const isTestPath = /^tests?\//.test(dstPath) || /\/__tests__\//.test(dstPath) || /\.test\./.test(dstPath) || /\.spec\./.test(dstPath);
+    if (!isTestPath) continue;
+    // Check the hunk for assert-line edits
+    if (SNAPSHOT_CAPITULATION_RE.test(block)) return true;
+  }
+  return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// hasScopeViolation — detect diffs touching paths outside the allowlist
+// ─────────────────────────────────────────────────────────────────────
+function hasScopeViolation(diff) {
+  if (typeof diff !== 'string' || diff.length === 0) return false;
+  // Extract all `+++ b/<path>` lines
+  const matches = [...diff.matchAll(/^\+\+\+ b\/(.+)$/gm)];
+  for (const m of matches) {
+    const dstPath = m[1].trim();
+    // Skip /dev/null (deletion targets)
+    if (dstPath === '/dev/null') continue;
+    // Check against allowlist
+    const allowed = ALLOWED_SCOPE_PATTERNS.some(re => re.test(dstPath));
+    if (!allowed) return true;  // any out-of-scope path triggers
+  }
+  return false;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// evaluateAutofixSafety — main entry point
+// ─────────────────────────────────────────────────────────────────────
+//   inputs: { recentAutofixCount, diff }
+//   returns: { safe: boolean, blocked: string[] }
+//
+//   blocked array preserves deterministic order:
+//     ['max-attempts', 'snapshot-capitulation', 'scope-allowlist']
+function evaluateAutofixSafety({ recentAutofixCount = 0, diff = '' } = {}) {
+  const blocked = [];
+
+  if (recentAutofixCount >= MAX_AUTOFIX_ATTEMPTS) {
+    blocked.push('max-attempts');
+  }
+  if (hasSnapshotCapitulation(diff)) {
+    blocked.push('snapshot-capitulation');
+  }
+  if (hasScopeViolation(diff)) {
+    blocked.push('scope-allowlist');
+  }
+
+  return { safe: blocked.length === 0, blocked };
+}
+
+module.exports = {
+  MAX_AUTOFIX_ATTEMPTS,
+  ALLOWED_SCOPE_PATTERNS,
+  SNAPSHOT_CAPITULATION_RE,
+  TEST_PATH_RE,
+  hasSnapshotCapitulation,
+  hasScopeViolation,
+  evaluateAutofixSafety,
+};

package/lib/branch-protection.js

@@ -0,0 +1,256 @@
+'use strict';
+/**
+ * cli/lib/branch-protection.js — H-001
+ *
+ * Installs GitHub branch protection on a repository's default branch
+ * after `hone setup` finishes scaffolding workflows. Prevents
+ * admin-merge from silently bypassing the AI Code Review gate the
+ * setup just installed.
+ *
+ * Closes #10 (H-001).
+ *
+ * Exports
+ * -------
+ *  buildPayload({ contexts, requireReviews? })
+ *      Pure. Returns the JSON payload for `PUT /repos/:owner/:repo/branches/:branch/protection`.
+ *
+ *  mergeContexts(existing, added)
+ *      Pure. Dedupes context names and preserves first-seen order so a
+ *      pre-existing custom check (e.g. 'lint') is preserved when Hone
+ *      appends 'ai-code-review'.
+ *
+ *  parseGhError(stderr, exitCode)
+ *      Pure. Classifies a `gh` invocation failure into a stable kind:
+ *      no-gh / no-auth / no-admin / plan-restricted / org-ruleset / unknown.
+ *
+ *  installBranchProtection({ exec?, log?, opts? })
+ *      Orchestrator. Returns { status, reason?, branch?, manualCommand? }
+ *      where status ∈ 'installed' | 'skipped' | 'failed'. Never throws,
+ *      never exits — degrades gracefully so `hone setup` always returns 0.
+ *
+ * The `exec` parameter is injectable. Production calls default to a thin
+ * wrapper around child_process.spawnSync. Tests inject a stub matching
+ * the same { status, stdout, stderr } return shape — no real subprocess
+ * invocations during testing.
+ */
+
+const DEFAULT_REQUIRED_CHECKS = ['ai-code-review'];
+
+// ─────────────────────────────────────────────────────────────────────
+// defaultExec — production exec, wraps spawnSync
+// ─────────────────────────────────────────────────────────────────────
+function defaultExec(cmd, args, opts = {}) {
+  const { spawnSync } = require('child_process');
+  const result = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    status: result.status === null ? -1 : result.status,
+    stdout: result.stdout || '',
+    stderr: result.stderr || '',
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// buildPayload — pure
+// ─────────────────────────────────────────────────────────────────────
+function buildPayload({ contexts = [], requireReviews } = {}) {
+  // Dedupe contexts while preserving order
+  const dedupedContexts = [];
+  const seen = new Set();
+  for (const c of contexts) {
+    if (!seen.has(c)) { seen.add(c); dedupedContexts.push(c); }
+  }
+  const reviewCount = typeof requireReviews === 'number' && requireReviews > 0
+    ? requireReviews
+    : 1;
+  return {
+    required_status_checks: {
+      strict: true,
+      contexts: dedupedContexts,
+    },
+    enforce_admins: true,
+    required_pull_request_reviews: {
+      required_approving_review_count: reviewCount,
+      dismiss_stale_reviews: true,
+    },
+    restrictions: null,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// mergeContexts — pure
+// ─────────────────────────────────────────────────────────────────────
+function mergeContexts(existing, added) {
+  const existingArr = Array.isArray(existing) ? existing : [];
+  const addedArr = Array.isArray(added) ? added : [];
+  const out = [];
+  const seen = new Set();
+  for (const c of [...existingArr, ...addedArr]) {
+    if (!seen.has(c)) { seen.add(c); out.push(c); }
+  }
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// parseGhError — pure
+// ─────────────────────────────────────────────────────────────────────
+function parseGhError(stderr = '', exitCode = 0) {
+  const s = String(stderr || '');
+  // gh binary missing entirely
+  if (exitCode === 127 || /command not found|gh:.*not found/i.test(s)) {
+    return { kind: 'no-gh', message: 'gh CLI not installed (or not on PATH)' };
+  }
+  // gh installed but not authenticated
+  if (/gh auth (login|status|required)|not authenticated|authentication required/i.test(s)) {
+    return { kind: 'no-auth', message: 'gh CLI not authenticated — run `gh auth login`' };
+  }
+  // 403 / no admin rights
+  if (/resource not accessible|admin permission|admin rights required|403/i.test(s)) {
+    return { kind: 'no-admin', message: 'Resource not accessible — admin rights required on this repository' };
+  }
+  // Plan restriction (private + free)
+  if (/upgrade.*github (pro|team|enterprise)|github (pro|team|enterprise).*required|requires.*github (pro|team|enterprise)/i.test(s)) {
+    return { kind: 'plan-restricted', message: 'plan-restricted — branch protection requires GitHub Pro for private repos' };
+  }
+  // Org-level ruleset
+  if (/repository ruleset|ruleset bypass|protected by.*ruleset/i.test(s)) {
+    return { kind: 'org-ruleset', message: 'org ruleset blocks this change — coordinate with the org admin' };
+  }
+  // Anything else
+  const trimmed = s.trim();
+  return {
+    kind: 'unknown',
+    message: trimmed.length > 0
+      ? `gh failed: ${trimmed}`
+      : `gh failed with exit code ${exitCode}`,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// buildManualCommand — produces a copy-paste shell snippet for the user
+// ─────────────────────────────────────────────────────────────────────
+function buildManualCommand({ contexts = DEFAULT_REQUIRED_CHECKS, owner = '<owner>', repo = '<repo>', branch = 'main' } = {}) {
+  const contextLines = contexts
+    .map(c => `  -f 'required_status_checks[contexts][]=${c}' \\`)
+    .join('\n');
+  return [
+    `gh api --method PUT repos/${owner}/${repo}/branches/${branch}/protection \\`,
+    `  -f 'required_status_checks[strict]=true' \\`,
+    contextLines,
+    `  -f 'enforce_admins=true' \\`,
+    `  -f 'required_pull_request_reviews[required_approving_review_count]=1' \\`,
+    `  -f 'restrictions='`,
+  ].join('\n');
+}
+
+// ─────────────────────────────────────────────────────────────────────
+// installBranchProtection — orchestrator
+// ─────────────────────────────────────────────────────────────────────
+async function installBranchProtection({ exec = defaultExec, log = () => {}, opts = {} } = {}) {
+  const requiredChecks = (opts.requiredChecks && opts.requiredChecks.length)
+    ? opts.requiredChecks
+    : DEFAULT_REQUIRED_CHECKS;
+  const requireReviews = opts.requireReviews || 1;
+
+  // 1. Honor opt-out — short-circuit before any subprocess call
+  if (opts.skip) {
+    return {
+      status: 'skipped',
+      reason: '--no-branch-protection (opt-out)',
+    };
+  }
+
+  // 2. Resolve git remote
+  const remote = exec('git', ['remote', 'get-url', 'origin']);
+  if (remote.status !== 0) {
+    return {
+      status: 'skipped',
+      reason: 'no git remote — not a git repo, or remote "origin" missing',
+      manualCommand: buildManualCommand({ contexts: requiredChecks }),
+    };
+  }
+  if (!/github\.com/.test(remote.stdout)) {
+    return {
+      status: 'skipped',
+      reason: 'non-GitHub host (only github.com is supported for branch protection install)',
+    };
+  }
+
+  // 3. Resolve repo info via gh
+  const repoView = exec('gh', ['repo', 'view', '--json', 'owner,name,defaultBranchRef,private']);
+  if (repoView.status !== 0) {
+    const err = parseGhError(repoView.stderr, repoView.status);
+    return {
+      status: 'skipped',
+      reason: err.message,
+      manualCommand: buildManualCommand({ contexts: requiredChecks }),
+    };
+  }
+  let repoInfo;
+  try {
+    repoInfo = JSON.parse(repoView.stdout || '{}');
+  } catch {
+    return {
+      status: 'failed',
+      reason: 'could not parse `gh repo view` JSON output',
+      manualCommand: buildManualCommand({ contexts: requiredChecks }),
+    };
+  }
+  const owner = repoInfo.owner?.login;
+  const repo = repoInfo.name;
+  const branch = repoInfo.defaultBranchRef?.name || 'main';
+  if (!owner || !repo) {
+    return {
+      status: 'failed',
+      reason: '`gh repo view` did not return owner/name',
+      manualCommand: buildManualCommand({ contexts: requiredChecks }),
+    };
+  }
+
+  // 4. GET existing protection (404 = none, 200 = merge)
+  const protPath = `repos/${owner}/${repo}/branches/${branch}/protection`;
+  const existing = exec('gh', ['api', protPath]);
+  let existingContexts = [];
+  if (existing.status === 0) {
+    try {
+      const e = JSON.parse(existing.stdout || '{}');
+      existingContexts = (e && e.required_status_checks && Array.isArray(e.required_status_checks.contexts))
+        ? e.required_status_checks.contexts
+        : [];
+    } catch {
+      existingContexts = [];
+    }
+  }
+  // (non-zero exit is treated as "no existing protection" — the PUT below will succeed if the user has permissions)
+
+  // 5. Build merged payload
+  const mergedContexts = mergeContexts(existingContexts, requiredChecks);
+  const payload = buildPayload({ contexts: mergedContexts, requireReviews });
+
+  // 6. PUT
+  const put = exec(
+    'gh',
+    ['api', '--method', 'PUT', protPath, '--input', '-'],
+    { input: JSON.stringify(payload) }
+  );
+  if (put.status === 0) {
+    return { status: 'installed', branch };
+  }
+
+  // 7. PUT failed — classify and return graceful failure
+  const err = parseGhError(put.stderr, put.status);
+  return {
+    status: 'failed',
+    reason: err.message,
+    manualCommand: buildManualCommand({ contexts: mergedContexts, owner, repo, branch }),
+  };
+}
+
+module.exports = {
+  buildPayload,
+  mergeContexts,
+  parseGhError,
+  installBranchProtection,
+  // Internal helpers exposed for inspection / future reuse
+  buildManualCommand,
+  DEFAULT_REQUIRED_CHECKS,
+};

package/lib/ci-classifier.js

@@ -0,0 +1,150 @@
+'use strict';
+/**
+ * ci-classifier.js — H-061 rule-based CI failure classifier.
+ *
+ * Reads CI log text and returns named categories with severity ranking.
+ * Pure helper — no I/O. Caller provides the log text; we return the
+ * classification.
+ *
+ * Categories form a stable contract that downstream stories switch on:
+ *   - #19 (H-010 CI → skills feedback loop) consumes `category`
+ *   - #60 (CI auto-fix workflow templates) consumes `auto_fixable`
+ *
+ * 6th instance of the pure-helpers + thin-CLI-shell pattern in cli/lib/
+ * after auto-detect.js (H-018), learnings-parse.js (H-035),
+ * pipeline-status.js (H-009), metrics-collect.js (H-008),
+ * config-update.js (H-021).
+ *
+ * Reference impl: OptionsFlow's E27-C (Python). Ported to Node.js so
+ * adopters' CI runners don't require a Python install.
+ *
+ * Closes #61 (sub-task: classifier as CLI command). Auto-install
+ * workflow template deferred to Phase 6.1 (#60 — consumer of these
+ * categories).
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// CATEGORY_TABLE — stable contract (severity + auto_fixable per category)
+// ─────────────────────────────────────────────────────────────────────
+//   Severity ordering: 100 > 50 > 30 > 20 > 15 > 10 > 1
+//   Higher severity wins when multiple categories match the same log.
+//   Patterns intentionally broad — match common log shapes across
+//   stacks (Python, Node, Go, .NET, Salesforce). Adopter-specific
+//   patterns can be added in v2 via config.
+const CATEGORY_TABLE = [
+  {
+    category: 'security',
+    severity: 100,
+    auto_fixable: false,
+    patterns: [
+      // Bandit — match in either order (tool-name first OR severity-first).
+      // Real bandit output has the header "Run started:" then findings with
+      // "Severity: HIGH" lines; sometimes the tool name appears after.
+      /\bbandit\b[\s\S]{0,300}?(HIGH|MEDIUM|CRITICAL|severity)/i,
+      /(HIGH|MEDIUM|CRITICAL|severity)[\s\S]{0,300}?\bbandit\b/i,
+      /\bsafety\b[\s\S]{0,200}?vulnerability/i,
+      /npm audit[\s\S]{0,200}?(high|critical) severity/i,
+      /\bTrivy\b[\s\S]{0,200}?CRITICAL/i,
+      /\bsemgrep\b[\s\S]{0,200}?ERROR/i,
+    ],
+  },
+  {
+    category: 'test_logic',
+    severity: 50,
+    auto_fixable: false,
+    patterns: [
+      /\bAssertionError\b/,
+      /\bexpect\(.*?\)\.to\w+/,
+      /\bFAIL(ED)?\b.*?test/i,
+      /\bpytest\b.*?failed/i,
+      /Tests:\s*\d+\s*failed/i,
+    ],
+  },
+  {
+    category: 'e2e_flake',
+    severity: 30,
+    auto_fixable: false,
+    patterns: [
+      /\bTimeoutError\b/,
+      /selector .*? not found/i,
+      /\bPlaywright\b.*?timeout/i,
+      /\bCypress\b.*?retry/i,
+      /element .*? is not visible/i,
+    ],
+  },
+  {
+    category: 'baseline_tripwire',
+    severity: 20,
+    auto_fixable: true,
+    patterns: [
+      /bloated to \d+ lines.*?baseline.*?ceiling/i,
+      /baseline tripwire/i,
+      /size budget exceeded/i,
+    ],
+  },
+  {
+    category: 'lint',
+    severity: 15,
+    auto_fixable: true,
+    patterns: [
+      /\b[IE]\d{3,}\s+\[.*?\]/,           // ruff: "I001 [*] Import block..."
+      /\beslint\b[\s\S]{0,200}?(error|warn)/i,
+      /\bruff(\s+check)?\b[\s\S]{0,200}?(error|warn)/i,
+      /\bgolangci-lint\b/i,
+      /\bflake8\b[\s\S]{0,200}?:\d+:\d+:/,
+    ],
+  },
+  {
+    category: 'badge_drift',
+    severity: 10,
+    auto_fixable: true,
+    patterns: [
+      /README test count drifted/i,
+      /badge.*?(mismatch|drift|stale)/i,
+      /doc_freshness_check/i,
+    ],
+  },
+];
+
+const UNKNOWN = { category: 'unknown', severity: 1, auto_fixable: false };
+
+// ─────────────────────────────────────────────────────────────────────
+// classifyLogText — main entry point
+// ─────────────────────────────────────────────────────────────────────
+//   Returns array of { category, severity, auto_fixable, evidence }
+//   sorted desc by severity. Always returns at least one element
+//   (`unknown` if no match).
+function classifyLogText(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return [{ ...UNKNOWN, evidence: '' }];
+  }
+
+  const matches = [];
+  for (const cat of CATEGORY_TABLE) {
+    for (const re of cat.patterns) {
+      const m = text.match(re);
+      if (m) {
+        matches.push({
+          category: cat.category,
+          severity: cat.severity,
+          auto_fixable: cat.auto_fixable,
+          evidence: m[0].slice(0, 200),
+        });
+        break; // one evidence per category is enough — don't double-count
+      }
+    }
+  }
+
+  if (matches.length === 0) {
+    return [{ ...UNKNOWN, evidence: '' }];
+  }
+
+  // Stable sort: desc by severity (CATEGORY_TABLE order is already
+  // severity-desc, so push order is stable for tie-breaks)
+  return matches.sort((a, b) => b.severity - a.severity);
+}
+
+module.exports = {
+  CATEGORY_TABLE,
+  classifyLogText,
+};