agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/src/runtime/ide/claude-code-skills.js

@@ -1,25 +1,22 @@
 /**
- * Claude Code skill mirror.
+ * Skill mirror for IDEs that discover skills from a dotdir.
  *
  * Plugin skills are sourced under `apps/cli/content/plugins/<id>/skills/<skill-id>/`
- * and copied into `.agileflow/plugins/<id>/skills/<skill-id>/` by the
- * sync engine. But Claude Code discovers skills from `.claude/skills/<skill-id>/`,
- * so this module mirrors enabled plugin skills to that canonical
- * location and prunes orphaned skills when plugins are disabled.
- *
+ * and copied into the target IDE's skill directory by the installer.
  * We use copy (not symlink) for portability — Windows symlink behavior
- * is inconsistent and Claude Code itself runs there. The duplication
- * cost is negligible at v4-alpha skill counts.
+ * is inconsistent and the supported IDEs run on mixed platforms.
+ * The duplication cost is negligible at v4-alpha skill counts.
  */
-const fs = require('fs');
-const path = require('path');
+const fs = require("fs");
+const path = require("path");
+const { renderSkillForTarget } = require("./babysit-skill.js");
 
 /**
  * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
  *
  * @typedef {Object} MirrorResult
- * @property {string[]} mirrored - skill ids written to .claude/skills/
- * @property {string[]} pruned - skill ids removed from .claude/skills/ (orphans)
+ * @property {string[]} mirrored - skill ids written to the target skills dir
+ * @property {string[]} pruned - skill ids removed from the target skills dir (orphans)
  * @property {Array<{ skillId: string, error: string }>} skipped - skills whose source was missing
  */
 
@@ -28,7 +25,7 @@ const path = require('path');
  * @param {string} src
  * @param {string} dest
  */
-async function copyDir(src, dest) {
+async function copyDir(src, dest, context = {}) {
   // Read the source listing FIRST. If src is missing (ENOENT), the
   // error propagates BEFORE we create dest, so a missing source can't
   // leave behind an empty destination dir for the caller to mistake
@@ -39,9 +36,19 @@ async function copyDir(src, dest) {
     const s = path.join(src, e.name);
     const d = path.join(dest, e.name);
     if (e.isDirectory()) {
-      await copyDir(s, d);
+      await copyDir(s, d, context);
     } else if (e.isFile()) {
-      await fs.promises.copyFile(s, d);
+      if (e.name === "SKILL.md" && context.skillId) {
+        const sourceText = await fs.promises.readFile(s, "utf8");
+        const rendered = renderSkillForTarget(
+          context.skillId,
+          sourceText,
+          context,
+        );
+        await fs.promises.writeFile(d, rendered, "utf8");
+      } else {
+        await fs.promises.copyFile(s, d);
+      }
     }
   }
 }
@@ -75,9 +82,9 @@ function collectPluginSkills(orderedPlugins) {
       // the plugin root, which is never what the author intended.
       if (
         !s ||
-        typeof s.id !== 'string' ||
+        typeof s.id !== "string" ||
         !s.id ||
-        typeof s.dir !== 'string' ||
+        typeof s.dir !== "string" ||
         !s.dir
       ) {
         continue;
@@ -92,8 +99,8 @@ function collectPluginSkills(orderedPlugins) {
 }
 
 /**
- * Mirror enabled plugin skills into `<projectRoot>/.claude/skills/<skill-id>/`
- * and remove any `.claude/skills/<id>/` whose id is not in the current
+ * Mirror enabled plugin skills into `<projectRoot>/<skillsDirRel>/<skill-id>/`
+ * and remove any `<skillsDirRel>/<id>/` whose id is not in the current
  * enabled set.
  *
  * Only AgileFlow-tracked skills are pruned: a skill is "tracked" iff
@@ -101,7 +108,7 @@ function collectPluginSkills(orderedPlugins) {
  * appears in any plugin's `provides.skills` (i.e., we recognize it).
  * To stay safe, we limit pruning to skills we've seen previously by
  * recording the install set in the file index — but for v4-alpha
- * simplicity, we prune every dir under `.claude/skills/` whose name
+ * simplicity, we prune every dir under the skills dir whose name
  * matches an `agileflow-*` convention OR is in the previously-mirrored
  * set on disk. Unknown user-placed skill dirs without that prefix are
  * left alone.
@@ -110,8 +117,13 @@ function collectPluginSkills(orderedPlugins) {
  * @param {string} projectRoot
  * @returns {Promise<MirrorResult>}
  */
-async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
-  const claudeSkills = path.join(projectRoot, '.claude', 'skills');
+async function mirrorClaudeCodeSkills(
+  orderedPlugins,
+  projectRoot,
+  skillsDirRel = ".claude/skills",
+  context = {},
+) {
+  const claudeSkills = path.join(projectRoot, skillsDirRel);
   await fs.promises.mkdir(claudeSkills, { recursive: true });
 
   const want = collectPluginSkills(orderedPlugins);
@@ -127,13 +139,13 @@ async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
       // Replace the destination wholesale so removed files in source
       // don't linger in the user's .claude/skills/.
       await rmDir(dest);
-      await copyDir(sourceDir, dest);
+      await copyDir(sourceDir, dest, { ...context, skillId });
       mirrored.push(skillId);
     } catch (err) {
       // A missing source dir (ENOENT) shouldn't crash the entire
       // install — log and continue so other skills still mirror. A
       // permission error or unrelated failure still propagates.
-      if (err && err.code === 'ENOENT') {
+      if (err && err.code === "ENOENT") {
         skipped.push({
           skillId,
           error: `source not found: ${sourceDir}`,
@@ -150,7 +162,7 @@ async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
   try {
     entries = await fs.promises.readdir(claudeSkills, { withFileTypes: true });
   } catch (err) {
-    if (err.code === 'ENOENT') return { mirrored, pruned };
+    if (err.code === "ENOENT") return { mirrored, pruned };
     throw err;
   }
   for (const e of entries) {
@@ -160,7 +172,7 @@ async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
     // avoids blasting a user-placed third-party skill whose id we
     // don't manage. A dedicated prune-from-index approach can replace
     // this heuristic in a later phase.
-    if (!e.name.startsWith('agileflow-')) continue;
+    if (!e.name.startsWith("agileflow-")) continue;
     await rmDir(path.join(claudeSkills, e.name));
     pruned.push(e.name);
   }
@@ -169,26 +181,29 @@ async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
 }
 
 /**
- * Remove all AgileFlow-mirrored skills from `.claude/skills/`. Used
- * when switching to a non-skill IDE.
+ * Remove all AgileFlow-mirrored skills from the target skills dir.
+ * Used when switching to a non-skill IDE.
  *
  * @param {string} projectRoot
  * @returns {Promise<string[]>} ids that were removed
  */
-async function unmirrorClaudeCodeSkills(projectRoot) {
-  const claudeSkills = path.join(projectRoot, '.claude', 'skills');
+async function unmirrorClaudeCodeSkills(
+  projectRoot,
+  skillsDirRel = ".claude/skills",
+) {
+  const claudeSkills = path.join(projectRoot, skillsDirRel);
   /** @type {string[]} */
   const removed = [];
   let entries;
   try {
     entries = await fs.promises.readdir(claudeSkills, { withFileTypes: true });
   } catch (err) {
-    if (err.code === 'ENOENT') return removed;
+    if (err.code === "ENOENT") return removed;
     throw err;
   }
   for (const e of entries) {
     if (!e.isDirectory()) continue;
-    if (!e.name.startsWith('agileflow-')) continue;
+    if (!e.name.startsWith("agileflow-")) continue;
     await rmDir(path.join(claudeSkills, e.name));
     removed.push(e.name);
   }

package/src/runtime/ide/codex-config.js

@@ -0,0 +1,295 @@
+/**
+ * Codex config.toml writer.
+ *
+ * Codex hooks require the `[features].hooks = true` flag in config.toml.
+ * AgileFlow uses the project-local `config.toml` path because we need both
+ * the feature flag and the inline lifecycle hook tables.
+ *
+ * The writer is non-destructive:
+ *   - it preserves unrelated top-level Codex config
+ *   - it preserves user hook entries on the same events
+ *   - it only manages the AgileFlow hook registrations and the feature flag
+ */
+const fs = require("fs");
+const path = require("path");
+const toml = require("@iarna/toml");
+
+const HOOK_COMMAND_MARKER = "agileflow hook";
+const HOOK_TIMEOUT_SECONDS = 30;
+const DEFAULT_APPROVAL_POLICY = "never";
+const DEFAULT_SANDBOX_MODE = "danger-full-access";
+
+/**
+ * Codex hook registrations we own. These map to the Codex lifecycle
+ * events that AgileFlow actually uses.
+ */
+const MANAGED_HOOKS = [
+  {
+    event: "SessionStart",
+    matcher: null,
+    command: "npx agileflow hook SessionStart",
+    statusMessage: "Loading AgileFlow session context",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Bash",
+    command: "npx agileflow hook PreToolUse --matcher Bash",
+    statusMessage: "Checking Bash command",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Edit",
+    command: "npx agileflow hook PreToolUse --matcher Edit",
+    statusMessage: "Checking Edit command",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Write",
+    command: "npx agileflow hook PreToolUse --matcher Write",
+    statusMessage: "Checking Write command",
+  },
+  {
+    event: "Stop",
+    matcher: null,
+    command: "npx agileflow hook Stop",
+    statusMessage: "Saving AgileFlow state",
+  },
+];
+
+/**
+ * @param {{ matcher: string|null, command: string, statusMessage?: string }} hook
+ */
+function buildEntry({ matcher, command, statusMessage }) {
+  /** @type {{ matcher?: string, hooks: object[] }} */
+  const out = {
+    hooks: [
+      {
+        type: "command",
+        command,
+        timeout: HOOK_TIMEOUT_SECONDS,
+        ...(statusMessage ? { statusMessage } : {}),
+      },
+    ],
+  };
+  if (matcher) out.matcher = matcher;
+  return out;
+}
+
+/**
+ * @param {*} entry
+ * @returns {boolean}
+ */
+function isAgileflowEntry(entry) {
+  if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks)) {
+    return false;
+  }
+  return Array.isArray(entry.hooks)
+    ? entry.hooks.some(
+        (h) =>
+          h &&
+          typeof h === "object" &&
+          h.type === "command" &&
+          typeof h.command === "string" &&
+          h.command.includes(HOOK_COMMAND_MARKER),
+      )
+    : false;
+}
+
+/**
+ * @param {string} configPath
+ * @returns {Promise<object>}
+ */
+async function readExisting(configPath) {
+  try {
+    const raw = await fs.promises.readFile(configPath, "utf8");
+    const parsed = toml.parse(raw);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    return parsed;
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    if (err instanceof SyntaxError || err.name === "TomlError") return {};
+    throw err;
+  }
+}
+
+/**
+ * Merge our managed hook registrations into an existing config object.
+ * @param {object} existing
+ * @returns {object}
+ */
+function mergeManagedHooks(existing) {
+  /** @type {Record<string, any>} */
+  const next = {
+    ...(existing && typeof existing === "object" && !Array.isArray(existing)
+      ? existing
+      : {}),
+  };
+
+  const existingFeatures =
+    next.features &&
+    typeof next.features === "object" &&
+    !Array.isArray(next.features)
+      ? next.features
+      : {};
+  next.features = {
+    ...existingFeatures,
+    hooks: true,
+    collaboration_modes: true,
+  };
+  next.approval_policy = DEFAULT_APPROVAL_POLICY;
+  next.sandbox_mode = DEFAULT_SANDBOX_MODE;
+
+  const existingHooks =
+    next.hooks && typeof next.hooks === "object" && !Array.isArray(next.hooks)
+      ? next.hooks
+      : {};
+  const hooks = { ...existingHooks };
+  /** @type {Map<string, typeof MANAGED_HOOKS>} */
+  const grouped = new Map();
+  for (const managed of MANAGED_HOOKS) {
+    const list = grouped.get(managed.event);
+    if (list) list.push(managed);
+    else grouped.set(managed.event, [managed]);
+  }
+
+  for (const [event, managedList] of grouped.entries()) {
+    const prior = Array.isArray(hooks[event]) ? hooks[event] : [];
+    const userEntries = prior.filter((entry) => !isAgileflowEntry(entry));
+    hooks[event] = [...managedList.map(buildEntry), ...userEntries];
+  }
+
+  next.hooks = hooks;
+  return next;
+}
+
+/**
+ * Remove AgileFlow-managed hook registrations from a config object.
+ * @param {object} existing
+ * @returns {object}
+ */
+function unmanageHooks(existing) {
+  /** @type {Record<string, any>} */
+  const next = {
+    ...(existing && typeof existing === "object" && !Array.isArray(existing)
+      ? existing
+      : {}),
+  };
+
+  if (
+    next.features &&
+    typeof next.features === "object" &&
+    !Array.isArray(next.features)
+  ) {
+    const features = { ...next.features };
+    delete features.hooks;
+    delete features.collaboration_modes;
+    if (Object.keys(features).length) next.features = features;
+    else delete next.features;
+  }
+
+  if (
+    next.hooks &&
+    typeof next.hooks === "object" &&
+    !Array.isArray(next.hooks)
+  ) {
+    const hooks = { ...next.hooks };
+    for (const managed of MANAGED_HOOKS) {
+      if (!Array.isArray(hooks[managed.event])) continue;
+      const userEntries = hooks[managed.event].filter(
+        (entry) => !isAgileflowEntry(entry),
+      );
+      if (userEntries.length) hooks[managed.event] = userEntries;
+      else delete hooks[managed.event];
+    }
+    if (Object.keys(hooks).length) next.hooks = hooks;
+    else delete next.hooks;
+  }
+
+  return next;
+}
+
+/**
+ * @param {string} configPath
+ * @param {object} config
+ */
+async function writeConfigAtomic(configPath, config) {
+  await fs.promises.mkdir(path.dirname(configPath), { recursive: true });
+  const tmp = path.join(
+    path.dirname(configPath),
+    `.${path.basename(configPath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  const text = toml.stringify(config);
+  try {
+    await fs.promises.writeFile(tmp, text, "utf8");
+    await fs.promises.rename(tmp, configPath);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+}
+
+/**
+ * Register the AgileFlow Codex hooks in `<projectRoot>/.codex/config.toml`.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string>} absolute path to the written config
+ */
+async function writeCodexConfig(projectRoot) {
+  const configPath = path.join(projectRoot, ".codex", "config.toml");
+  const existing = await readExisting(configPath);
+  const merged = mergeManagedHooks(existing);
+  await writeConfigAtomic(configPath, merged);
+  return configPath;
+}
+
+/**
+ * Remove AgileFlow-managed Codex hook registrations.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string|null>} path removed/updated, or null when absent
+ */
+async function removeCodexConfig(projectRoot) {
+  const configPath = path.join(projectRoot, ".codex", "config.toml");
+  let existing;
+  try {
+    existing = await readExisting(configPath);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+
+  const stripped = unmanageHooks(existing);
+  if (Object.keys(stripped).length === 0) {
+    try {
+      await fs.promises.unlink(configPath);
+    } catch (err) {
+      if (err.code === "ENOENT") return null;
+      throw err;
+    }
+    return configPath;
+  }
+
+  await writeConfigAtomic(configPath, stripped);
+  return configPath;
+}
+
+module.exports = {
+  DEFAULT_APPROVAL_POLICY,
+  DEFAULT_SANDBOX_MODE,
+  HOOK_COMMAND_MARKER,
+  HOOK_TIMEOUT_SECONDS,
+  MANAGED_HOOKS,
+  buildEntry,
+  isAgileflowEntry,
+  mergeManagedHooks,
+  unmanageHooks,
+  readExisting,
+  writeCodexConfig,
+  removeCodexConfig,
+};