failproofai 0.0.14 → 0.0.15-beta.1

package/src/hooks/hooks-config.ts

@@ -4,10 +4,17 @@
 import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
-import type { HooksConfig } from "./policy-types";
+import type { HooksConfig, ConventionPolicyRecord } from "./policy-types";
 import type { HookScope } from "./types";
 import { hookLogInfo, hookLogWarn } from "./hook-logger";
 
+/** Normalize plural and legacy singular explicit policy paths for consumers. */
+export function configuredCustomPolicyPaths(
+  config: Pick<HooksConfig, "customPoliciesPaths" | "customPoliciesPath">,
+): string[] {
+  return config.customPoliciesPaths ?? (config.customPoliciesPath ? [config.customPoliciesPath] : []);
+}
+
 function readConfigAt(path: string): Partial<HooksConfig> {
   if (!existsSync(path)) return {};
   try {
@@ -55,7 +62,7 @@ export function findProjectConfigDir(start: string): string {
  * Merge rules:
  *   enabledPolicies: union + dedup across all three
  *   policyParams:    per-policy key, first scope that defines it wins entirely
- *   customPoliciesPath: first scope that defines it wins
+ *   customPoliciesPaths/customPoliciesPath: first scope defining either wins
  *   llm:            first scope that defines it wins
  */
 export function readMergedHooksConfig(cwd?: string): HooksConfig {
@@ -86,9 +93,26 @@ export function readMergedHooksConfig(cwd?: string): HooksConfig {
     }
   }
 
-  // customPoliciesPath: first scope wins
-  const customPoliciesPath =
-    project.customPoliciesPath ?? local.customPoliciesPath ?? global_.customPoliciesPath;
+  // Explicit custom policy paths: first scope defining either the current
+  // array form or the legacy singular form wins.
+  const customPoliciesPaths = [project, local, global_]
+    .map((scope) =>
+      scope.customPoliciesPaths !== undefined
+        ? scope.customPoliciesPaths
+        : scope.customPoliciesPath !== undefined
+          ? [scope.customPoliciesPath]
+          : undefined,
+    )
+    .find((paths) => paths !== undefined);
+
+  const disabledCustomPolicies = new Set<string>([
+    ...(project.disabledCustomPolicies ?? []),
+    ...(local.disabledCustomPolicies ?? []),
+    ...(global_.disabledCustomPolicies ?? []),
+  ]);
+
+  const customPoliciesEnabled =
+    project.customPoliciesEnabled ?? local.customPoliciesEnabled ?? global_.customPoliciesEnabled;
 
   // llm: first scope wins
   const llm = project.llm ?? local.llm ?? global_.llm;
@@ -96,7 +120,9 @@ export function readMergedHooksConfig(cwd?: string): HooksConfig {
   return {
     enabledPolicies: [...enabledSet],
     ...(Object.keys(mergedParams).length > 0 ? { policyParams: mergedParams } : {}),
-    ...(customPoliciesPath !== undefined ? { customPoliciesPath } : {}),
+    ...(customPoliciesPaths !== undefined ? { customPoliciesPaths } : {}),
+    ...(disabledCustomPolicies.size ? { disabledCustomPolicies: [...disabledCustomPolicies] } : {}),
+    ...(customPoliciesEnabled !== undefined ? { customPoliciesEnabled } : {}),
     ...(llm !== undefined ? { llm } : {}),
   };
 }
@@ -171,6 +197,64 @@ export function writeScopedHooksConfig(config: HooksConfig, scope: HookScope, cw
   writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n", "utf8");
 }
 
+/**
+ * Mirror the convention policies discovered at `scope` into that scope's
+ * config file, so `policies-config.json` shows what is installed rather than
+ * only what was explicitly enabled.
+ *
+ * Wholesale replace, not merge: the point is to reflect the directory as it is
+ * now, so a deleted file must vanish from the record. Writes only when the
+ * value actually changes, so repeated `failproofai policies` runs do not
+ * rewrite the file (and do not churn its mtime) for no reason.
+ *
+ * Callers must be one-shot commands. This is never safe to call from the hook
+ * path — see the `conventionPolicies` doc comment on `HooksConfig`.
+ *
+ * Returns true when the file was written.
+ */
+export function syncConventionPolicies(
+  entries: ConventionPolicyRecord[],
+  scope: HookScope,
+  cwd?: string,
+): boolean {
+  const configPath = getConfigPathForScope(scope, cwd);
+
+  // Never bring a config file into existence just to record an empty list —
+  // that would litter every directory the CLI is run from.
+  if (!existsSync(configPath) && entries.length === 0) return false;
+
+  // NEVER write over a file we could not parse. `readScopedHooksConfig` fails
+  // soft, returning `{enabledPolicies: []}` on a syntax error — correct for the
+  // hook path, which must not die because a config is malformed, but fatal
+  // here: writing that default back silently DESTROYS the user's real settings.
+  // A hand-edited file with one stray comma would lose every enabled policy the
+  // moment someone ran `failproofai policies`, a read-only command. Bail and
+  // leave the file exactly as it is; the parse warning already surfaced.
+  if (existsSync(configPath)) {
+    try {
+      JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+      hookLogWarn(
+        `not recording convention policies: ${configPath} is not valid JSON — ` +
+          `fix the syntax error and re-run. Nothing was written.`,
+      );
+      return false;
+    }
+  }
+
+  const config = readScopedHooksConfig(scope, cwd);
+  const sorted = [...entries].sort((a, b) => a.file.localeCompare(b.file));
+  const next: HooksConfig = { ...config };
+  if (sorted.length === 0) delete next.conventionPolicies;
+  else next.conventionPolicies = sorted;
+
+  if (JSON.stringify(next.conventionPolicies ?? null) === JSON.stringify(config.conventionPolicies ?? null)) {
+    return false;
+  }
+  writeScopedHooksConfig(next, scope, cwd);
+  return true;
+}
+
 export interface ResolvedLlmConfig {
   baseUrl: string;
   apiKey: string;

package/src/hooks/integrations.ts

@@ -12,8 +12,10 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { parseDocument, type Document } from "yaml";
+import { listHermesProfiles, hermesRoot } from "../../lib/hermes-profiles";
 import {
   HOOK_EVENT_TYPES,
+  CLAUDE_INSTALL_EVENT_TYPES,
   HOOK_SCOPES,
   CODEX_HOOK_EVENT_TYPES,
   CODEX_HOOK_SCOPES,
@@ -118,6 +120,18 @@ export interface Integration {
   /** Resolve the per-scope settings/hooks file path. */
   getSettingsPath(scope: HookScope, cwd?: string): string;
 
+  /**
+   * Every settings file this integration must write for a scope.
+   *
+   * Optional — defaults to `[getSettingsPath(scope, cwd)]`, which is right for
+   * every CLI whose scope maps to exactly one file. Hermes overrides it because
+   * each of its PROFILES is a separate home dir with its own `config.yaml`:
+   * writing only `~/.hermes/config.yaml` would leave every other profile running
+   * unhooked, silently. Use `settingsPathsFor(integration, …)` at call sites
+   * rather than calling this directly.
+   */
+  getSettingsPaths?(scope: HookScope, cwd?: string): string[];
+
   /** Read the raw settings/hooks file (returns {} when missing). */
   readSettings(settingsPath: string): Record<string, unknown>;
 
@@ -143,13 +157,28 @@ export interface Integration {
   detectInstalled(): boolean;
 }
 
+/**
+ * Every settings file to write/remove for `(integration, scope)`.
+ *
+ * Single-file integrations (all but Hermes) return exactly one path, so callers
+ * can loop unconditionally.
+ */
+export function settingsPathsFor(
+  integration: Integration,
+  scope: HookScope,
+  cwd?: string,
+): string[] {
+  const paths = integration.getSettingsPaths?.(scope, cwd);
+  return paths && paths.length > 0 ? paths : [integration.getSettingsPath(scope, cwd)];
+}
+
 // ── Claude Code integration ─────────────────────────────────────────────────
 
 export const claudeCode: Integration = {
   id: "claude",
   displayName: "Claude Code",
   scopes: HOOK_SCOPES,
-  eventTypes: HOOK_EVENT_TYPES,
+  eventTypes: CLAUDE_INSTALL_EVENT_TYPES,
 
   getSettingsPath(scope, cwd) {
     const base = cwd ? resolve(cwd) : process.cwd();
@@ -196,7 +225,48 @@ export const claudeCode: Integration = {
     const s = settings as ClaudeSettings;
     if (!s.hooks) s.hooks = {};
 
-    for (const eventType of HOOK_EVENT_TYPES) {
+    // Drop our hook from any event we no longer install. Without this, an
+    // event removed from the list stays in settings.json forever on existing
+    // machines — reinstalling would not repair it — which is exactly the
+    // situation `WorktreeCreate` created: registered, silent on allow, and
+    // therefore breaking `claude --worktree` until hand-edited. Only OUR
+    // marked entries are touched; anyone else's hooks on the same event stay.
+    //
+    // This walks EVERY key the file happens to carry, including ones
+    // failproofai has never written — a newer Claude event, another tool's
+    // entry, a typo. Their values are therefore unvalidated input, and a
+    // non-array one (`"Foo": {}` or `"Foo": "bar"`) makes the iteration below
+    // throw. That aborts the whole install AFTER the policies were recorded as
+    // enabled, so the user is left believing they are covered while no hook was
+    // written at all — the silent non-enforcement this file exists to prevent.
+    // Skip anything not shaped like a matcher list and leave it untouched.
+    const installed = new Set<string>(CLAUDE_INSTALL_EVENT_TYPES);
+    for (const eventType of Object.keys(s.hooks)) {
+      if (installed.has(eventType)) continue;
+      const matchers = s.hooks[eventType];
+      if (!Array.isArray(matchers)) continue;
+      // Drop a matcher group only when WE emptied it. A group we never touched
+      // (no `hooks` array, or one that held nothing of ours) is somebody else's
+      // and is written back exactly as found — pruning is for our own entries,
+      // not a cleanup pass over the user's file.
+      const kept: ClaudeHookMatcher[] = [];
+      for (const matcher of matchers as ClaudeHookMatcher[]) {
+        if (!matcher || !Array.isArray(matcher.hooks)) {
+          if (matcher) kept.push(matcher);
+          continue;
+        }
+        const before = matcher.hooks.length;
+        matcher.hooks = matcher.hooks.filter(
+          (h) => !isMarkedHook(h as Record<string, unknown>),
+        );
+        const weEmptiedIt = matcher.hooks.length === 0 && before > 0;
+        if (!weEmptiedIt) kept.push(matcher);
+      }
+      s.hooks[eventType] = kept;
+      if (kept.length === 0) delete s.hooks[eventType];
+    }
+
+    for (const eventType of CLAUDE_INSTALL_EVENT_TYPES) {
       const hookEntry = this.buildHookEntry(binaryPath, eventType, scope) as unknown as ClaudeHookEntry;
       if (!s.hooks[eventType]) s.hooks[eventType] = [];
       const matchers: ClaudeHookMatcher[] = s.hooks[eventType];
@@ -1315,10 +1385,19 @@ export const hermes: Integration = {
   scopes: HERMES_HOOK_SCOPES,
   eventTypes: HERMES_HOOK_EVENT_TYPES,
 
-  // Hermes config is USER-scope only (`~/.hermes/config.yaml`); there is no
-  // project/local file, so scope/cwd are irrelevant here.
+  // Hermes config is USER-scope only (`<HERMES_HOME>/config.yaml`); there is no
+  // project/local file, so scope/cwd are irrelevant here. This is the DEFAULT
+  // profile's config — see getSettingsPaths for the rest.
   getSettingsPath() {
-    return resolve(homedir(), ".hermes", "config.yaml");
+    return resolve(hermesRoot(), "config.yaml");
+  },
+
+  // Every profile is a separate Hermes home with its own config.yaml, so a
+  // single-file install would leave non-default profiles running unhooked —
+  // silently, since Hermes never reports a missing hook. Install/uninstall
+  // therefore cover them all.
+  getSettingsPaths() {
+    return listHermesProfiles().map((p) => resolve(p.home, "config.yaml"));
   },
 
   readSettings(settingsPath) {
@@ -1403,21 +1482,13 @@ export const hermes: Integration = {
     return removed;
   },
 
+  // "Installed" means EVERY profile is hooked, not just some. A profile created
+  // after install has no hooks, and reporting green there would hide exactly the
+  // silent-unenforcement gap this integration exists to close; reporting "not
+  // installed" instead prompts a re-install, which writes the missing profiles.
   hooksInstalledInSettings(scope, cwd) {
-    const settingsPath = this.getSettingsPath(scope, cwd);
-    if (!existsSync(settingsPath)) return false;
-    try {
-      const doc = readYamlDoc(settingsPath);
-      const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
-      const hooks = js.hooks;
-      if (!hooks || typeof hooks !== "object") return false;
-      for (const entries of Object.values(hooks)) {
-        if (Array.isArray(entries) && entries.some((h) => isMarkedHook(h))) return true;
-      }
-    } catch {
-      // Corrupt config — treat as not installed.
-    }
-    return false;
+    const paths = settingsPathsFor(this, scope, cwd);
+    return paths.length > 0 && paths.every((p) => hermesConfigHasHooks(p));
   },
 
   detectInstalled() {
@@ -1425,6 +1496,39 @@ export const hermes: Integration = {
   },
 };
 
+function hermesConfigHasHooks(settingsPath: string): boolean {
+  if (!existsSync(settingsPath)) return false;
+  try {
+    const doc = readYamlDoc(settingsPath);
+    const js = (doc.toJS() ?? {}) as { hooks?: Record<string, HermesHookEntry[]> };
+    const hooks = js.hooks;
+    if (!hooks || typeof hooks !== "object") return false;
+    for (const entries of Object.values(hooks)) {
+      if (Array.isArray(entries) && entries.some((h) => isMarkedHook(h))) return true;
+    }
+  } catch {
+    // Corrupt config — treat as not installed.
+  }
+  return false;
+}
+
+/**
+ * Profiles that exist but have no failproofai hooks — i.e. Hermes instances
+ * currently running unenforced. Empty when Hermes isn't installed at all.
+ *
+ * `listHermesProfiles()` always seeds a `default` entry so install has a path to
+ * write even on a fresh machine, so this filters to homes that actually exist —
+ * otherwise every machine WITHOUT Hermes would report one unhooked profile and
+ * the wizard would replace its accurate "not on PATH" hint with a phantom
+ * warning.
+ */
+export function unhookedHermesProfiles(): string[] {
+  return listHermesProfiles()
+    .filter((p) => existsSync(p.home))
+    .filter((p) => !hermesConfigHasHooks(resolve(p.home, "config.yaml")))
+    .map((p) => p.name);
+}
+
 // ── OpenClaw integration ────────────────────────────────────────────────────
 //
 // OpenClaw is a self-hosted assistant gateway. Enforcement is via its in-process