@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.25

package/scripts/lib/hooks.mjs

@@ -1,34 +1,5 @@
 /**
- * hooks.mjs — Drift-check hook registration logic for all surfaces.
- *
- * Supports: claude, codex, cursor, enact
- *
- * Per-surface registration details:
- *
- * CLAUDE:
- *   Writes to <claudeHome>/settings.json (creates/merges JSON).
- *   Adds a `hooks.SessionStart` array entry with a command that invokes the
- *   drift-check script via `node <abs path>`. Idempotent (keyed by a stable
- *   marker string in the command). This matches the Claude Code hook format:
- *   https://docs.anthropic.com/en/docs/claude-code/hooks
- *
- * CODEX / ENACT:
- *   Writes to <home>/config.toml.
- *   Adds a `[[hooks.session_start]]` entry. The codex-fork's exact TOML hook
- *   schema is approximated from the enact-agent config conventions. The entry
- *   is clearly namespaced (`[hooks]` / `[[hooks.session_start]]`) and is
- *   idempotent (guarded by a stable comment marker). If the exact schema is
- *   different in a given codex/enact build, the TOML entry is still safe to
- *   have present (unknown sections are ignored by most TOML parsers).
- *
- * CURSOR:
- *   Cursor uses a settings.json at <cursorHome>/settings.json, similar to
- *   Claude. Registration mirrors the claude approach (SessionStart hooks array).
- *   If Cursor's actual hook schema differs, the entry is still reversible and
- *   clearly marked.
- *
- * All registrations are IDEMPOTENT (safe to run twice) and REVERSIBLE
- * (--remove cleanly undoes them).
+ * hooks.mjs — plugin hook reconciliation and stale standalone drift-hook cleanup.
  */
 
 import {
@@ -38,15 +9,7 @@ import {
   writeFileSync,
 } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const REPO_ROOT = resolve(__dirname, "..", "..");
-
-// Absolute path to the drift-check hook script.
-const DRIFT_CHECK_SCRIPT = join(REPO_ROOT, "scripts", "hooks", "session-start-drift-check.mjs");
+import { dirname, join } from "node:path";
 
 // Stable marker used to detect an existing entry (idempotency key).
 const CLAUDE_HOOK_MARKER = "enact-extensions:session-start-drift-check";
@@ -70,30 +33,6 @@ function defaultHome(surface) {
 // Claude settings.json helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Build the SessionStart hook entry object for Claude's settings.json.
- * The command invokes node directly with the absolute hook script path.
- *
- * Claude Code hook format (from docs + live ~/.claude/settings.json):
- *   { matcher: ".*", hooks: [{ type: "command", command: "..." }] }
- *
- * The stable marker lives in the command string itself for idempotency
- * detection (see CLAUDE_HOOK_MARKER / "session-start-drift-check").
- *
- * @returns {object} Claude hook entry in the required shape.
- */
-function makeClaudeHookEntry() {
-  return {
-    matcher: ".*",
-    hooks: [
-      {
-        type: "command",
-        command: `node ${DRIFT_CHECK_SCRIPT}`,
-      },
-    ],
-  };
-}
-
 /**
  * Read and parse settings.json. Returns empty object on missing/error.
  */
@@ -114,37 +53,6 @@ function writeSettings(settingsPath, settings) {
   writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
 }
 
-/**
- * Register the drift-check hook in Claude's (or Cursor's) settings.json.
- * Idempotent: skips if marker already present.
- *
- * @param {string} settingsPath - Absolute path to settings.json
- * @returns {"registered"|"already_registered"} result
- */
-function registerClaudeHook(settingsPath) {
-  const settings = readSettings(settingsPath);
-  if (!settings.hooks) settings.hooks = {};
-  if (!Array.isArray(settings.hooks.SessionStart)) settings.hooks.SessionStart = [];
-
-  // Check if already registered (idempotency).
-  // Marker is the path substring "session-start-drift-check" in the nested command.
-  const entryMatchesDriftCheck = (e) =>
-    e &&
-    (
-      // New schema: { matcher, hooks: [{ type, command }] }
-      (Array.isArray(e.hooks) && e.hooks.some((h) => (h.command ?? "").includes("session-start-drift-check"))) ||
-      // Old schema (pre-fix): { _enact_marker, command } — tolerate during transition.
-      e._enact_marker === CLAUDE_HOOK_MARKER ||
-      (e.command ?? "").includes("session-start-drift-check")
-    );
-  const alreadyPresent = settings.hooks.SessionStart.some(entryMatchesDriftCheck);
-  if (alreadyPresent) return "already_registered";
-
-  settings.hooks.SessionStart.push(makeClaudeHookEntry());
-  writeSettings(settingsPath, settings);
-  return "registered";
-}
-
 /**
  * Remove the drift-check hook from Claude's (or Cursor's) settings.json.
  * Idempotent: safe if entry not present.
@@ -185,15 +93,9 @@ function removeClaudeHook(settingsPath) {
 // the entry is still safely parseable as TOML and clearly marked for removal.
 // ---------------------------------------------------------------------------
 
-const TOML_HOOK_BLOCK = (scriptPath) => `
-# [enact-extensions:session-start-drift-check] BEGIN — do not edit this line
-[[hooks.session_start]]
-command = "node ${scriptPath}"
-# [enact-extensions:session-start-drift-check] END
-`;
-
 const TOML_BEGIN_MARKER = `# [${TOML_HOOK_MARKER}] BEGIN`;
 const TOML_END_MARKER = `# [${TOML_HOOK_MARKER}] END`;
+const TOML_DRIFT_COMMAND_MARKER = "session-start-drift-check";
 
 function pluginMarker(pluginName) {
   return `enact-extensions:plugin-hooks:${pluginName}`;
@@ -281,17 +183,16 @@ function flattenHookCommands(hookConfig) {
 }
 
 function commandLooksPluginOwned(command) {
-  return /^enact-(?:operator|context)\s+hook\s+/.test(String(command));
+  return /^enact-context\s+hook\s+/.test(String(command));
 }
 
 /**
  * True when `command` is owned by the named plugin's runtime CLI, i.e. it
- * starts with `<pluginName> hook ` (the operator/context binaries invoke their
- * hooks as `enact-operator hook <x>` / `enact-context hook <x>`).
+ * starts with `<pluginName> hook `.
  *
  * Scoping removal to the SPECIFIC plugin avoids reconciling one plugin from
- * stripping a sibling plugin's marker-less entries. Falls back to the broad
- * operator|context match when no plugin name is given.
+ * stripping a sibling plugin's marker-less entries. Falls back to the known
+ * context hook command shape when no plugin name is given.
  */
 function commandOwnedByPlugin(command, pluginName) {
   if (!pluginName) return commandLooksPluginOwned(command);
@@ -413,7 +314,7 @@ function removeTomlPluginHooks(configPath, pluginName) {
 
   // Legacy cleanup: older codex installs could preserve the hook tables while
   // dropping the marker comments when config.toml was reserialized. Remove any
-  // remaining plain [[hooks.*]] blocks that still point at the operator runtime
+  // remaining plain [[hooks.*]] blocks that still point at this plugin's hook
   // command set.
   const lines = next.split(/\r?\n/);
   const out = [];
@@ -473,20 +374,46 @@ function writeToml(configPath, content) {
   writeFileSync(configPath, content, "utf8");
 }
 
-/**
- * Register the drift-check hook in a codex/enact config.toml.
- * Idempotent: checks for the BEGIN marker before appending.
- *
- * @param {string} configPath
- * @returns {"registered"|"already_registered"} result
- */
-function registerTomlHook(configPath) {
-  const existing = readToml(configPath);
-  if (existing.includes(TOML_BEGIN_MARKER)) return "already_registered";
+function stripTomlDriftHookBlocks(content) {
+  let next = content;
+  let removed = false;
 
-  const block = TOML_HOOK_BLOCK(DRIFT_CHECK_SCRIPT);
-  writeToml(configPath, existing + block);
-  return "registered";
+  const markedPattern = new RegExp(
+    `\\n?${TOML_BEGIN_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${TOML_END_MARKER.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[^\\n]*\\n?`,
+    "g",
+  );
+  next = next.replace(markedPattern, () => {
+    removed = true;
+    return "\n";
+  });
+
+  const lines = next.split(/\r?\n/);
+  const out = [];
+  for (let i = 0; i < lines.length;) {
+    const line = lines[i];
+    if (line.trim() === "[[hooks.session_start]]") {
+      const block = [line];
+      i += 1;
+      while (i < lines.length && !/^\s*\[/.test(lines[i])) {
+        block.push(lines[i]);
+        i += 1;
+      }
+      if (block.some((entry) => entry.includes(TOML_DRIFT_COMMAND_MARKER))) {
+        removed = true;
+        continue;
+      }
+      out.push(...block);
+      continue;
+    }
+    out.push(line);
+    i += 1;
+  }
+
+  next = out.join("\n").replace(/\n{3,}/g, "\n\n").replace(/^\n+/, "");
+  return {
+    content: next.endsWith("\n") || next.length === 0 ? next : `${next}\n`,
+    removed,
+  };
 }
 
 /**
@@ -498,101 +425,17 @@ function registerTomlHook(configPath) {
  */
 function removeTomlHook(configPath) {
   const existing = readToml(configPath);
-  if (!existing.includes(TOML_BEGIN_MARKER)) return "not_found";
+  const stripped = stripTomlDriftHookBlocks(existing);
+  if (!stripped.removed) return "not_found";
 
-  // Remove the marked block (BEGIN line through END line, inclusive).
-  const beginIdx = existing.indexOf(TOML_BEGIN_MARKER);
-  const endIdx = existing.indexOf(TOML_END_MARKER);
-  if (beginIdx === -1 || endIdx === -1) return "not_found";
-
-  // Include the newline before BEGIN and after END.
-  const beforeBegin = existing.slice(0, beginIdx).replace(/\n$/, "");
-  const afterEnd = existing.slice(endIdx + TOML_END_MARKER.length).replace(/^\n/, "");
-  const newContent = beforeBegin + (afterEnd ? "\n" + afterEnd : "");
-
-  writeToml(configPath, newContent);
+  writeToml(configPath, stripped.content);
   return "removed";
 }
 
 // ---------------------------------------------------------------------------
-// Public API: registerHook / removeHook for each surface
+// Public API: removeHook / registerPluginHooks / removePluginHooks
 // ---------------------------------------------------------------------------
 
-/**
- * Register the session-start drift-check hook for a given surface.
- *
- * @param {string} surface — "claude" | "codex" | "cursor" | "enact"
- * @param {object} [opts]
- * @param {string} [opts.claudeHome]
- * @param {string} [opts.codexHome]
- * @param {string} [opts.cursorHome]
- * @param {string} [opts.enactHome]
- * @param {boolean} [opts.local] — if true, use project-local home under cwd
- * @param {string} [opts.cwd] — cwd for --local resolution
- * @returns {{ surface: string, result: "registered"|"already_registered"|"skipped", note?: string }}
- */
-export function registerHook(surface, opts = {}) {
-  try {
-    switch (surface) {
-      case "claude": {
-        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
-        const settingsPath = join(home, "settings.json");
-        const result = registerClaudeHook(settingsPath);
-        return { surface, result, location: settingsPath };
-      }
-
-      case "cursor": {
-        // Cursor mirrors Claude's settings.json approach.
-        // NOTE: Cursor's actual hook schema may differ — this uses the same
-        // SessionStart format as Claude. Reverse with --remove if unwanted.
-        const home = opts.cursorHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".cursor") : defaultHome("cursor"));
-        const settingsPath = join(home, "settings.json");
-        const result = registerClaudeHook(settingsPath);
-        return {
-          surface,
-          result,
-          location: settingsPath,
-          note: "Assumption: Cursor uses settings.json SessionStart hooks (same as Claude Code). Verify if Cursor's actual hook schema differs.",
-        };
-      }
-
-      case "codex": {
-        const home = opts.codexHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".codex") : defaultHome("codex"));
-        const configPath = join(home, "config.toml");
-        const result = registerTomlHook(configPath);
-        return {
-          surface,
-          result,
-          location: configPath,
-          note: "Assumption: codex config.toml supports [[hooks.session_start]] with a command field.",
-        };
-      }
-
-      case "enact": {
-        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
-        const configPath = join(home, "config.toml");
-        const result = registerTomlHook(configPath);
-        return {
-          surface,
-          result,
-          location: configPath,
-          note: "Assumption: enact-agent config.toml supports [[hooks.session_start]] with a command field.",
-        };
-      }
-
-      default:
-        return { surface, result: "skipped", note: `Unknown surface: ${surface}` };
-    }
-  } catch (err) {
-    // Never crash — return skipped with the error note.
-    return {
-      surface,
-      result: "skipped",
-      note: `Error: ${err instanceof Error ? err.message : String(err)}`,
-    };
-  }
-}
-
 /**
  * Remove the session-start drift-check hook for a given surface.
  *
@@ -647,10 +490,11 @@ export function registerPluginHooks(surface, pluginName, hookConfig, opts = {})
   try {
     switch (surface) {
       case "claude": {
-        const home = opts.claudeHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".claude") : defaultHome("claude"));
-        const settingsPath = join(home, "settings.json");
-        const result = registerJsonPluginHooks(settingsPath, pluginName, hookConfig);
-        return { surface, result, location: settingsPath };
+        return {
+          surface,
+          result: "skipped",
+          note: "Claude reads plugin runtime hooks from the enabled plugin bundle. No settings.json plugin hook registration is performed.",
+        };
       }
 
       case "cursor": {
@@ -674,10 +518,11 @@ export function registerPluginHooks(surface, pluginName, hookConfig, opts = {})
       }
 
       case "enact": {
-        const home = opts.enactHome ?? (opts.local ? join(opts.cwd ?? process.cwd(), ".enact", "agent") : defaultHome("enact"));
-        const configPath = join(home, "config.toml");
-        const result = registerTomlPluginHooks(configPath, pluginName, hookConfig);
-        return { surface, result, location: configPath };
+        return {
+          surface,
+          result: "skipped",
+          note: "Enact follows the Codex-compatible bundle-owned plugin hook model. No config.toml plugin hook registration is performed.",
+        };
       }
 
       default:
@@ -738,4 +583,3 @@ export function removePluginHooks(surface, pluginName, opts = {}) {
 }
 
 // The 4 supported surfaces.
-export const SUPPORTED_SURFACES = ["claude", "codex", "cursor", "enact"];

package/scripts/lib/migrate-artifacts.mjs

@@ -0,0 +1,144 @@
+/**
+ * Idempotent migration for global factory/loop markdown artifacts to YYMMDDHH-<slug>.md.
+ */
+
+import { existsSync, readdirSync, renameSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const TIMESTAMPED_RE = /^(\d{8})-(.+\.md)$/;
+const ISO_DATE_RE = /^(20\d{2})-(\d{2})-(\d{2})-(.+)$/;
+
+export function timestampPrefixFromDate(date) {
+  const yy = String(date.getFullYear()).slice(2);
+  const mm = String(date.getMonth() + 1).padStart(2, "0");
+  const dd = String(date.getDate()).padStart(2, "0");
+  const hh = String(date.getHours()).padStart(2, "0");
+  return `${yy}${mm}${dd}${hh}`;
+}
+
+export function targetNameForLegacy(fileName, mtimeMs, fallbackHour = "00") {
+  if (TIMESTAMPED_RE.test(fileName)) return null;
+
+  const iso = ISO_DATE_RE.exec(fileName);
+  if (iso) {
+    const [, yyyy, mm, dd, rest] = iso;
+    return `${yyyy.slice(2)}${mm}${dd}${fallbackHour}-${rest}`;
+  }
+
+  const mtime = new Date(mtimeMs);
+  return `${timestampPrefixFromDate(mtime)}-${fileName}`;
+}
+
+/**
+ * @param {string} dir
+ * @param {{ dryRun?: boolean, fallbackHour?: string }} [opts]
+ */
+export function migrateMarkdownDir(dir, opts = {}) {
+  const dryRun = Boolean(opts.dryRun);
+  const fallbackHour = opts.fallbackHour ?? "00";
+  const renamed = [];
+  const skipped = [];
+  const fallbacks = [];
+
+  if (!existsSync(dir)) return { renamed, skipped, fallbacks };
+
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith(".md")) continue;
+    if (TIMESTAMPED_RE.test(name)) {
+      skipped.push(name);
+      continue;
+    }
+
+    const target = targetNameForLegacy(name, statSync(join(dir, name)).mtimeMs, fallbackHour);
+    if (!target || target === name) {
+      skipped.push(name);
+      continue;
+    }
+
+    const targetPath = join(dir, target);
+    if (existsSync(targetPath)) {
+      skipped.push(name);
+      continue;
+    }
+
+    if (ISO_DATE_RE.test(name)) {
+      fallbacks.push({ from: name, to: target, reason: "iso-date-hour-fallback" });
+    }
+
+    if (!dryRun) {
+      renameSync(join(dir, name), targetPath);
+    }
+    renamed.push({ from: name, to: target });
+  }
+
+  return { renamed, skipped, fallbacks };
+}
+
+/**
+ * @param {{ dryRun?: boolean, factoryRoot?: string, loopRoot?: string }} [opts]
+ */
+export function migrateGlobalArtifacts(opts = {}) {
+  const dryRun = Boolean(opts.dryRun);
+  const factoryRoot = opts.factoryRoot ?? join(homedir(), ".enact", "factory", "projects");
+  const loopRoot = opts.loopRoot ?? join(homedir(), ".enact", "loop", "projects");
+  const report = {
+    dryRun,
+    factory: [],
+    loop: [],
+    fallbacks: [],
+  };
+
+  if (existsSync(factoryRoot)) {
+    for (const project of readdirSync(factoryRoot, { withFileTypes: true })) {
+      if (!project.isDirectory()) continue;
+      const plansDir = join(factoryRoot, project.name, "plans");
+      const researchDir = join(factoryRoot, project.name, "research");
+      for (const dir of [plansDir, researchDir]) {
+        const result = migrateMarkdownDir(dir, { dryRun });
+        if (result.renamed.length || result.skipped.length) {
+          report.factory.push({ project: project.name, dir, ...result });
+        }
+        report.fallbacks.push(...result.fallbacks.map((f) => ({ ...f, project: project.name, dir })));
+      }
+    }
+  }
+
+  if (existsSync(loopRoot)) {
+    for (const project of readdirSync(loopRoot, { withFileTypes: true })) {
+      if (!project.isDirectory()) continue;
+      const stateDir = join(loopRoot, project.name, "state");
+      const legacy = join(stateDir, "summary.md");
+      if (!existsSync(legacy)) continue;
+
+      const hasTimestamped = readdirSync(stateDir).some((name) =>
+        /^\d{8}-loop-summary\.md$/.test(name),
+      );
+      if (hasTimestamped) {
+        report.loop.push({
+          project: project.name,
+          dir: stateDir,
+          renamed: [],
+          skipped: ["summary.md"],
+          fallbacks: [],
+        });
+        continue;
+      }
+
+      const mtime = statSync(legacy).mtimeMs;
+      const target = `${timestampPrefixFromDate(new Date(mtime))}-loop-summary.md`;
+      if (!dryRun) {
+        renameSync(legacy, join(stateDir, target));
+      }
+      report.loop.push({
+        project: project.name,
+        dir: stateDir,
+        renamed: [{ from: "summary.md", to: target }],
+        skipped: [],
+        fallbacks: [],
+      });
+    }
+  }
+
+  return report;
+}

package/scripts/lib/principles.mjs

@@ -0,0 +1,109 @@
+/**
+ * principles.mjs — Operating-principles block injection for host agent files.
+ *
+ * Surfaces: claude, codex, cursor, enact
+ * Writes managed blocks into CLAUDE.md / AGENTS.md (not settings.json).
+ */
+
+import {
+  applyBlock,
+  checkBlock,
+  removeBlock,
+  renderBlock,
+  resolveHostFile,
+  SUPPORTED_PRINCIPLES_SURFACES,
+} from "../../dist/index.js";
+
+export { SUPPORTED_PRINCIPLES_SURFACES };
+
+/**
+ * @param {string} surface
+ * @param {object} [opts]
+ * @returns {{ surface: string, path: string, result: string, action?: string }}
+ */
+export function setupPrinciples(surface, opts = {}) {
+  const hostFile = resolveHostFile(surface, opts);
+  const block = renderBlock(opts.doctrinePath);
+  const { action } = applyBlock(hostFile, block);
+  return {
+    surface,
+    path: hostFile,
+    result: action === "noop" ? "already_present" : "applied",
+    action,
+  };
+}
+
+/**
+ * @param {string} surface
+ * @param {object} [opts]
+ * @returns {{ surface: string, path: string, result: string }}
+ */
+export function removePrinciples(surface, opts = {}) {
+  const hostFile = resolveHostFile(surface, opts);
+  const { removed } = removeBlock(hostFile);
+  return {
+    surface,
+    path: hostFile,
+    result: removed ? "removed" : "not_found",
+  };
+}
+
+/**
+ * @param {string} surface
+ * @param {object} [opts]
+ * @returns {{ surface: string, path: string, status: string }}
+ */
+export function checkPrinciples(surface, opts = {}) {
+  const hostFile = resolveHostFile(surface, opts);
+  const block = renderBlock(opts.doctrinePath);
+  const status = checkBlock(hostFile, block);
+  return { surface, path: hostFile, status };
+}
+
+/**
+ * @param {string} surface
+ * @param {object} [opts]
+ * @returns {{ surface: string, path: string, status: string, action?: string, result?: string }}
+ */
+export function fixPrinciples(surface, opts = {}) {
+  const check = checkPrinciples(surface, opts);
+  if (check.status === "present") {
+    return { ...check, result: "already_present", action: "noop" };
+  }
+  const setup = setupPrinciples(surface, opts);
+  const after = checkPrinciples(surface, opts);
+  return {
+    surface,
+    path: setup.path,
+    status: after.status,
+    action: setup.action,
+    result: setup.result,
+  };
+}
+
+/**
+ * @param {string[]} surfaces
+ * @param {object} [opts]
+ * @param {boolean} [opts.fix]
+ * @returns {{ rows: object[], drift: boolean, exitCode: number }}
+ */
+export function runDoctor(surfaces, opts = {}) {
+  const rows = [];
+  let exitCode = 0;
+
+  for (const surface of surfaces) {
+    try {
+      const row = opts.fix ? fixPrinciples(surface, opts) : checkPrinciples(surface, opts);
+      rows.push(row);
+      if (row.status !== "present") {
+        exitCode = 1;
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      rows.push({ surface, path: "", status: "error", error: message });
+      exitCode = 1;
+    }
+  }
+
+  return { rows, drift: exitCode !== 0, exitCode };
+}

package/scripts/lib/provision-mcp.mjs

@@ -3,7 +3,7 @@
  *
  * The script-layer helpers remain for backwards compatibility with tests and
  * the CLI wrapper, but the source of truth now lives in src/provision.ts and is
- * exported from dist/index.js for in-process consumers like enact-operator.
+ * exported from dist/index.js for in-process consumers.
  */
 import {
   provisionMcp as provisionMcpCore,