agileflow 3.4.3 → 4.0.0-alpha.2

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

@@ -0,0 +1,234 @@
+/**
+ * Claude Code settings.json writer.
+ *
+ * When the target IDE is `claude-code`, the installer registers our 6
+ * hook entry points in `.claude/settings.json` so Claude Code actually
+ * invokes them at runtime. We use the unified `npx --no-install
+ * agileflow hook <event> [--matcher <m>]` command so the path resolves
+ * regardless of how the package is installed.
+ *
+ * The writer is **non-destructive**: it merges with any existing
+ * settings.json. Only AgileFlow-owned hook entries (identified by the
+ * `agileflow hook` substring in their command) are replaced; the
+ * user's other hook registrations and non-hook fields (permissions,
+ * env, etc.) are preserved.
+ *
+ * On a non-claude-code switch, `removeManagedHooks` strips our entries
+ * but leaves the rest of the file alone.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const HOOK_COMMAND_MARKER = 'agileflow hook';
+const HOOK_TIMEOUT_SECONDS = 30;
+
+/**
+ * The 6 hook registrations we own. Each is `{ event, matcher?, command }`.
+ * The `command` is what gets baked into settings.json.
+ */
+const MANAGED_HOOKS = [
+  { event: 'SessionStart', matcher: null, command: 'npx --no-install agileflow hook SessionStart' },
+  { event: 'PreToolUse', matcher: 'Bash', command: 'npx --no-install agileflow hook PreToolUse --matcher Bash' },
+  { event: 'PreToolUse', matcher: 'Edit', command: 'npx --no-install agileflow hook PreToolUse --matcher Edit' },
+  { event: 'PreToolUse', matcher: 'Write', command: 'npx --no-install agileflow hook PreToolUse --matcher Write' },
+  { event: 'PreCompact', matcher: null, command: 'npx --no-install agileflow hook PreCompact' },
+  { event: 'Stop', matcher: null, command: 'npx --no-install agileflow hook Stop' },
+];
+
+const MANAGED_EVENTS = new Set(MANAGED_HOOKS.map((h) => h.event));
+
+/**
+ * Detect whether a settings.json hook entry belongs to AgileFlow.
+ * @param {*} entry
+ */
+function isAgileflowEntry(entry) {
+  if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) return false;
+  return entry.hooks.some(
+    (h) =>
+      h &&
+      typeof h === 'object' &&
+      h.type === 'command' &&
+      typeof h.command === 'string' &&
+      h.command.includes(HOOK_COMMAND_MARKER),
+  );
+}
+
+/**
+ * Build a fresh entry for one MANAGED_HOOKS row.
+ * @param {{ matcher: string|null, command: string }} hook
+ */
+function buildEntry({ matcher, command }) {
+  /** @type {{ matcher?: string, hooks: object[] }} */
+  const out = {
+    hooks: [
+      { type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS },
+    ],
+  };
+  if (matcher) out.matcher = matcher;
+  return out;
+}
+
+/**
+ * Read existing settings.json (or {} if absent / malformed).
+ * @param {string} settingsPath
+ * @returns {Promise<object>}
+ */
+async function readExisting(settingsPath) {
+  try {
+    const raw = await fs.promises.readFile(settingsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    if (err instanceof SyntaxError) return {};
+    throw err;
+  }
+}
+
+/**
+ * Atomically write the merged settings.
+ * @param {string} settingsPath
+ * @param {object} settings
+ */
+async function writeMerged(settingsPath, settings) {
+  await fs.promises.mkdir(path.dirname(settingsPath), { recursive: true });
+  const tmp = path.join(
+    path.dirname(settingsPath),
+    `.${path.basename(settingsPath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  const text = JSON.stringify(settings, null, 2) + '\n';
+  try {
+    await fs.promises.writeFile(tmp, text, 'utf8');
+    await fs.promises.rename(tmp, settingsPath);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+}
+
+/**
+ * Compute the merged settings: drop any existing AgileFlow entries from
+ * the events we manage, append our fresh ones in the canonical order,
+ * leave everything else alone.
+ *
+ * @param {object} existing
+ * @returns {object}
+ */
+function mergeManagedHooks(existing) {
+  const next = { ...existing };
+  // Reject array-shaped `hooks`: spreading an array into a plain object
+  // produces numeric-keyed garbage. Treat it as missing instead.
+  const baseHooks =
+    existing.hooks &&
+    typeof existing.hooks === 'object' &&
+    !Array.isArray(existing.hooks)
+      ? existing.hooks
+      : {};
+  const hooks = { ...baseHooks };
+
+  for (const event of MANAGED_EVENTS) {
+    const prior = Array.isArray(hooks[event]) ? hooks[event] : [];
+    // Strip our previous registrations, keep user's other entries.
+    const userEntries = prior.filter((e) => !isAgileflowEntry(e));
+    const ours = MANAGED_HOOKS.filter((h) => h.event === event).map(buildEntry);
+    hooks[event] = [...ours, ...userEntries];
+  }
+
+  next.hooks = hooks;
+  return next;
+}
+
+/**
+ * Compute the unmanaged settings: strip AgileFlow entries from every
+ * event we manage. Used when switching to a non-claude-code IDE.
+ *
+ * @param {object} existing
+ * @returns {object}
+ */
+function unmanageHooks(existing) {
+  const next = { ...existing };
+  if (
+    !existing.hooks ||
+    typeof existing.hooks !== 'object' ||
+    Array.isArray(existing.hooks)
+  ) {
+    return next;
+  }
+  const hooks = { ...existing.hooks };
+  for (const event of MANAGED_EVENTS) {
+    if (!Array.isArray(hooks[event])) continue;
+    const userEntries = hooks[event].filter((e) => !isAgileflowEntry(e));
+    if (userEntries.length === 0) {
+      delete hooks[event];
+    } else {
+      hooks[event] = userEntries;
+    }
+  }
+  // If hooks ended up with no keys, drop the field entirely.
+  if (Object.keys(hooks).length === 0) {
+    delete next.hooks;
+  } else {
+    next.hooks = hooks;
+  }
+  return next;
+}
+
+/**
+ * Register the 6 AgileFlow hooks in `<projectRoot>/.claude/settings.json`.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string>} absolute path of the written settings file
+ */
+async function writeClaudeCodeSettings(projectRoot) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const existing = await readExisting(settingsPath);
+  const merged = mergeManagedHooks(existing);
+  await writeMerged(settingsPath, merged);
+  return settingsPath;
+}
+
+/**
+ * Strip AgileFlow hook registrations from settings.json. If the file
+ * ends up empty (no hooks AND no other fields), it's removed; if it
+ * still has content, the cleaned version is written back.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<{ removed: boolean, settingsPath: string|null }>}
+ */
+async function removeClaudeCodeSettings(projectRoot) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  // readExisting already converts ENOENT and SyntaxError to {} — any
+  // exception here means a real filesystem problem (EACCES / EIO).
+  // Do NOT swallow: a silent success would lie about successfully
+  // removing entries that are still in an unreadable file.
+  const existing = await readExisting(settingsPath);
+  const next = unmanageHooks(existing);
+  if (Object.keys(next).length === 0) {
+    try {
+      await fs.promises.unlink(settingsPath);
+      return { removed: true, settingsPath };
+    } catch (err) {
+      if (err.code === 'ENOENT') return { removed: false, settingsPath: null };
+      throw err;
+    }
+  }
+  await writeMerged(settingsPath, next);
+  return { removed: false, settingsPath };
+}
+
+module.exports = {
+  writeClaudeCodeSettings,
+  removeClaudeCodeSettings,
+  mergeManagedHooks,
+  unmanageHooks,
+  isAgileflowEntry,
+  MANAGED_HOOKS,
+  MANAGED_EVENTS,
+  HOOK_COMMAND_MARKER,
+  HOOK_TIMEOUT_SECONDS,
+};

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

@@ -0,0 +1,202 @@
+/**
+ * Claude Code skill mirror.
+ *
+ * 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.
+ *
+ * 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.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @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 {Array<{ skillId: string, error: string }>} skipped - skills whose source was missing
+ */
+
+/**
+ * Recursively copy a directory tree.
+ * @param {string} src
+ * @param {string} dest
+ */
+async function copyDir(src, dest) {
+  // 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
+  // for a successful copy.
+  const entries = await fs.promises.readdir(src, { withFileTypes: true });
+  await fs.promises.mkdir(dest, { recursive: true });
+  for (const e of entries) {
+    const s = path.join(src, e.name);
+    const d = path.join(dest, e.name);
+    if (e.isDirectory()) {
+      await copyDir(s, d);
+    } else if (e.isFile()) {
+      await fs.promises.copyFile(s, d);
+    }
+  }
+}
+
+/**
+ * Recursively remove a directory tree (no-op when missing).
+ * @param {string} dir
+ */
+async function rmDir(dir) {
+  await fs.promises.rm(dir, { recursive: true, force: true });
+}
+
+/**
+ * Collect every skill declared by an enabled plugin manifest. Returns
+ * a list of `{ skillId, sourceDir }` where sourceDir is absolute.
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @returns {Array<{ skillId: string, sourceDir: string }>}
+ */
+function collectPluginSkills(orderedPlugins) {
+  /** @type {Array<{ skillId: string, sourceDir: string }>} */
+  const out = [];
+  for (const plugin of orderedPlugins) {
+    const skills =
+      plugin.provides && Array.isArray(plugin.provides.skills)
+        ? plugin.provides.skills
+        : [];
+    for (const s of skills) {
+      // Reject missing-or-empty id/dir. An empty `dir: ""` would
+      // pass `typeof === 'string'` but path.join silently treats it as
+      // the plugin root, which is never what the author intended.
+      if (
+        !s ||
+        typeof s.id !== 'string' ||
+        !s.id ||
+        typeof s.dir !== 'string' ||
+        !s.dir
+      ) {
+        continue;
+      }
+      out.push({
+        skillId: s.id,
+        sourceDir: path.join(plugin.dir, s.dir),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Mirror enabled plugin skills into `<projectRoot>/.claude/skills/<skill-id>/`
+ * and remove any `.claude/skills/<id>/` whose id is not in the current
+ * enabled set.
+ *
+ * Only AgileFlow-tracked skills are pruned: a skill is "tracked" iff
+ * its dir contains a `SKILL.md` whose first line is `---` AND its name
+ * 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
+ * matches an `agileflow-*` convention OR is in the previously-mirrored
+ * set on disk. Unknown user-placed skill dirs without that prefix are
+ * left alone.
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {string} projectRoot
+ * @returns {Promise<MirrorResult>}
+ */
+async function mirrorClaudeCodeSkills(orderedPlugins, projectRoot) {
+  const claudeSkills = path.join(projectRoot, '.claude', 'skills');
+  await fs.promises.mkdir(claudeSkills, { recursive: true });
+
+  const want = collectPluginSkills(orderedPlugins);
+  const wantIds = new Set(want.map((w) => w.skillId));
+
+  /** @type {string[]} */
+  const mirrored = [];
+  /** @type {Array<{ skillId: string, error: string }>} */
+  const skipped = [];
+  for (const { skillId, sourceDir } of want) {
+    const dest = path.join(claudeSkills, skillId);
+    try {
+      // 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);
+      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') {
+        skipped.push({
+          skillId,
+          error: `source not found: ${sourceDir}`,
+        });
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  /** @type {string[]} */
+  const pruned = [];
+  let entries;
+  try {
+    entries = await fs.promises.readdir(claudeSkills, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return { mirrored, pruned };
+    throw err;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (wantIds.has(e.name)) continue;
+    // Only prune skills that LOOK like ours: agileflow-* prefix. This
+    // 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;
+    await rmDir(path.join(claudeSkills, e.name));
+    pruned.push(e.name);
+  }
+
+  return { mirrored, pruned, skipped };
+}
+
+/**
+ * Remove all AgileFlow-mirrored skills from `.claude/skills/`. 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');
+  /** @type {string[]} */
+  const removed = [];
+  let entries;
+  try {
+    entries = await fs.promises.readdir(claudeSkills, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return removed;
+    throw err;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    if (!e.name.startsWith('agileflow-')) continue;
+    await rmDir(path.join(claudeSkills, e.name));
+    removed.push(e.name);
+  }
+  return removed;
+}
+
+module.exports = {
+  mirrorClaudeCodeSkills,
+  unmirrorClaudeCodeSkills,
+  collectPluginSkills,
+};

package/src/runtime/installer/file-index.js

@@ -0,0 +1,112 @@
+/**
+ * File index read/write for the sync engine.
+ *
+ * The file index (`_cfg/files.json`) records the SHA256 hash of every
+ * file the installer has written into the user's project and whether
+ * the user has since diverged from that baseline. The sync engine uses
+ * the index to decide whether a destination file is safe to overwrite,
+ * should be preserved, or should trigger a stash.
+ *
+ * Schema (version 1):
+ *   {
+ *     schema: 1,
+ *     generated_at: <ISO string>,
+ *     version: <CLI version that wrote this index>,
+ *     files: {
+ *       "<posix-relative-path>": {
+ *         sha256: "<hex>",
+ *         protected: <bool>
+ *       },
+ *       ...
+ *     }
+ *   }
+ */
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_VERSION = 1;
+
+/**
+ * @typedef {{ sha256: string, protected: boolean }} FileRecord
+ * @typedef {{ schema: 1, generated_at: string, version: string, files: Record<string, FileRecord> }} FileIndex
+ */
+
+/**
+ * Build an empty index. Caller fills `files` as sync proceeds.
+ * @param {string} cliVersion
+ * @returns {FileIndex}
+ */
+function emptyIndex(cliVersion) {
+  return {
+    schema: SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    version: cliVersion,
+    files: {},
+  };
+}
+
+/**
+ * Read an index file. Returns null on missing file, malformed JSON, or
+ * schema mismatch — the caller should treat any of those as "first
+ * install / no baseline" and start fresh.
+ *
+ * @param {string} indexPath
+ * @returns {Promise<FileIndex|null>}
+ */
+async function readFileIndex(indexPath) {
+  let raw;
+  try {
+    raw = await fs.promises.readFile(indexPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  if (parsed.schema !== SCHEMA_VERSION) return null;
+  if (!parsed.files || typeof parsed.files !== 'object' || Array.isArray(parsed.files)) {
+    return null;
+  }
+  return /** @type {FileIndex} */ (parsed);
+}
+
+/**
+ * Write the index atomically (temp + rename), matching the writer's
+ * pattern for the user config. Callers should pass the final index they
+ * produced — nothing about `files` is validated here.
+ *
+ * @param {string} indexPath
+ * @param {FileIndex} index
+ * @returns {Promise<void>}
+ */
+async function writeFileIndex(indexPath, index) {
+  const dir = path.dirname(indexPath);
+  await fs.promises.mkdir(dir, { recursive: true });
+  const tmp = path.join(
+    dir,
+    `${path.basename(indexPath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  const payload = {
+    ...index,
+    generated_at: new Date().toISOString(),
+  };
+  const content = JSON.stringify(payload, null, 2) + '\n';
+  try {
+    await fs.promises.writeFile(tmp, content, 'utf8');
+    await fs.promises.rename(tmp, indexPath);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+}
+
+module.exports = { SCHEMA_VERSION, emptyIndex, readFileIndex, writeFileIndex };