moflo 4.9.11 → 4.9.13

package/dist/src/cli/services/hook-block-hash.js

@@ -0,0 +1,341 @@
+/**
+ * Settings.json hook-block drift detection (#881).
+ *
+ * Hashes the consumer's `.claude/settings.json` `hooks` block and the
+ * reference hook block that `generateHooksConfig()` would produce for the
+ * current moflo version.  When the hashes differ, the session-start launcher
+ * surfaces the diff (or, in `regenerate` mode, adds purely-additive missing
+ * hooks).  This is the broader complement to the per-bug `repairHookWiring`
+ * and `rewriteIncorrectHookWiring` rules — it catches drift in any direction,
+ * including future hook events we haven't shipped yet.
+ *
+ * IMPORTANT: This module must remain self-contained with ZERO imports from
+ * other moflo modules (mirrors the constraint on `services/hook-wiring.ts`).
+ * It is dynamically imported at runtime by `bin/session-start-launcher.mjs`
+ * in consumer projects, where transitive dependencies may not resolve.
+ *
+ * The reference hook block is duplicated from `init/settings-generator.ts`
+ * on purpose — the launcher cannot pull in `init/types.js` at runtime, and a
+ * unit test (`hook-block-hash.test.ts`) asserts the two stay in sync.
+ */
+import { createHash } from 'crypto';
+export const DRIFT_MODES = ['warn', 'regenerate', 'off'];
+// ────────────────────────────────────────────────────────────────────────────
+// Reference hook block — kept in sync with init/settings-generator.ts
+// ────────────────────────────────────────────────────────────────────────────
+const HELPERS_PREFIX = '$CLAUDE_PROJECT_DIR/.claude/helpers';
+const SCRIPTS_PREFIX = '$CLAUDE_PROJECT_DIR/.claude/scripts';
+/** Build a `node "<helper> <subcommand>"` hook entry. */
+const helperHook = (helper, sub, timeout) => ({
+    type: 'command',
+    command: `node "${HELPERS_PREFIX}/${helper}"${sub ? ` ${sub}` : ''}`,
+    timeout,
+});
+/** Build a `node "<scripts/file>"` hook entry (no subcommand). */
+const scriptHook = (file, timeout) => ({
+    type: 'command',
+    command: `node "${SCRIPTS_PREFIX}/${file}"`,
+    timeout,
+});
+const gateHook = (sub, timeout) => helperHook('gate-hook.mjs', sub, timeout);
+const gateCjs = (sub, timeout) => helperHook('gate.cjs', sub, timeout);
+const handler = (sub, timeout) => helperHook('hook-handler.cjs', sub, timeout);
+const autoMemory = (sub, timeout) => helperHook('auto-memory-hook.mjs', sub, timeout);
+/**
+ * Build the reference hook block — the canonical block `generateHooksConfig()`
+ * produces with all hook flags enabled (the default for `flo init`).
+ *
+ * If you change `generateHooksConfig()` in `init/settings-generator.ts`, also
+ * change this function — and the unit test `getReferenceHookBlock matches
+ * generateHooksConfig` will fail until the two agree.
+ */
+export function getReferenceHookBlock() {
+    return {
+        PreToolUse: [
+            { matcher: '^(Write|Edit|MultiEdit)$', hooks: [handler('post-edit', 5000)] },
+            { matcher: '^(Glob|Grep)$', hooks: [gateHook('check-before-scan', 3000)] },
+            { matcher: '^Read$', hooks: [gateHook('check-before-read', 3000)] },
+            {
+                matcher: '^Bash$',
+                hooks: [gateHook('check-dangerous-command', 2000), gateHook('check-before-pr', 2000)],
+            },
+        ],
+        PostToolUse: [
+            {
+                matcher: '^(Write|Edit|MultiEdit)$',
+                hooks: [handler('post-edit', 5000), gateHook('reset-edit-gates', 2000)],
+            },
+            { matcher: '^Agent$', hooks: [handler('post-task', 5000)] },
+            { matcher: '^TaskCreate$', hooks: [gateCjs('record-task-created', 2000)] },
+            {
+                matcher: '^Bash$',
+                hooks: [gateHook('check-bash-memory', 2000), gateHook('record-test-run', 2000)],
+            },
+            { matcher: '^Skill$', hooks: [gateHook('record-skill-run', 2000)] },
+            { matcher: 'mcp__moflo__memory_', hooks: [gateHook('record-memory-searched', 3000)] },
+            { matcher: '^TaskUpdate$', hooks: [gateCjs('check-task-transition', 2000)] },
+            { matcher: '^mcp__moflo__memory_store$', hooks: [gateCjs('record-learnings-stored', 2000)] },
+        ],
+        UserPromptSubmit: [
+            { hooks: [helperHook('prompt-hook.mjs', '', 3000)] },
+            { hooks: [gateHook('prompt-reminder', 3000)] },
+        ],
+        SubagentStart: [
+            { hooks: [helperHook('subagent-start.cjs', '', 2000)] },
+        ],
+        SessionStart: [
+            {
+                hooks: [scriptHook('session-start-launcher.mjs', 3000), autoMemory('import', 8000)],
+            },
+        ],
+        Stop: [
+            { hooks: [handler('session-end', 5000), autoMemory('sync', 10000)] },
+        ],
+        PreCompact: [
+            { hooks: [gateCjs('compact-guidance', 3000)] },
+        ],
+        Notification: [
+            { hooks: [handler('notification', 3000)] },
+        ],
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Normalisation + hashing
+// ────────────────────────────────────────────────────────────────────────────
+function normaliseHookEntry(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    if (typeof r.command !== 'string')
+        return null;
+    return {
+        type: typeof r.type === 'string' ? r.type : 'command',
+        command: r.command.replace(/\s+/g, ' ').trim(),
+        timeout: typeof r.timeout === 'number' && isFinite(r.timeout) ? r.timeout : 0,
+    };
+}
+function normaliseHookBlock(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const r = raw;
+    const hooksIn = Array.isArray(r.hooks) ? r.hooks : [];
+    const hooks = hooksIn.map(normaliseHookEntry).filter((h) => h !== null);
+    if (hooks.length === 0)
+        return null;
+    hooks.sort((a, b) => a.command.localeCompare(b.command));
+    const out = { hooks };
+    if (typeof r.matcher === 'string' && r.matcher.length > 0)
+        out.matcher = r.matcher;
+    return out;
+}
+/**
+ * Produce a stable, sorted view of a hook tree suitable for hashing or diffing.
+ * Drops unknown keys, coerces missing fields to defaults, and sorts events,
+ * matchers, and commands so semantically-equal trees compare equal.
+ */
+export function normaliseHooks(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    const events = raw;
+    const out = {};
+    const eventNames = Object.keys(events).sort();
+    for (const event of eventNames) {
+        const arr = events[event];
+        if (!Array.isArray(arr))
+            continue;
+        const blocks = arr
+            .map(normaliseHookBlock)
+            .filter((b) => b !== null);
+        if (blocks.length === 0)
+            continue;
+        blocks.sort((a, b) => {
+            const am = a.matcher ?? '';
+            const bm = b.matcher ?? '';
+            if (am !== bm)
+                return am.localeCompare(bm);
+            return (a.hooks[0]?.command ?? '').localeCompare(b.hooks[0]?.command ?? '');
+        });
+        out[event] = blocks;
+    }
+    return out;
+}
+function hashNormalised(tree) {
+    return createHash('sha256').update(JSON.stringify(tree)).digest('hex').slice(0, 16);
+}
+/**
+ * Hash a hook tree.  Stable across runs (deterministic normalisation), and
+ * insensitive to key order, whitespace inside commands, or matcher block
+ * grouping.  Returns a 16-char hex prefix of sha256 — long enough to make
+ * collisions a non-concern for the small space of valid hook trees while
+ * staying readable in launcher output.
+ */
+export function computeHookBlockHash(raw) {
+    return hashNormalised(normaliseHooks(raw));
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Diff
+// ────────────────────────────────────────────────────────────────────────────
+function entryKey(event, matcher, command) {
+    return `${event} ${matcher} ${command}`;
+}
+function flatten(tree) {
+    const out = new Map();
+    for (const event of Object.keys(tree)) {
+        for (const block of tree[event]) {
+            const matcher = block.matcher ?? '';
+            for (const hook of block.hooks) {
+                const entry = { event, matcher, command: hook.command };
+                out.set(entryKey(event, matcher, hook.command), entry);
+            }
+        }
+    }
+    return out;
+}
+let cachedReference = null;
+function getCachedReference() {
+    if (!cachedReference) {
+        const tree = getReferenceHookBlock();
+        const normalised = normaliseHooks(tree);
+        cachedReference = { tree, normalised, hash: hashNormalised(normalised), flat: flatten(normalised) };
+    }
+    return cachedReference;
+}
+/**
+ * Compare a consumer hook block against the reference and report what's
+ * missing / extra.  Pass an explicit `referenceHooks` to test against a
+ * frozen reference (used by tests); omit it to use the current moflo
+ * reference from `getReferenceHookBlock()` (memoised — built once per process).
+ */
+export function computeHookBlockDrift(consumerHooks, referenceHooks) {
+    const consumerNormalised = normaliseHooks(consumerHooks);
+    const consumerHash = hashNormalised(consumerNormalised);
+    const consumerFlat = flatten(consumerNormalised);
+    let referenceHash;
+    let referenceFlat;
+    if (referenceHooks === undefined) {
+        const ref = getCachedReference();
+        referenceHash = ref.hash;
+        referenceFlat = ref.flat;
+    }
+    else {
+        const refNormalised = normaliseHooks(referenceHooks);
+        referenceHash = hashNormalised(refNormalised);
+        referenceFlat = flatten(refNormalised);
+    }
+    const missing = [];
+    for (const [k, v] of referenceFlat) {
+        if (!consumerFlat.has(k))
+            missing.push(v);
+    }
+    const extra = [];
+    for (const [k, v] of consumerFlat) {
+        if (!referenceFlat.has(k))
+            extra.push(v);
+    }
+    return {
+        consumerHash,
+        referenceHash,
+        drifted: consumerHash !== referenceHash,
+        missing,
+        extra,
+    };
+}
+// ────────────────────────────────────────────────────────────────────────────
+// Settings.json helpers — shared between launcher + doctor
+// ────────────────────────────────────────────────────────────────────────────
+/**
+ * True when the user has set `claudeFlow.hooks.locked: true` in their
+ * settings.json — a sentinel that suppresses drift surfacing entirely.
+ */
+export function isHookBlockLocked(settings) {
+    const root = settings;
+    const cf = root?.claudeFlow;
+    const hooks = cf?.hooks;
+    return hooks?.locked === true;
+}
+/**
+ * Additively repair drift: for every entry in `report.missing`, locate the
+ * corresponding hook in the reference block and graft it into the consumer's
+ * settings.  Only safe when `report.extra.length === 0` — otherwise the
+ * caller should fall back to `warn` mode to avoid clobbering customisations.
+ *
+ * Mutates `settings` in place; caller is responsible for writing the file.
+ */
+export function applyAdditiveRegeneration(settings, report) {
+    if (report.missing.length === 0)
+        return { settings, added: 0, removed: 0 };
+    const ref = getCachedReference().tree;
+    const hooks = (settings.hooks ?? {});
+    let added = 0;
+    for (const miss of report.missing) {
+        const arr = Array.isArray(hooks[miss.event]) ? hooks[miss.event] : [];
+        let block = arr.find(b => (b?.matcher ?? '') === miss.matcher);
+        if (!block) {
+            block = { hooks: [] };
+            if (miss.matcher)
+                block.matcher = miss.matcher;
+            arr.push(block);
+        }
+        if (!Array.isArray(block.hooks))
+            block.hooks = [];
+        const refArr = ref[miss.event] ?? [];
+        const refBlock = refArr.find(b => (b?.matcher ?? '') === miss.matcher);
+        const refHook = refBlock?.hooks.find(h => h.command === miss.command);
+        if (refHook && !block.hooks.some(h => h?.command === miss.command)) {
+            block.hooks.push(refHook);
+            added++;
+        }
+        hooks[miss.event] = arr;
+    }
+    if (added > 0)
+        settings.hooks = hooks;
+    return { settings, added, removed: 0 };
+}
+/**
+ * Wholesale regeneration: replace `settings.hooks` with the canonical reference
+ * block. Drops extras (stale entries from previous moflo versions, e.g. the
+ * `gate.cjs session-reset` SessionStart hook removed in #842) AND adds missing
+ * entries — the additive variant only does the latter.
+ *
+ * The caller MUST check `isHookBlockLocked(settings)` first; if locked, the
+ * user has opted out and this function should not be called. Non-hooks fields
+ * on `settings` (permissions, env, claudeFlow.*, etc.) are preserved.
+ *
+ * Mutates `settings` in place; caller is responsible for writing the file.
+ */
+export function applyWholesaleRegeneration(settings, report) {
+    if (!report.drifted)
+        return { settings, added: 0, removed: 0 };
+    // Clone the cached reference so a later mutation of settings.hooks (by the
+    // launcher's settings.json migrations, doctor --fix, etc.) cannot corrupt
+    // the cached tree shared across `computeHookBlockDrift` calls in this process.
+    settings.hooks = structuredClone(getCachedReference().tree);
+    return { settings, added: report.missing.length, removed: report.extra.length };
+}
+/**
+ * Format a drift report for human-readable output (multi-line, no colour).
+ * Used by `flo doctor` and the session-start launcher's stdout summary.
+ */
+export function formatDriftReport(report) {
+    if (!report.drifted) {
+        return `hook block matches reference (${report.consumerHash})`;
+    }
+    const lines = [];
+    lines.push(`hook block drift detected (consumer ${report.consumerHash} vs reference ${report.referenceHash})`);
+    if (report.missing.length > 0) {
+        lines.push(`  ${report.missing.length} missing:`);
+        for (const m of report.missing) {
+            const m2 = m.matcher ? ` ${m.matcher}` : '';
+            lines.push(`    - ${m.event}${m2}: ${m.command}`);
+        }
+    }
+    if (report.extra.length > 0) {
+        lines.push(`  ${report.extra.length} extra (likely customisations):`);
+        for (const e of report.extra) {
+            const m2 = e.matcher ? ` ${e.matcher}` : '';
+            lines.push(`    + ${e.event}${m2}: ${e.command}`);
+        }
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=hook-block-hash.js.map

package/dist/src/cli/services/index.js

@@ -15,6 +15,8 @@ export { AgentRouter, getAgentRouter, routeTask, AGENT_CAPABILITIES, } from './a
 export { startDashboard, createDashboardMemoryAccessor, DEFAULT_DASHBOARD_PORT, } from './daemon-dashboard.js';
 // Hook Wiring (shared between doctor, upgrade, and session-start)
 export { repairHookWiring, HOOK_ENTRY_MAP, REQUIRED_HOOK_WIRING, } from './hook-wiring.js';
+// Hook Block Drift Detection (#881 — hash-based reconciliation)
+export { computeHookBlockHash, computeHookBlockDrift, formatDriftReport, getReferenceHookBlock, normaliseHooks, isHookBlockLocked, applyAdditiveRegeneration, DRIFT_MODES, } from './hook-block-hash.js';
 // Subagent Bootstrap Directive (single-source for SubagentStart + agent_spawn surfaces)
 export { SUBAGENT_BOOTSTRAP_DIRECTIVE } from './subagent-bootstrap.js';
 //# sourceMappingURL=index.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.9.11';
+export const VERSION = '4.9.13';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.9.11",
+  "version": "4.9.13",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -81,7 +81,7 @@
     "@typescript-eslint/eslint-plugin": "^7.18.0",
     "@typescript-eslint/parser": "^7.18.0",
     "eslint": "^8.0.0",
-    "moflo": "^4.9.10",
+    "moflo": "^4.9.12",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"