@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.24

package/scripts/enact-extensions.mjs

@@ -11,8 +11,15 @@ import { runPrune } from "./lib/run-prune.mjs";
 import { runUninstall } from "./lib/run-uninstall.mjs";
 import { readLedger } from "./lib/ledger.mjs";
 import { computeOutdated } from "./lib/outdated.mjs";
+import { migrateGlobalArtifacts } from "./lib/migrate-artifacts.mjs";
 import { startServer, resolveServePort } from "./lib/serve.mjs";
-import { registerHook, removeHook, SUPPORTED_SURFACES } from "./lib/hooks.mjs";
+import {
+  setupPrinciples,
+  removePrinciples,
+  checkPrinciples,
+  runDoctor,
+  SUPPORTED_PRINCIPLES_SURFACES,
+} from "./lib/principles.mjs";
 import { dirname, join, resolve } from "node:path";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
@@ -36,6 +43,8 @@ Usage:
   enact-extensions log --json             Emit the raw ledger array as JSON
   enact-extensions outdated               Report freshness drift: installed vs canonical source (per plugin+surface)
   enact-extensions outdated --json        Emit JSON array [{name, platform, scope, home, status, installedHash, currentHash, version}]
+  enact-extensions migrate-artifacts [--dry-run] [--json]
+                                          Rename legacy factory/loop markdown artifacts to YYMMDDHH-<slug>.md
   enact-extensions update <name>          Refresh an outdated plugin on every surface it is installed on (ledger-driven)
   enact-extensions update --all           Refresh EVERY outdated plugin/surface
   enact-extensions update <name> --dry-run  Show what would be refreshed; change nothing
@@ -68,17 +77,14 @@ Usage:
   enact-extensions uninstall [path|name] --platform all      Uninstall from every plugin platform
   enact-extensions uninstall [path|name] --platform claude,cursor   Uninstall from a subset of platforms
   enact-extensions serve [--port N] [--prod] [--host 127.0.0.1] [--open]  Start the localhost management UI + API (dev 43217 / prod 53217)
-  enact-extensions hooks [setup] [--surfaces <list>|--all] [--remove] [--local]
-                                          Register (or remove) the session-start drift-check hook
-                                          for each named surface (claude, codex, cursor, enact).
-
-Hooks command:
-  enact-extensions hooks setup --surfaces claude,codex   Register the drift hook for Claude and Codex
-  enact-extensions hooks setup --all                     Register for all surfaces (claude, codex, cursor, enact)
-  enact-extensions hooks setup --surfaces claude --remove  Remove the drift hook from Claude
-  enact-extensions hooks setup --all --remove            Remove the drift hook from all surfaces
-  enact-extensions hooks setup --surfaces claude --local  Register using project-local home (under cwd)
-  enact-extensions hooks setup                           Interactive surface picker (TTY only)
+  enact-extensions principles setup [--surfaces <list>|--all] [--remove] [--local]
+                                          Inject (or remove) the enact-core operating-principles block
+                                          into host agent files (CLAUDE.md / AGENTS.md).
+  enact-extensions principles check [--surfaces <list>|--all] [--local] [--json]
+                                          Report principles block drift per surface (present/missing/stale).
+                                          Use principles setup or doctor --fix to remediate. Not npm run check:principles.
+  enact-extensions doctor [--fix] [--surfaces <list>|--all] [--local] [--json]
+                                          Check operating-principles block drift per surface; --fix applies blocks.
   enact-extensions -v | --version                        Print version and exit
 
 Options:
@@ -198,6 +204,8 @@ function parseArgs(argv) {
       options.surfaces = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
     } else if (arg === "--remove") {
       options.remove = true;
+    } else if (arg === "--fix") {
+      options.fix = true;
     } else if (arg === "-h" || arg === "--help") {
       positional.push("help");
     } else if (!arg.startsWith("-")) {
@@ -227,83 +235,81 @@ if (!command || command === "help") {
 // Surfaces: claude, codex, cursor, enact
 // Registration is idempotent and reversible.
 // ---------------------------------------------------------------------------
-if (command === "hooks") {
-  // Sub-command: `hooks setup` or just `hooks` (treat bare `hooks` as `hooks setup`).
-  // path is positional[1] — could be "setup" or undefined.
+// ---------------------------------------------------------------------------
+// `principles` command — inject or check operating-principles blocks in host files.
+//
+// Surfaces: claude, codex, cursor, enact
+// ---------------------------------------------------------------------------
+if (command === "principles") {
   const subCommand = path ?? "setup";
 
-  if (subCommand !== "setup") {
-    process.stderr.write(`[enact-extensions hooks] Unknown sub-command: ${subCommand}. Did you mean 'setup'?\n`);
+  if (subCommand !== "setup" && subCommand !== "check") {
+    process.stderr.write(
+      `[enact-extensions principles] Unknown sub-command: ${subCommand}. Use 'setup' or 'check'.\n`,
+    );
     process.exit(1);
   }
 
   const isRemove = options.remove ?? false;
   const isLocal = options.scope === "local";
   const cwd = processCwd();
+  const surfacesList = SUPPORTED_PRINCIPLES_SURFACES;
 
-  // Determine which surfaces to act on.
   let surfaces = [];
   if (options.all) {
-    surfaces = [...SUPPORTED_SURFACES];
+    surfaces = [...surfacesList];
   } else if (options.surfaces && options.surfaces.length > 0) {
-    // Validate provided surface names.
-    const invalid = options.surfaces.filter((s) => !SUPPORTED_SURFACES.includes(s));
+    const invalid = options.surfaces.filter((s) => !surfacesList.includes(s));
     if (invalid.length > 0) {
-      process.stderr.write(`[enact-extensions hooks] Unknown surface(s): ${invalid.join(", ")}. Valid: ${SUPPORTED_SURFACES.join(", ")}\n`);
+      process.stderr.write(
+        `[enact-extensions principles] Unknown surface(s): ${invalid.join(", ")}. Valid: ${surfacesList.join(", ")}\n`,
+      );
       process.exit(1);
     }
     surfaces = options.surfaces;
-  } else {
-    // No surfaces specified — check if TTY for interactive picker.
-    if (process.stdin.isTTY) {
-      // Interactive picker via node:readline.
-      const { createInterface } = await import("node:readline");
-      const rl = createInterface({ input: process.stdin, output: process.stdout });
+  } else if (subCommand === "setup" && process.stdin.isTTY) {
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const question = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
 
-      const question = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+    process.stdout.write(`\nenact-extensions principles setup — interactive surface picker\n`);
+    process.stdout.write(`Available surfaces: ${surfacesList.map((s, i) => `${i + 1}. ${s}`).join(", ")}\n`);
+    process.stdout.write(`Enter surface names or numbers (comma-separated), or 'all':\n`);
 
-      process.stdout.write(`\nenact-extensions hooks setup — interactive surface picker\n`);
-      process.stdout.write(`Available surfaces: ${SUPPORTED_SURFACES.map((s, i) => `${i + 1}. ${s}`).join(", ")}\n`);
-      process.stdout.write(`Enter surface names or numbers (comma-separated), or 'all':\n`);
+    const answer = await question("> ");
+    rl.close();
 
-      const answer = await question("> ");
-      rl.close();
+    if (answer.trim().toLowerCase() === "all") {
+      surfaces = [...surfacesList];
+    } else {
+      surfaces = answer
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => {
+          const idx = parseInt(s, 10);
+          if (!isNaN(idx) && idx >= 1 && idx <= surfacesList.length) {
+            return surfacesList[idx - 1];
+          }
+          return s.toLowerCase();
+        })
+        .filter((s) => surfacesList.includes(s));
 
-      if (answer.trim().toLowerCase() === "all") {
-        surfaces = [...SUPPORTED_SURFACES];
-      } else {
-        surfaces = answer
-          .split(",")
-          .map((s) => s.trim())
-          .filter(Boolean)
-          .map((s) => {
-            // Allow numeric selection.
-            const idx = parseInt(s, 10);
-            if (!isNaN(idx) && idx >= 1 && idx <= SUPPORTED_SURFACES.length) {
-              return SUPPORTED_SURFACES[idx - 1];
-            }
-            return s.toLowerCase();
-          })
-          .filter((s) => SUPPORTED_SURFACES.includes(s));
-
-        if (surfaces.length === 0) {
-          process.stderr.write(`[enact-extensions hooks] No valid surfaces selected. Exiting.\n`);
-          process.exit(0);
-        }
+      if (surfaces.length === 0) {
+        process.stderr.write(`[enact-extensions principles] No valid surfaces selected. Exiting.\n`);
+        process.exit(0);
       }
-    } else {
-      // Non-TTY, no surface flags → print notice and exit 0.
-      process.stdout.write(
-        `[enact-extensions hooks] No surface specified. Run with --surfaces or --all:\n` +
-        `  enact-extensions hooks setup --surfaces claude,codex\n` +
-        `  enact-extensions hooks setup --all\n`,
-      );
-      process.exit(0);
     }
+  } else {
+    process.stdout.write(
+      `[enact-extensions principles] No surface specified. Run with --surfaces or --all:\n` +
+      `  enact-extensions principles ${subCommand} --surfaces claude,codex\n` +
+      `  enact-extensions principles ${subCommand} --all\n`,
+    );
+    process.exit(0);
   }
 
-  // Execute registration or removal for each surface.
-  const hookOpts = {
+  const principleOpts = {
     claudeHome: options.claudeHome,
     codexHome: options.codexHome,
     cursorHome: options.cursorHome,
@@ -312,37 +318,126 @@ if (command === "hooks") {
     cwd,
   };
 
+  let exitCode = 0;
+
+  if (subCommand === "check") {
+    const rows = [];
+    for (const surface of surfaces) {
+      try {
+        const res = checkPrinciples(surface, principleOpts);
+        rows.push(res);
+        if (!options.json) {
+          process.stdout.write(
+            `  [principles] ${surface}: ${res.status} → ${res.path}\n`,
+          );
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        rows.push({ surface, path: "", status: "error", error: message });
+        process.stderr.write(`  [principles] ${surface}: error — ${message}\n`);
+      }
+    }
+
+    if (options.json) {
+      console.log(JSON.stringify(rows, null, 2));
+    }
+
+    process.exit(0);
+  }
+
   for (const surface of surfaces) {
-    let res;
-    if (isRemove) {
-      res = removeHook(surface, hookOpts);
-    } else {
-      res = registerHook(surface, hookOpts);
+    try {
+      const res = isRemove
+        ? removePrinciples(surface, principleOpts)
+        : setupPrinciples(surface, principleOpts);
+
+      if (res.result === "applied") {
+        process.stdout.write(
+          `  [principles] ${surface}: applied (${res.action}) → ${res.path}\n`,
+        );
+      } else if (res.result === "already_present") {
+        process.stdout.write(
+          `  [principles] ${surface}: already present (noop) → ${res.path}\n`,
+        );
+      } else if (res.result === "removed") {
+        process.stdout.write(`  [principles] ${surface}: removed → ${res.path}\n`);
+      } else if (res.result === "not_found") {
+        process.stdout.write(
+          `  [principles] ${surface}: not found (nothing to remove) → ${res.path}\n`,
+        );
+      }
+    } catch (err) {
+      exitCode = 1;
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`  [principles] ${surface}: error — ${message}\n`);
     }
+  }
 
-    // Print per-surface result.
-    const status = res.result;
-    const location = res.location ? ` → ${res.location}` : "";
-    const note = res.note ? ` (${res.note})` : "";
-
-    if (status === "registered") {
-      process.stdout.write(`  [hooks] ${surface}: registered${location}\n`);
-    } else if (status === "already_registered") {
-      process.stdout.write(`  [hooks] ${surface}: already registered (skipped)${location}\n`);
-    } else if (status === "removed") {
-      process.stdout.write(`  [hooks] ${surface}: removed${location}\n`);
-    } else if (status === "not_found") {
-      process.stdout.write(`  [hooks] ${surface}: not found (nothing to remove)${location}\n`);
-    } else {
-      process.stdout.write(`  [hooks] ${surface}: skipped${note}\n`);
+  process.exit(exitCode);
+}
+
+// ---------------------------------------------------------------------------
+// `doctor` command — check (and optionally fix) operating-principles drift.
+//
+// Surfaces: claude, codex, cursor, enact (defaults to all when omitted)
+// ---------------------------------------------------------------------------
+if (command === "doctor") {
+  const isFix = options.fix ?? false;
+  const isLocal = options.scope === "local";
+  const cwd = processCwd();
+  const surfacesList = SUPPORTED_PRINCIPLES_SURFACES;
+
+  let surfaces = [];
+  if (options.all || !options.surfaces || options.surfaces.length === 0) {
+    surfaces = [...surfacesList];
+  } else {
+    const invalid = options.surfaces.filter((s) => !surfacesList.includes(s));
+    if (invalid.length > 0) {
+      process.stderr.write(
+        `[enact-extensions doctor] Unknown surface(s): ${invalid.join(", ")}. Valid: ${surfacesList.join(", ")}\n`,
+      );
+      process.exit(1);
     }
+    surfaces = options.surfaces;
+  }
+
+  const principleOpts = {
+    claudeHome: options.claudeHome,
+    codexHome: options.codexHome,
+    cursorHome: options.cursorHome,
+    enactHome: options.enactHome,
+    local: isLocal,
+    cwd,
+    fix: isFix,
+  };
+
+  const { rows, exitCode } = runDoctor(surfaces, principleOpts);
 
-    if (res.note && status !== "skipped") {
-      process.stderr.write(`  [hooks] ${surface} note: ${res.note}\n`);
+  if (!options.json) {
+    for (const row of rows) {
+      if (row.error) {
+        process.stderr.write(`  [doctor] ${row.surface}: error — ${row.error}\n`);
+        continue;
+      }
+      if (isFix) {
+        const note = row.result === "already_present"
+          ? "already present (noop)"
+          : `fixed (${row.action ?? row.result})`;
+        process.stdout.write(`  [doctor] ${row.surface}: ${row.status} — ${note} → ${row.path}\n`);
+      } else {
+        process.stdout.write(`  [doctor] ${row.surface}: ${row.status} → ${row.path}\n`);
+      }
     }
+    if (!isFix && exitCode !== 0) {
+      process.stderr.write(
+        `[enact-extensions doctor] Drift detected. Fix with: enact-extensions doctor --fix --all\n`,
+      );
+    }
+  } else {
+    console.log(JSON.stringify(rows, null, 2));
   }
 
-  process.exit(0);
+  process.exit(exitCode);
 }
 
 // ---------------------------------------------------------------------------
@@ -615,6 +710,39 @@ if (command === "outdated") {
 }
 
 // ---------------------------------------------------------------------------
+// `migrate-artifacts` command — rename legacy global markdown artifacts.
+if (command === "migrate-artifacts") {
+  try {
+    const report = migrateGlobalArtifacts({ dryRun: Boolean(options.dryRun) });
+    if (options.json) {
+      process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    } else {
+      const factoryRenamed = report.factory.flatMap((entry) => entry.renamed);
+      const loopRenamed = report.loop.flatMap((entry) => entry.renamed);
+      if (factoryRenamed.length === 0 && loopRenamed.length === 0) {
+        process.stdout.write("✓ no legacy markdown artifacts to migrate\n");
+      }
+      for (const { from, to } of factoryRenamed) {
+        process.stdout.write(`✓ factory ${from} → ${to}\n`);
+      }
+      for (const { from, to } of loopRenamed) {
+        process.stdout.write(`✓ loop ${from} → ${to}\n`);
+      }
+      if (report.fallbacks.length > 0) {
+        process.stderr.write(
+          `· ${report.fallbacks.length} ISO-date rename(s) used hour fallback — see --json for details\n`,
+        );
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(
+      `[enact-extensions migrate-artifacts] Error: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    process.exit(1);
+  }
+}
+
 // `update` command — refresh outdated installed plugins, driven by the ledger.
 //
 // Re-installs each OUTDATED (plugin, surface, home) to the EXACT surface + home
@@ -803,6 +931,9 @@ if (command === "serve") {
 // `hook` command — execute a hook handler by name, reading JSON from stdin.
 //
 // Currently supported sub-commands:
+//   enact-extensions hook session-start
+//     Runs the advisory drift-check and prints a single line only when plugin
+//     surfaces are outdated.
 //   enact-extensions hook user-prompt-submit
 //     Reads a UserPromptSubmit hook payload from stdin, extracts the prompt,
 //     builds the skill catalog from the bundled extensions dir, routes the
@@ -816,10 +947,10 @@ if (command === "serve") {
 if (command === "hook") {
   const subCommand = path; // positional[1]
 
-  if (subCommand !== "user-prompt-submit") {
+  if (subCommand !== "user-prompt-submit" && subCommand !== "session-start") {
     process.stderr.write(
       `[enact-extensions hook] Unknown sub-command: ${subCommand ?? "(none)"}. ` +
-      `Supported: user-prompt-submit\n`,
+      `Supported: session-start, user-prompt-submit\n`,
     );
     process.stdout.write(JSON.stringify({ continue: true }) + "\n");
     process.exit(0);
@@ -827,6 +958,22 @@ if (command === "hook") {
 
   // Async IIFE: stdin reading and dynamic import require async context.
   (async () => {
+    if (subCommand === "session-start") {
+      try {
+        const { computeOutdated } = await import("./lib/outdated.mjs");
+        const outdated = (computeOutdated() ?? []).filter((entry) => entry?.status === "outdated");
+        if (outdated.length > 0) {
+          const pairs = outdated.map((entry) => `${entry.name}/${entry.platform}`).join(", ");
+          process.stdout.write(
+            `[enact-extensions] ${outdated.length} plugin surface${outdated.length === 1 ? "" : "s"} outdated: ${pairs}. Run: enact-extensions update --all\n`,
+          );
+        }
+      } catch {
+        // Fail-silent for session-start hooks.
+      }
+      process.exit(0);
+    }
+
     // Read stdin to get the hook payload JSON.
     let payload;
     try {