@hone-ai/cli 1.4.0

package/lib/refresh-check.js

@@ -0,0 +1,67 @@
+'use strict';
+/**
+ * refresh-check.js — H-015 skill freshness evaluator.
+ *
+ * Pure helpers — no I/O. Caller (hone-cli.js) reads the config + walks
+ * the source dirs to count files; passes those values in.
+ *
+ * Closes #24 parts 1+2 (time + growth triggers). Architecture trigger
+ * (new top-level dir) deferred to v2 because storing arrays in
+ * .pipeline-config.yml requires a comment-preserving YAML lib (vs the
+ * surgical-regex strategy used here per H-021/L2).
+ *
+ * 8th instance of pure-helpers + thin-CLI-shell pattern in cli/lib/
+ * after H-018, H-035, H-009, H-008, H-021, H-061, H-010.
+ */
+
+// ─────────────────────────────────────────────────────────────────────
+// evaluateRefresh — pure freshness evaluator
+// ─────────────────────────────────────────────────────────────────────
+//   Inputs:
+//     now: Date | string                    (defaults to Date.now())
+//     lastDerived: string | null            (ISO timestamp from config)
+//     lastDerivedSrcFiles: number | null    (saved src-file count)
+//     currentSrcFiles: number               (current src-file count)
+//     refreshIntervalDays: number           (default 90)
+//     growthPct: number                     (default 50, i.e. 1.5x)
+//
+//   Returns: { stale: boolean, reasons: string[] }
+//     reasons can include: 'never-derived', 'time-based', 'growth-based'
+function evaluateRefresh(opts = {}) {
+  const reasons = [];
+
+  // ── Never-derived ───────────────────────────────────
+  if (!opts.lastDerived) {
+    reasons.push('never-derived');
+    return { stale: true, reasons };
+  }
+
+  // ── Time-based trigger ────────────────────────────
+  const lastMs = new Date(opts.lastDerived).getTime();
+  const nowMs  = (opts.now ? new Date(opts.now) : new Date()).getTime();
+  if (Number.isFinite(lastMs) && Number.isFinite(nowMs)) {
+    const ageDays = (nowMs - lastMs) / 86400000;
+    const intervalDays = (typeof opts.refreshIntervalDays === 'number' && opts.refreshIntervalDays > 0)
+      ? opts.refreshIntervalDays
+      : 90;
+    if (ageDays > intervalDays) {
+      reasons.push('time-based');
+    }
+  }
+
+  // ── Growth-based trigger ──────────────────────────
+  // Skip when previous count is missing or zero (E2 graceful — avoid div-by-zero).
+  if (typeof opts.lastDerivedSrcFiles === 'number'
+      && opts.lastDerivedSrcFiles > 0
+      && typeof opts.currentSrcFiles === 'number') {
+    const growthPct = (typeof opts.growthPct === 'number') ? opts.growthPct : 50;
+    const ratio = opts.currentSrcFiles / opts.lastDerivedSrcFiles;
+    if (ratio >= 1 + growthPct / 100) {
+      reasons.push('growth-based');
+    }
+  }
+
+  return { stale: reasons.length > 0, reasons };
+}
+
+module.exports = { evaluateRefresh };

package/lib/refresh-knowledge.js

@@ -0,0 +1,360 @@
+'use strict';
+/**
+ * refresh-knowledge.js — HC-003 (first multi-channel orchestration wrapper).
+ *
+ * Implements OptionsFlow E22-E-L3 (deferred during SC-008 absorption).
+ *
+ * Orchestrates `hone sync` (enterprise skills from server) + `hone derive`
+ * (domain skills from local codebase) with backup-before-write +
+ * section-aware restore + halt-and-restore-on-failure.
+ *
+ * Pure-helper-with-injected-IO style (Category B per cli/lib/README.md):
+ *   - `runChannel` is injectable for testability
+ *   - All filesystem ops via Node fs (could be injected; kept simple here)
+ *   - Returns {findings, summary, backupPath, channelResults, ...}
+ *   - Never throws
+ *
+ * Architecture decisions (per HC-003 step-1-plan.md):
+ *   - Backup mechanism: tar archive (.hone/backups/<ISO>.tar.gz)
+ *   - Channel runner: injectable via `runChannel(name, repoRoot) → result`
+ *   - Restore strategy: section-aware (re-apply user sections from backup)
+ *   - Failure handling: halt-and-restore (any channel error → restore + report)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execSync } = require('node:child_process');
+
+const KNOWLEDGE_DIRS = [
+  '.github/skills',
+  '.github/agents',
+  '.claude/agents',
+  '.github/copilot-instructions.md',
+];
+
+const ENTERPRISE_MANAGED_START_RE = /<!--\s*ENTERPRISE-MANAGED[^>]*-->/;
+const ENTERPRISE_MANAGED_END_RE = /<!--\s*END ENTERPRISE-MANAGED\s*-->/;
+const FRONTMATTER_MANAGED_RE = /^---[\s\S]*?managed_by:\s*\S+[\s\S]*?---/m;
+
+/**
+ * Default channel runner — invokes `hone <name>` via execSync.
+ * Tests inject a fake runner; real CLI uses this default.
+ */
+function defaultRunChannel(name, repoRoot) {
+  const cliPath = path.resolve(__dirname, '..', 'hone-cli.js');
+  try {
+    const out = execSync(`node "${cliPath}" ${name}`, {
+      cwd: repoRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5 * 60 * 1000,
+    });
+    return { ok: true, exitCode: 0, stdout: out };
+  } catch (e) {
+    return {
+      ok: false,
+      exitCode: e.status || 1,
+      stdout: (e.stdout || '').toString(),
+      stderr: (e.stderr || e.message || '').toString(),
+      error: e.message,
+    };
+  }
+}
+
+/**
+ * Multi-channel refresh wrapper.
+ *
+ * @param {object} args
+ * @param {string} args.repoRoot
+ * @param {string[]} [args.channels=['sync','derive']]   user-specified order
+ * @param {boolean} [args.preserveUserSections=true]
+ * @param {string}  [args.backupDir='.hone/backups']
+ * @param {boolean} [args.dryRun=false]
+ * @param {boolean} [args.force=false]
+ * @param {Function}[args.runChannel]                    injectable; defaults to defaultRunChannel
+ * @param {Function}[args.now=() => new Date()]
+ * @returns {{
+ *   findings: Array,
+ *   summary: { total, errors, warnings, info },
+ *   backupPath: string|null,
+ *   channelResults: Array<{name, ok, exitCode}>,
+ *   diffSummary: object,
+ *   restored: string[],
+ *   dryRun: boolean,
+ * }}
+ */
+function refreshKnowledge(args = {}) {
+  const {
+    repoRoot,
+    channels = ['sync', 'derive'],
+    preserveUserSections = true,
+    backupDir = '.hone/backups',
+    dryRun = false,
+    force = false,
+    runChannel = defaultRunChannel,
+    now = () => new Date(),
+  } = args;
+
+  const findings = [];
+  const channelResults = [];
+  const restored = [];
+  let backupPath = null;
+
+  if (!repoRoot || typeof repoRoot !== 'string') {
+    return wrap(
+      [{ severity: 'ERROR', code: 'invalid-args', message: 'repoRoot is required' }],
+      backupPath, channelResults, restored, dryRun,
+    );
+  }
+
+  if (!Array.isArray(channels) || channels.length === 0) {
+    return wrap(
+      [{ severity: 'ERROR', code: 'invalid-channels', message: 'channels must be a non-empty array' }],
+      backupPath, channelResults, restored, dryRun,
+    );
+  }
+
+  // HC-005-B: --force is a real alias for preserveUserSections=false.
+  // Both flags effectively disable section-aware restore. `force=true`
+  // wins over preserveUserSections=true for user clarity (HC-001-L1
+  // marker discipline naming convention).
+  // Push the WARN finding AFTER arg validation so a never-actually-ran
+  // invocation doesn't carry the warning alongside its invalid-args error.
+  const effectivePreserve = force ? false : preserveUserSections;
+  if (force) {
+    findings.push({
+      severity: 'WARN',
+      code: 'force-mode',
+      message: '--force enabled; user sections WILL NOT be preserved (DANGEROUS — alias for --no-preserve)',
+    });
+  }
+
+  // Snapshot current adopter knowledge content (for section-aware restore + tar contents)
+  const knowledgeFiles = collectKnowledgeFiles(repoRoot);
+  const userSectionSnapshot = effectivePreserve
+    ? snapshotUserSections(knowledgeFiles)
+    : new Map();
+
+  // Dry-run: print plan, no side effects
+  if (dryRun) {
+    findings.push({
+      severity: 'INFO',
+      code: 'dry-run-plan',
+      message: `Would run channels in order: ${channels.join(' → ')}; backup to ${backupDir}; preserveUserSections=${preserveUserSections}`,
+    });
+    return wrap(findings, null, channelResults, restored, true);
+  }
+
+  // 1. Create backup BEFORE running any channel
+  try {
+    backupPath = createBackup({ repoRoot, backupDir, knowledgeFiles, now });
+    if (!backupPath) {
+      findings.push({
+        severity: 'WARN',
+        code: 'no-knowledge-files',
+        message: 'No adopter knowledge files found; running channels without backup',
+      });
+    }
+  } catch (e) {
+    findings.push({
+      severity: 'ERROR',
+      code: 'backup-failed',
+      message: `failed to create backup: ${e.message}`,
+    });
+    return wrap(findings, null, channelResults, restored, false);
+  }
+
+  // 2. Run channels in order; halt-and-restore on first failure
+  for (const channelName of channels) {
+    const result = runChannel(channelName, repoRoot);
+    channelResults.push({ name: channelName, ok: result.ok, exitCode: result.exitCode });
+    if (!result.ok) {
+      findings.push({
+        severity: 'ERROR',
+        code: 'channel-failed',
+        message: `channel '${channelName}' failed (exit ${result.exitCode}): ${result.error || result.stderr || 'unknown'}`,
+      });
+      // Halt-and-restore
+      if (backupPath && fs.existsSync(backupPath)) {
+        try {
+          restoreFromBackup({ repoRoot, backupPath });
+          findings.push({
+            severity: 'INFO',
+            code: 'restored-from-backup',
+            message: `restored adopter knowledge files from ${backupPath} after channel '${channelName}' failure`,
+          });
+        } catch (re) {
+          // HC-005-B: explicit manual-recovery instructions when restore itself fails.
+          // This is the 4th state HC-003-L1 didn't acknowledge:
+          // all-success / partial-completion-with-restore / all-fail-channel-1 / restore-failed.
+          findings.push({
+            severity: 'ERROR',
+            code: 'restore-failed',
+            manualInterventionRequired: true,
+            backupPath,
+            message: `RESTORE-FAILED — manual intervention required. Backup tar archive at ${backupPath}; recover with: tar -xzf "${backupPath}". Underlying error: ${re.message}`,
+          });
+        }
+      }
+      return wrap(findings, backupPath, channelResults, restored, false);
+    }
+  }
+
+  // 3. Section-aware restore: re-apply adopter user sections that channel runs may have overwritten
+  if (effectivePreserve && userSectionSnapshot.size > 0) {
+    for (const [filePath, userSection] of userSectionSnapshot.entries()) {
+      try {
+        if (!fs.existsSync(filePath)) continue;
+        const current = fs.readFileSync(filePath, 'utf8');
+        if (!current.includes(userSection.trim()) && userSection.trim().length > 0) {
+          // Channel run dropped the user section; re-apply
+          const merged = mergeUserSection(current, userSection);
+          fs.writeFileSync(filePath, merged);
+          restored.push(filePath);
+        }
+      } catch (e) {
+        findings.push({
+          severity: 'WARN',
+          code: 'restore-section-failed',
+          message: `failed to restore user section in ${filePath}: ${e.message}`,
+        });
+      }
+    }
+  }
+
+  return wrap(findings, backupPath, channelResults, restored, false);
+}
+
+// ─── Internal helpers (exported for testability) ────────────────────────
+
+function collectKnowledgeFiles(repoRoot) {
+  const files = [];
+  for (const dir of KNOWLEDGE_DIRS) {
+    const fullPath = path.join(repoRoot, dir);
+    if (!fs.existsSync(fullPath)) continue;
+    const stat = fs.statSync(fullPath);
+    if (stat.isFile()) {
+      files.push(fullPath);
+    } else if (stat.isDirectory()) {
+      walkDir(fullPath, files);
+    }
+  }
+  return files;
+}
+
+function walkDir(dir, out) {
+  for (const entry of fs.readdirSync(dir)) {
+    const ep = path.join(dir, entry);
+    const stat = fs.statSync(ep);
+    if (stat.isDirectory()) walkDir(ep, out);
+    else out.push(ep);
+  }
+}
+
+function snapshotUserSections(files) {
+  const map = new Map();
+  for (const f of files) {
+    try {
+      const content = fs.readFileSync(f, 'utf8');
+      const userSection = extractUserSections(content);
+      if (userSection.trim().length > 0) map.set(f, userSection);
+    } catch {}
+  }
+  return map;
+}
+
+/**
+ * Extract everything AFTER the closing ENTERPRISE-MANAGED marker.
+ * That's adopter-authored content that the framework should never touch.
+ *
+ * @param {string} content
+ * @returns {string}
+ */
+function extractUserSections(content) {
+  const endMatch = content.match(ENTERPRISE_MANAGED_END_RE);
+  if (!endMatch) return '';
+  const after = content.slice(endMatch.index + endMatch[0].length);
+  return after;
+}
+
+function mergeUserSection(current, userSection) {
+  const endMatch = current.match(ENTERPRISE_MANAGED_END_RE);
+  if (endMatch) {
+    // Replace whatever's after the END marker with the snapshotted user section
+    return current.slice(0, endMatch.index + endMatch[0].length) + userSection;
+  }
+  // No boundary in current; append the user section
+  return current.trimEnd() + '\n\n' + userSection.trimStart();
+}
+
+function createBackup({ repoRoot, backupDir, knowledgeFiles, now }) {
+  if (knowledgeFiles.length === 0) return null;
+
+  const fullBackupDir = path.join(repoRoot, backupDir);
+  fs.mkdirSync(fullBackupDir, { recursive: true });
+
+  // HC-005-B: append 4-char random suffix to prevent same-millisecond
+  // collision when concurrent `hone refresh-knowledge` runs land in the
+  // same backup dir.
+  const stamp = now().toISOString().replace(/[:.]/g, '-');
+  const suffix = crypto.randomBytes(2).toString('hex'); // 4 hex chars
+  const filename = `knowledge-${stamp}-${suffix}.tar.gz`;
+  const backupPath = path.join(fullBackupDir, filename);
+
+  // Build relative paths for tar
+  const relPaths = knowledgeFiles
+    .map(f => path.relative(repoRoot, f))
+    .filter(Boolean);
+
+  if (relPaths.length === 0) return null;
+
+  // Use system tar for portability
+  try {
+    execSync(`tar -czf "${backupPath}" ${relPaths.map(p => `"${p}"`).join(' ')}`, {
+      cwd: repoRoot,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    });
+  } catch (e) {
+    throw new Error(`tar failed: ${e.message}`);
+  }
+
+  return backupPath;
+}
+
+function restoreFromBackup({ repoRoot, backupPath }) {
+  execSync(`tar -xzf "${backupPath}"`, {
+    cwd: repoRoot,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function wrap(findings, backupPath, channelResults, restored, dryRun) {
+  const summary = {
+    total: findings.length,
+    errors: findings.filter(f => f.severity === 'ERROR').length,
+    warnings: findings.filter(f => f.severity === 'WARN').length,
+    info: findings.filter(f => f.severity === 'INFO').length,
+  };
+  const diffSummary = {
+    filesRestored: restored.length,
+  };
+  return {
+    findings,
+    summary,
+    backupPath,
+    channelResults,
+    diffSummary,
+    restored,
+    dryRun,
+  };
+}
+
+module.exports = {
+  refreshKnowledge,
+  defaultRunChannel,
+  extractUserSections,
+  mergeUserSection,
+  collectKnowledgeFiles,
+  KNOWLEDGE_DIRS,
+};

package/lib/rule-resolver.js

@@ -0,0 +1,146 @@
+'use strict';
+/**
+ * rule-resolver.js — H-090 single source of truth for "what rules are in
+ * effect in this repo?"
+ *
+ * Composition primitive for the editor-integrity helpers. Reads canonical
+ * rule files from `.hone/agents/<step>.agent.md` + adopter overlays from
+ * `.hone-local/rule-overlays/<step>.<rule>.md` and returns a unified view:
+ *
+ *   { canonical, overlays, merged }
+ *
+ * Three downstream consumers (per architect plan #117):
+ *   - cli/lib/pipeline-validate.js (H-091): asserts editor projections
+ *     match `merged` (not canonical alone) when overlays exist
+ *   - cli/lib/synthetic-pipeline.js (H-092): synthetic verifier uses
+ *     `merged` as the assertion baseline
+ *   - cli/hone-cli.js (future): debug surfacing for adopters
+ *
+ * Pure helper with injected I/O (same shape as platform-detect.js).
+ * Caller provides `fileExists` + `readFile`; helper handles the
+ * canonical/overlay loading + merge composition.
+ *
+ * IMPORTANT: This helper DELEGATES merge math to overlay-merge.js.
+ * It does NOT reimplement insert-mode logic. The architect's risk R2
+ * ("resolver re-implements merge semantics, drifts over time") is
+ * mitigated by always calling mergeOverlays() rather than building
+ * a parallel implementation.
+ *
+ * Closes architect plan #117 H-090.
+ */
+
+const { mergeOverlays } = require('./overlay-merge');
+
+const CANONICAL_AGENTS_DIR = '.hone/agents';
+const OVERLAYS_DIR = '.hone-local/rule-overlays';
+
+/**
+ * Resolve all rules in effect — canonical + overlays + merged.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot - absolute path to repo root
+ * @param {(relativePath: string) => boolean} opts.fileExists - filesystem check
+ * @param {(relativePath: string) => string|null} opts.readFile - file reader
+ * @param {string} [opts.step] - filter to one step name (e.g., 'code-reviewer')
+ * @param {string} [opts.rule] - filter to one rule_id within that step
+ * @returns {{
+ *   canonical: Array<{step, path, content}>,
+ *   overlays: Array<{step, ruleId, path, content}>,
+ *   merged: Array<{step, content, hasOverlay, overlayCount, errors}>
+ * }}
+ */
+function resolveRules(opts = {}) {
+  const { repoRoot, fileExists, readFile, step: stepFilter, rule: ruleFilter } = opts;
+
+  // Defensive: missing required I/O → empty result (non-throwing)
+  if (typeof fileExists !== 'function' || typeof readFile !== 'function') {
+    return {
+      canonical: [],
+      overlays: [],
+      merged: [],
+      _error: 'fileExists and readFile callbacks required',
+    };
+  }
+
+  // ─── 1. Canonical rule files in .hone/agents/<step>.agent.md ───
+  const canonical = [];
+  // We don't walk the directory here — caller's fileExists + readFile must
+  // be backed by something that can list. Instead, we look up by the
+  // standard step names. Caller can extend STANDARD_STEPS by passing a
+  // custom step filter.
+  const STANDARD_STEPS = [
+    'story-groomer', 'implementation-planner', 'unit-test-writer',
+    'e2e-qa-planner', 'e2e-test-spec-writer', 'code-builder', 'code-reviewer',
+  ];
+  const stepsToCheck = stepFilter ? [stepFilter] : STANDARD_STEPS;
+
+  for (const stepName of stepsToCheck) {
+    const path = `${CANONICAL_AGENTS_DIR}/${stepName}.agent.md`;
+    if (fileExists(path)) {
+      const content = readFile(path);
+      if (typeof content === 'string') {
+        canonical.push({ step: stepName, path, content });
+      }
+    }
+  }
+
+  // ─── 2. Adopter overlays in .hone-local/rule-overlays/<step>.<rule>.md ───
+  // We can't list a directory through fileExists/readFile alone. Caller may
+  // supply opts.overlayPaths if they've walked the dir; otherwise we attempt
+  // common overlay file names.
+  const overlays = [];
+  const overlayPaths = Array.isArray(opts.overlayPaths) ? opts.overlayPaths : [];
+  for (const overlayPath of overlayPaths) {
+    if (!overlayPath.startsWith(`${OVERLAYS_DIR}/`)) continue;
+    const fname = overlayPath.slice(OVERLAYS_DIR.length + 1);  // strip prefix
+    // Filename convention: `<step>.<rule_id>.md`
+    const m = fname.match(/^([a-z-]+)\.([A-Za-z0-9-]+)\.md$/);
+    if (!m) continue;
+    const [, step, ruleId] = m;
+    if (stepFilter && step !== stepFilter) continue;
+    if (ruleFilter && ruleId !== ruleFilter) continue;
+    if (fileExists(overlayPath)) {
+      const content = readFile(overlayPath);
+      if (typeof content === 'string') {
+        overlays.push({ step, ruleId, path: overlayPath, content });
+      }
+    }
+  }
+
+  // ─── 3. Merged view per step (canonical + overlays for that step) ───
+  const merged = [];
+  for (const c of canonical) {
+    const stepOverlays = overlays.filter((o) => o.step === c.step);
+    if (stepOverlays.length === 0) {
+      // No overlays — merged equals canonical byte-for-byte
+      merged.push({
+        step: c.step,
+        content: c.content,
+        hasOverlay: false,
+        overlayCount: 0,
+        errors: [],
+      });
+      continue;
+    }
+    // Delegate to overlay-merge.js for the actual merge math
+    const result = mergeOverlays(c.content, stepOverlays.map((o) => ({
+      path: o.path,
+      content: o.content,
+    })));
+    merged.push({
+      step: c.step,
+      content: result.merged,
+      hasOverlay: true,
+      overlayCount: stepOverlays.length,
+      errors: result.errors,
+    });
+  }
+
+  return { canonical, overlays, merged };
+}
+
+module.exports = {
+  CANONICAL_AGENTS_DIR,
+  OVERLAYS_DIR,
+  resolveRules,
+};