@michelj/context-guard 0.4.2 → 0.4.4

package/bin/context-guard-skill.js

@@ -7,22 +7,32 @@ const path = require("path");
 const { spawnSync } = require("child_process");
 
 const packageRoot = path.resolve(__dirname, "..");
-const sourceSkillDir = path.join(packageRoot, "skills", "context-guard");
+const sourceSkillDir = packageRoot;
 const sourceHooksPath = path.join(packageRoot, "hooks.json");
 const pythonScript = path.join(sourceSkillDir, "scripts", "context_guard.py");
+const skillInstallEntries = [
+  "SKILL.md",
+  "README.md",
+  "README.zh-CN.md",
+  "agents",
+  "prototype",
+  "references",
+  "scripts"
+];
 
 function usage() {
   console.log(`Context Guard Skill
 
 Usage:
-  context-guard install [--target <dir>] [--with-hooks] [--hooks-target <file>]
+  context-guard install [--platform auto|all|codex|cursor|claude] [--no-hooks]
+                        [--target <dir>] [--hooks-target <file>] [--config-target <file>]
   context-guard path
   context-guard <context_guard.py command> [args...]
 
 Examples:
   npx @michelj/context-guard install
-  npx @michelj/context-guard install --with-hooks
-  npx @michelj/context-guard show-roadmap --root /path/to/project
+  npx @michelj/context-guard install --platform all
+  npx @michelj/context-guard init --root /path/to/project
 `);
 }
 
@@ -38,27 +48,54 @@ function expandHome(inputPath) {
   return inputPath;
 }
 
-function defaultSkillTarget() {
-  if (process.env.CONTEXT_GUARD_SKILL_TARGET) {
-    return path.resolve(expandHome(process.env.CONTEXT_GUARD_SKILL_TARGET));
-  }
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  return path.join(codexHome, "skills", "context-guard");
+const PLATFORM_SPECS = {
+  codex: { env: "CODEX_HOME", folder: ".codex", hooksFile: "hooks.json", configFile: "config.toml" },
+  cursor: { env: "CURSOR_HOME", folder: ".cursor", hooksFile: "hooks.json" },
+  claude: { env: "CLAUDE_HOME", folder: ".claude", hooksFile: "settings.json" }
+};
+
+function platformHome(platform) {
+  const spec = PLATFORM_SPECS[platform];
+  return path.resolve(expandHome(process.env[spec.env] || path.join(os.homedir(), spec.folder)));
 }
 
-function defaultHooksTarget() {
-  if (process.env.CONTEXT_GUARD_HOOKS_TARGET) {
-    return path.resolve(expandHome(process.env.CONTEXT_GUARD_HOOKS_TARGET));
-  }
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  return path.join(codexHome, "hooks.json");
+function platformTargets(platform) {
+  const home = platformHome(platform);
+  return {
+    target: path.join(home, "skills", "context-guard"),
+    hooksTarget: path.join(home, PLATFORM_SPECS[platform].hooksFile),
+    configTarget: PLATFORM_SPECS[platform].configFile
+      ? path.join(home, PLATFORM_SPECS[platform].configFile)
+      : null
+  };
+}
+
+function selectedPlatforms(requested) {
+  if (requested === "all") return Object.keys(PLATFORM_SPECS);
+  if (requested !== "auto") return [requested];
+  const detected = Object.entries(PLATFORM_SPECS)
+    .filter(([, spec]) => Boolean(process.env[spec.env]) || fs.existsSync(platformHomeBySpec(spec)))
+    .map(([name]) => name);
+  return detected.length ? detected : ["codex"];
+}
+
+function platformHomeBySpec(spec) {
+  return path.resolve(expandHome(process.env[spec.env] || path.join(os.homedir(), spec.folder)));
 }
 
 function parseInstallArgs(args) {
   const options = {
-    target: defaultSkillTarget(),
-    withHooks: false,
-    hooksTarget: defaultHooksTarget(),
+    platform: "auto",
+    target: process.env.CONTEXT_GUARD_SKILL_TARGET
+      ? path.resolve(expandHome(process.env.CONTEXT_GUARD_SKILL_TARGET))
+      : null,
+    withHooks: true,
+    hooksTarget: process.env.CONTEXT_GUARD_HOOKS_TARGET
+      ? path.resolve(expandHome(process.env.CONTEXT_GUARD_HOOKS_TARGET))
+      : null,
+    configTarget: null,
+    targetExplicit: Boolean(process.env.CONTEXT_GUARD_SKILL_TARGET),
+    hooksTargetExplicit: Boolean(process.env.CONTEXT_GUARD_HOOKS_TARGET),
     dryRun: false
   };
 
@@ -68,12 +105,26 @@ function parseInstallArgs(args) {
       const value = args[++i];
       if (!value) fail("--target requires a directory");
       options.target = path.resolve(expandHome(value));
+      options.targetExplicit = true;
+    } else if (arg === "--platform") {
+      const value = String(args[++i] || "").toLowerCase();
+      if (!["auto", "all", ...Object.keys(PLATFORM_SPECS)].includes(value)) {
+        fail("--platform must be auto, all, codex, cursor, or claude");
+      }
+      options.platform = value;
     } else if (arg === "--with-hooks" || arg === "--hooks") {
       options.withHooks = true;
+    } else if (arg === "--no-hooks") {
+      options.withHooks = false;
     } else if (arg === "--hooks-target") {
       const value = args[++i];
       if (!value) fail("--hooks-target requires a file path");
       options.hooksTarget = path.resolve(expandHome(value));
+      options.hooksTargetExplicit = true;
+    } else if (arg === "--config-target") {
+      const value = args[++i];
+      if (!value) fail("--config-target requires a file path");
+      options.configTarget = path.resolve(expandHome(value));
     } else if (arg === "--dry-run") {
       options.dryRun = true;
     } else if (arg === "-h" || arg === "--help") {
@@ -83,9 +134,73 @@ function parseInstallArgs(args) {
       fail(`unknown install option: ${arg}`);
     }
   }
+  if ((options.target || options.hooksTarget || options.configTarget) && options.platform === "all") {
+    fail("custom targets can only be used with one platform");
+  }
+  if (options.targetExplicit && !options.hooksTargetExplicit) {
+    const platform = options.platform === "auto" ? "codex" : options.platform;
+    options.hooksTarget = path.join(path.dirname(options.target), PLATFORM_SPECS[platform].hooksFile);
+  }
+  if (!options.configTarget && options.hooksTarget && (options.platform === "auto" || options.platform === "codex")) {
+    options.configTarget = path.join(path.dirname(options.hooksTarget), "config.toml");
+  }
   return options;
 }
 
+function migrateHooksFeatureConfig(configTarget, dryRun) {
+  const original = fs.existsSync(configTarget) ? fs.readFileSync(configTarget, "utf8") : "";
+  const lines = original ? original.replace(/\r\n/g, "\n").split("\n") : [];
+  const sectionStart = lines.findIndex((line) => /^\s*\[features\]\s*(?:#.*)?$/.test(line));
+  let nextLines = lines.slice();
+
+  if (sectionStart === -1) {
+    while (nextLines.length && nextLines[nextLines.length - 1] === "") nextLines.pop();
+    if (nextLines.length) nextLines.push("");
+    nextLines.push("[features]", "hooks = true", "");
+  } else {
+    let sectionEnd = nextLines.length;
+    for (let i = sectionStart + 1; i < nextLines.length; i += 1) {
+      if (/^\s*\[[^\]]+\]/.test(nextLines[i])) {
+        sectionEnd = i;
+        break;
+      }
+    }
+    const hooksIndex = nextLines.findIndex(
+      (line, index) => index > sectionStart && index < sectionEnd && /^\s*hooks\s*=/.test(line)
+    );
+    const legacyIndexes = [];
+    nextLines.forEach((line, index) => {
+      if (index > sectionStart && index < sectionEnd && /^\s*codex_hooks\s*=/.test(line)) legacyIndexes.push(index);
+    });
+
+    if (hooksIndex >= 0) {
+      nextLines[hooksIndex] = nextLines[hooksIndex].replace(/^\s*hooks\s*=.*$/, "hooks = true");
+      for (const index of legacyIndexes.reverse()) nextLines.splice(index, 1);
+    } else if (legacyIndexes.length) {
+      const first = legacyIndexes.shift();
+      nextLines[first] = nextLines[first].replace(/^\s*codex_hooks\s*=.*$/, "hooks = true");
+      for (const index of legacyIndexes.reverse()) nextLines.splice(index, 1);
+    } else {
+      nextLines.splice(sectionStart + 1, 0, "hooks = true");
+    }
+  }
+
+  const next = `${nextLines.join("\n").replace(/\n*$/, "")}\n`;
+  if (next === original.replace(/\r\n/g, "\n")) return;
+  if (dryRun) {
+    console.log(`[context-guard-skill] would enable hooks in ${configTarget}`);
+    return;
+  }
+  fs.mkdirSync(path.dirname(configTarget), { recursive: true });
+  if (fs.existsSync(configTarget)) {
+    const backupPath = `${configTarget}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    fs.copyFileSync(configTarget, backupPath);
+    console.log(`[context-guard-skill] backed up config: ${backupPath}`);
+  }
+  fs.writeFileSync(configTarget, next);
+  console.log(`[context-guard-skill] enabled hooks: ${configTarget}`);
+}
+
 function copySkill(target, dryRun) {
   if (!fs.existsSync(path.join(sourceSkillDir, "SKILL.md"))) {
     fail(`source skill folder is missing: ${sourceSkillDir}`);
@@ -96,19 +211,32 @@ function copySkill(target, dryRun) {
   }
   fs.rmSync(target, { recursive: true, force: true });
   fs.mkdirSync(path.dirname(target), { recursive: true });
-  fs.cpSync(sourceSkillDir, target, { recursive: true });
+  fs.mkdirSync(target, { recursive: true });
+  for (const entry of skillInstallEntries) {
+    const from = path.join(sourceSkillDir, entry);
+    if (!fs.existsSync(from)) continue;
+    const to = path.join(target, entry);
+    fs.cpSync(from, to, { recursive: true });
+  }
   console.log(`[context-guard-skill] installed skill: ${target}`);
 }
 
-function rewriteHookCommands(hooksConfig, skillTarget) {
+function hookCommand(skillTarget, event, platform) {
   const hookScript = path.join(skillTarget, "scripts", "context_guard_hook.py");
   const encodedHookScript = JSON.stringify(hookScript);
+  const pythonCommand = process.platform === "win32" ? "python" : "python3";
+  return `${pythonCommand} ${encodedHookScript} ${event} --platform ${platform}`;
+}
+
+function rewriteGroupedHookCommands(hooksConfig, skillTarget, platform) {
   const next = JSON.parse(JSON.stringify(hooksConfig));
   for (const groups of Object.values(next.hooks || {})) {
     for (const group of groups || []) {
       for (const hook of group.hooks || []) {
         if (hook.type === "command" && typeof hook.command === "string" && hook.command.includes("context_guard_hook.py")) {
-          hook.command = `python3 ${encodedHookScript} ${hook.command.split(" ").pop()}`;
+          const match = hook.command.match(/context_guard_hook\.py["']?\s+([a-z-]+)/);
+          const event = match ? match[1] : "session-start";
+          hook.command = hookCommand(skillTarget, event, platform);
         }
       }
     }
@@ -116,6 +244,25 @@ function rewriteHookCommands(hooksConfig, skillTarget) {
   return next;
 }
 
+function cursorHooks(skillTarget) {
+  const events = {
+    sessionStart: "session-start",
+    subagentStart: "subagent-start",
+    beforeSubmitPrompt: "user-prompt-submit",
+    subagentStop: "subagent-stop",
+    stop: "stop"
+  };
+  const hooks = {};
+  for (const [cursorEvent, normalizedEvent] of Object.entries(events)) {
+    hooks[cursorEvent] = [{
+      type: "command",
+      command: hookCommand(skillTarget, normalizedEvent, "cursor"),
+      timeout: 10
+    }];
+  }
+  return { version: 1, hooks };
+}
+
 function mergeHooks(existing, incoming) {
   const merged = existing && typeof existing === "object" ? existing : {};
   merged.hooks = merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {};
@@ -130,36 +277,73 @@ function mergeHooks(existing, incoming) {
   return merged;
 }
 
-function installHooks(skillTarget, hooksTarget, dryRun) {
-  if (!fs.existsSync(sourceHooksPath)) {
-    fail(`source hooks file is missing: ${sourceHooksPath}`);
-  }
-  const rawIncoming = JSON.parse(fs.readFileSync(sourceHooksPath, "utf8"));
-  const incoming = rewriteHookCommands(rawIncoming, skillTarget);
-  let existing = {};
-  if (fs.existsSync(hooksTarget)) {
-    existing = JSON.parse(fs.readFileSync(hooksTarget, "utf8"));
+function mergeCursorHooks(existing, incoming) {
+  const merged = existing && typeof existing === "object" ? existing : {};
+  merged.version = merged.version || 1;
+  merged.hooks = merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {};
+  for (const [event, hooks] of Object.entries(incoming.hooks || {})) {
+    const current = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+    merged.hooks[event] = current
+      .filter((hook) => !String(hook && hook.command || "").includes("context_guard_hook.py"))
+      .concat(hooks);
   }
-  const merged = mergeHooks(existing, incoming);
+  return merged;
+}
+
+function writeConfigFile(target, value, label, dryRun) {
   if (dryRun) {
-    console.log(`[context-guard-skill] would install hooks to ${hooksTarget}`);
+    console.log(`[context-guard-skill] would install ${label} to ${target}`);
     return;
   }
-  fs.mkdirSync(path.dirname(hooksTarget), { recursive: true });
-  if (fs.existsSync(hooksTarget)) {
-    const backupPath = `${hooksTarget}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-    fs.copyFileSync(hooksTarget, backupPath);
-    console.log(`[context-guard-skill] backed up hooks: ${backupPath}`);
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  if (fs.existsSync(target)) {
+    const backupPath = `${target}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    fs.copyFileSync(target, backupPath);
+    console.log(`[context-guard-skill] backed up ${label}: ${backupPath}`);
   }
-  fs.writeFileSync(hooksTarget, `${JSON.stringify(merged, null, 2)}\n`);
-  console.log(`[context-guard-skill] installed hooks: ${hooksTarget}`);
+  fs.writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`);
+  console.log(`[context-guard-skill] installed ${label}: ${target}`);
+}
+
+function readObject(target) {
+  if (!fs.existsSync(target)) return {};
+  const value = JSON.parse(fs.readFileSync(target, "utf8"));
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+
+function installHooks(platform, skillTarget, hooksTarget, dryRun) {
+  if (!fs.existsSync(sourceHooksPath)) {
+    fail(`source hooks file is missing: ${sourceHooksPath}`);
+  }
+  const existing = readObject(hooksTarget);
+  if (platform === "cursor") {
+    writeConfigFile(hooksTarget, mergeCursorHooks(existing, cursorHooks(skillTarget)), "hooks", dryRun);
+    return;
+  }
+  const rawIncoming = JSON.parse(fs.readFileSync(sourceHooksPath, "utf8"));
+  const incoming = rewriteGroupedHookCommands(rawIncoming, skillTarget, platform);
+  const merged = mergeHooks(existing, incoming);
+  writeConfigFile(hooksTarget, merged, platform === "claude" ? "settings hooks" : "hooks", dryRun);
 }
 
 function install(args) {
   const options = parseInstallArgs(args);
-  copySkill(options.target, options.dryRun);
-  if (options.withHooks) {
-    installHooks(options.target, options.hooksTarget, options.dryRun);
+  let platforms = selectedPlatforms(options.platform);
+  if ((options.target || options.hooksTarget || options.configTarget) && options.platform === "auto") {
+    platforms = ["codex"];
+  }
+  for (const platform of platforms) {
+    const defaults = platformTargets(platform);
+    const skillTarget = options.target || defaults.target;
+    const hooksTarget = options.hooksTarget || defaults.hooksTarget;
+    const configTarget = options.configTarget || defaults.configTarget;
+    copySkill(skillTarget, options.dryRun);
+    if (options.withHooks) {
+      if (platform === "codex" && configTarget) {
+        migrateHooksFeatureConfig(configTarget, options.dryRun);
+      }
+      installHooks(platform, skillTarget, hooksTarget, options.dryRun);
+    }
   }
 }
 
@@ -167,9 +351,13 @@ function runPython(args) {
   if (!fs.existsSync(pythonScript)) {
     fail(`context_guard.py is missing: ${pythonScript}`);
   }
-  const result = spawnSync("python3", [pythonScript, ...args], { stdio: "inherit" });
-  if (result.error) fail(result.error.message);
-  process.exit(result.status === null ? 1 : result.status);
+  for (const command of ["python3", "python"]) {
+    const result = spawnSync(command, [pythonScript, ...args], { stdio: "inherit" });
+    if (result.error && result.error.code === "ENOENT") continue;
+    if (result.error) fail(result.error.message);
+    process.exit(result.status === null ? 1 : result.status);
+  }
+  fail("Python 3 is required; neither `python3` nor `python` was found.");
 }
 
 const [command, ...rest] = process.argv.slice(2);

package/bin/postinstall.js

@@ -13,7 +13,7 @@ if (skipInstall) {
 }
 
 if (!isGlobalInstall && !autoInstall) {
-  console.log("[context-guard-skill] package installed. Run `npx @michelj/context-guard install` to install the Codex skill.");
+  console.log("[context-guard-skill] package installed. Run `npx @michelj/context-guard install` to install the skill and hooks for detected clients.");
   process.exit(0);
 }
 

package/hooks.json

@@ -6,21 +6,45 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ./scripts/context_guard_hook.py session-start",
+            "command": "python3 ./scripts/context_guard_hook.py session-start --platform codex",
             "timeout": 10,
             "statusMessage": "Initializing context folder"
           }
         ]
       }
     ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py subagent-start --platform codex",
+            "timeout": 10,
+            "statusMessage": "Initializing folder context"
+          }
+        ]
+      }
+    ],
     "UserPromptSubmit": [
       {
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ./scripts/context_guard_hook.py user-prompt-submit",
+            "command": "python3 ./scripts/context_guard_hook.py user-prompt-submit --platform codex",
+            "timeout": 10,
+            "statusMessage": "Recording durable user wording"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py subagent-stop --platform codex",
             "timeout": 10,
-            "statusMessage": "Checking context intake"
+            "statusMessage": "Reminder: write sessions/bugs/tasks if this turn mattered"
           }
         ]
       }
@@ -30,9 +54,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "python3 ./scripts/context_guard_hook.py stop",
+            "command": "python3 ./scripts/context_guard_hook.py stop --platform codex",
             "timeout": 10,
-            "statusMessage": "Checking context checkpoint"
+            "statusMessage": "Reminder: write sessions/bugs/tasks if this turn mattered"
           }
         ]
       }

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@michelj/context-guard",
-  "version": "0.4.2",
-  "description": "Install and run the Context Guard Codex skill.",
+  "version": "0.4.4",
+  "description": "Install and run Context Guard for Codex, Cursor, and Claude.",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/Michel-Johnson/Context-Guard-Skill.git"
+    "url": "git+https://github.com/Michel-Johnson/Context-Guard-Skill.git"
   },
   "publishConfig": {
     "access": "public",
@@ -17,13 +17,20 @@
   "files": [
     "README.md",
     "README.zh-CN.md",
+    "SKILL.md",
     "hooks.json",
+    "agents/",
     "bin/",
-    "skills/context-guard/"
+    "prototype/",
+    "references/",
+    "scripts/context_guard.py",
+    "scripts/context_guard_hook.py",
+    "scripts/map_owns.py"
   ],
   "scripts": {
     "postinstall": "node bin/postinstall.js",
-    "test": "bash tests/npm-install-smoke.sh && python3 -m py_compile skills/context-guard/scripts/context_guard.py skills/context-guard/scripts/context_guard_hook.py"
+    "test": "node tests/ci-smoke.mjs",
+    "test:cd": "node .github/scripts/rehearse-cd.mjs"
   },
   "engines": {
     "node": ">=18"