agileflow 3.4.3 → 4.0.0-alpha.2

package/src/runtime/installer/install.js

@@ -0,0 +1,329 @@
+/**
+ * `installPlugins` — end-to-end orchestrator that wires the plugin
+ * registry, validator, resolver, and sync engine into a single call.
+ *
+ * Flow:
+ *   1. Strict-validate every discovered plugin (errors → throw with
+ *      a flat report; warnings ignored here, surfaced by `doctor`).
+ *   2. Resolve transitive dependencies + topological order from the
+ *      user's selection (resolver throws on cycles or missing deps).
+ *   3. Read the existing `_cfg/files.json` (or build a fresh index).
+ *   4. For each resolved plugin, walk its source directory and
+ *      `syncFile` every file into `<agileflowDir>/plugins/<id>/...`.
+ *   5. Remove directories of previously-installed plugins that are no
+ *      longer enabled. Their entries are also pruned from the file
+ *      index.
+ *   6. Write the file index atomically.
+ *
+ * Side effects only on the destination project. The bundled `content/`
+ * source tree is read-only.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const { syncFile, emptyCounters } = require("./sync-engine.js");
+const {
+  emptyIndex,
+  readFileIndex,
+  writeFileIndex,
+} = require("./file-index.js");
+const { resolvePlugins } = require("../plugins/resolver.js");
+const { validatePluginSet, hasErrors } = require("../plugins/validator.js");
+const {
+  writeAggregatedManifest,
+  removeAggregatedManifest,
+  buildHookManifest,
+} = require("../hooks/aggregator.js");
+const { normalizeManifest } = require("../hooks/manifest-loader.js");
+const { capabilitiesFor } = require("../ide/capabilities.js");
+const {
+  writeClaudeCodeSettings,
+  removeClaudeCodeSettings,
+} = require("../ide/claude-code-settings.js");
+const {
+  mirrorClaudeCodeSkills,
+  unmirrorClaudeCodeSkills,
+} = require("../ide/claude-code-skills.js");
+
+/**
+ * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
+ *
+ * @typedef {Object} InstallOptions
+ * @property {PluginManifest[]} discovered
+ * @property {Iterable<string>} userSelected
+ * @property {string} agileflowDir - target install root (typically `<cwd>/.agileflow`)
+ * @property {string} cliVersion - written into the file index header
+ * @property {string} [ide='claude-code'] - target IDE for capability gating
+ * @property {Record<string, boolean>} [behaviors] - behavior preset toggles
+ * @property {boolean} [force=false] - overwrite user modifications
+ *
+ * @typedef {Object} InstallResult
+ * @property {string[]} ordered - plugin ids in install order
+ * @property {string[]} autoEnabled - ids pulled in via depends
+ * @property {string[]} removed - ids whose dir was removed (no longer enabled)
+ * @property {import('./sync-engine.js').FileOpsCounters} ops
+ * @property {string} agileflowDir
+ * @property {string} indexPath
+ * @property {string} timestamp
+ * @property {string|null} hookManifestPath - path of the written hook manifest, or null
+ * @property {string|null} settingsPath - path of the written .claude/settings.json, or null
+ * @property {string[]} skillsMirrored - skill ids copied into .claude/skills/
+ * @property {string[]} skillsPruned - skill ids removed from .claude/skills/
+ * @property {Array<{skillId:string, error:string}>} [skillsSkipped] - skills with missing source
+ * @property {string} ide - the target IDE for this install
+ */
+
+/**
+ * Build a stable file-system-safe timestamp string for stash bucketing.
+ * @returns {string}
+ */
+function makeTimestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+/** @param {string} p */
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * Yield absolute paths to every file under `dir`, depth-first.
+ * @param {string} dir
+ * @returns {AsyncGenerator<string>}
+ */
+async function* walkFiles(dir) {
+  const entries = await fs.promises.readdir(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      yield* walkFiles(full);
+    } else if (e.isFile()) {
+      yield full;
+    }
+  }
+}
+
+/**
+ * Sync every file in `plugin.dir` into `agileflowDir/plugins/<id>/...`.
+ *
+ * @param {PluginManifest} plugin
+ * @param {string} agileflowDir
+ * @param {import('./file-index.js').FileIndex} fileIndex
+ * @param {import('./sync-engine.js').FileOpsCounters} ops
+ * @param {string} timestamp
+ * @param {boolean} force
+ */
+async function installOnePlugin(
+  plugin,
+  agileflowDir,
+  fileIndex,
+  ops,
+  timestamp,
+  force,
+) {
+  const cfgDir = path.join(agileflowDir, "_cfg");
+  const pluginRoot = path.join(agileflowDir, "plugins", plugin.id);
+
+  for await (const sourcePath of walkFiles(plugin.dir)) {
+    const relInPlugin = path.relative(plugin.dir, sourcePath);
+    const dest = path.join(pluginRoot, relInPlugin);
+    const relativePath = toPosix(path.relative(agileflowDir, dest));
+    const content = await fs.promises.readFile(sourcePath);
+    await syncFile({
+      content,
+      dest,
+      relativePath,
+      fileIndex,
+      cfgDir,
+      timestamp,
+      force,
+      ops,
+    });
+  }
+}
+
+/**
+ * Remove plugin directories for plugins that were previously installed
+ * (have entries in the file index under `plugins/<id>/...`) but are
+ * NOT in the currently enabled set. Their file index entries are also
+ * pruned so a future re-enable produces fresh CREATED records.
+ *
+ * @param {Set<string>} enabledIds
+ * @param {Set<string>} knownIds - all discovered ids (so we don't blow
+ *   away unknown directories the user might have placed manually)
+ * @param {string} agileflowDir
+ * @param {import('./file-index.js').FileIndex} fileIndex
+ * @param {import('./sync-engine.js').FileOpsCounters} ops
+ * @returns {Promise<string[]>} the plugin ids that were removed
+ */
+async function removeDisabledPlugins(
+  enabledIds,
+  knownIds,
+  agileflowDir,
+  fileIndex,
+  ops,
+) {
+  const pluginsRoot = path.join(agileflowDir, "plugins");
+  /** @type {string[]} */
+  const removed = [];
+  let entries;
+  try {
+    entries = await fs.promises.readdir(pluginsRoot, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === "ENOENT") return removed;
+    throw err;
+  }
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const id = e.name;
+    if (enabledIds.has(id)) continue;
+    if (!knownIds.has(id)) continue; // leave unknown dirs alone
+    const dir = path.join(pluginsRoot, id);
+    await fs.promises.rm(dir, { recursive: true, force: true });
+    for (const key of Object.keys(fileIndex.files)) {
+      if (key.startsWith(`plugins/${id}/`)) {
+        delete fileIndex.files[key];
+      }
+    }
+    removed.push(id);
+    ops.removed++;
+  }
+  return removed;
+}
+
+/**
+ * @param {InstallOptions} options
+ * @returns {Promise<InstallResult>}
+ */
+async function installPlugins(options) {
+  const {
+    discovered,
+    userSelected,
+    agileflowDir,
+    cliVersion,
+    ide = "claude-code",
+    behaviors,
+    force = false,
+  } = options;
+
+  // 1. Strict-validate. Errors abort; warnings are surfaced elsewhere.
+  const issues = validatePluginSet(discovered);
+  if (hasErrors(issues)) {
+    const errors = issues
+      .filter((i) => i.severity === "error")
+      .map((i) => `  ${i.pluginId}: ${i.message}`)
+      .join("\n");
+    throw new Error(`Plugin validation failed:\n${errors}`);
+  }
+
+  // 2. Resolve dependency order.
+  const { ordered, autoEnabled } = resolvePlugins(discovered, userSelected);
+
+  // 3. Read or seed the file index.
+  const cfgDir = path.join(agileflowDir, "_cfg");
+  const indexPath = path.join(cfgDir, "files.json");
+  const fileIndex = (await readFileIndex(indexPath)) || emptyIndex(cliVersion);
+
+  // 4-6 wrapped in try/finally so the file index is ALWAYS persisted,
+  // even if a sync fails mid-loop. Otherwise on-disk files would exist
+  // without index entries and the next run would misclassify them as
+  // "user-modified" and stash them.
+  const ops = emptyCounters();
+  const timestamp = makeTimestamp();
+  /** @type {string[]} */
+  let removed = [];
+
+  try {
+    // 4. Sync each plugin in order.
+    for (const plugin of ordered) {
+      await installOnePlugin(
+        plugin,
+        agileflowDir,
+        fileIndex,
+        ops,
+        timestamp,
+        force,
+      );
+    }
+
+    // 5. Remove disabled plugin directories.
+    const enabledIds = new Set(ordered.map((p) => p.id));
+    const knownIds = new Set(discovered.map((p) => p.id));
+    removed = await removeDisabledPlugins(
+      enabledIds,
+      knownIds,
+      agileflowDir,
+      fileIndex,
+      ops,
+    );
+  } finally {
+    // 6. Persist the file index. Always.
+    await writeFileIndex(indexPath, fileIndex);
+  }
+
+  // 7. Validate-before-write: build the manifest in memory and run
+  //    the loader's normalizer against it. Surfacing an invalid plugin
+  //    contribution NOW prevents step 8 from registering hook
+  //    dispatchers in settings.json that point at an unparseable
+  //    manifest.
+  const caps = capabilitiesFor(ide);
+  let hookManifestPath = null;
+  if (caps.hooks) {
+    const manifestObj = buildHookManifest(ordered, behaviors);
+    try {
+      normalizeManifest(manifestObj);
+    } catch (err) {
+      throw new Error(`Hook manifest validation failed: ${err.message}`);
+    }
+    hookManifestPath = await writeAggregatedManifest(
+      ordered,
+      agileflowDir,
+      behaviors,
+    );
+  } else {
+    await removeAggregatedManifest(agileflowDir);
+  }
+
+  // 8. Register or unregister our hook dispatchers in
+  //    `.claude/settings.json`. Only when ide=claude-code.
+  const projectRoot = path.dirname(agileflowDir);
+  let settingsPath = null;
+  if (ide === "claude-code") {
+    settingsPath = await writeClaudeCodeSettings(projectRoot);
+  } else {
+    await removeClaudeCodeSettings(projectRoot);
+  }
+
+  // 9. Mirror skills into `.claude/skills/<id>/`. Copy (not symlink)
+  //    for Windows portability. Missing skill sources are skipped
+  //    gracefully; non-ENOENT errors propagate.
+  let skillsMirrored = [];
+  let skillsPruned = [];
+  let skillsSkipped = [];
+  if (caps.skills) {
+    const r = await mirrorClaudeCodeSkills(ordered, projectRoot);
+    skillsMirrored = r.mirrored;
+    skillsPruned = r.pruned;
+    skillsSkipped = r.skipped || [];
+  } else {
+    skillsPruned = await unmirrorClaudeCodeSkills(projectRoot);
+  }
+
+  return {
+    ordered: ordered.map((p) => p.id),
+    autoEnabled,
+    removed,
+    ops,
+    agileflowDir,
+    indexPath,
+    timestamp,
+    hookManifestPath,
+    settingsPath,
+    skillsMirrored,
+    skillsPruned,
+    skillsSkipped,
+    ide,
+  };
+}
+
+module.exports = { installPlugins };

package/src/runtime/installer/stash.js

@@ -0,0 +1,61 @@
+/**
+ * Stash writer for the sync engine.
+ *
+ * When the sync engine encounters a user-modified destination file whose
+ * content diverges from the incoming upstream version, it preserves the
+ * user's file in place and writes the new version to a stash directory
+ * at `<cfgDir>/updates/<timestamp>/<relativePath>` so the user can
+ * manually diff and merge.
+ *
+ * Path-traversal-safe: a malicious or buggy `relativePath` containing
+ * `..` segments cannot escape the updates directory. The resolved
+ * destination is checked against the resolved updates root and rejected
+ * if it points outside.
+ */
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * @param {Object} args
+ * @param {string} args.cfgDir - absolute path to .agileflow/_cfg/
+ * @param {string} args.timestamp - stable stamp for this sync run
+ * @param {string} args.relativePath - posix-style path (no leading slash, no `..`)
+ * @param {Buffer|string} args.content - bytes to stash (as would have been written)
+ * @returns {Promise<string>} absolute path the stash file was written to
+ */
+async function writeStash({ cfgDir, timestamp, relativePath, content }) {
+  // Reject absolute paths up front. `path.join` would otherwise treat
+  // `/etc/passwd` as a relative segment, silently producing
+  // `<updatesRoot>/etc/passwd` which is technically inside the root
+  // but not what the caller intended.
+  if (path.isAbsolute(relativePath)) {
+    throw new Error(
+      `writeStash: relativePath "${relativePath}" escapes the updates directory (must be a relative path)`,
+    );
+  }
+
+  const updatesRoot = path.resolve(path.join(cfgDir, 'updates', timestamp));
+  const stashPath = path.resolve(path.join(updatesRoot, relativePath));
+
+  // Path-traversal guard: stashPath must be at or under updatesRoot.
+  // We check both equality (a relativePath that resolves to the dir
+  // itself) and the path.sep prefix (any descendant).
+  if (
+    stashPath !== updatesRoot &&
+    !stashPath.startsWith(updatesRoot + path.sep)
+  ) {
+    throw new Error(
+      `writeStash: relativePath "${relativePath}" escapes the updates directory`,
+    );
+  }
+
+  await fs.promises.mkdir(path.dirname(stashPath), { recursive: true });
+  if (typeof content === 'string') {
+    await fs.promises.writeFile(stashPath, content, 'utf8');
+  } else {
+    await fs.promises.writeFile(stashPath, content);
+  }
+  return stashPath;
+}
+
+module.exports = { writeStash };

package/src/runtime/installer/sync-engine.js

@@ -0,0 +1,205 @@
+/**
+ * Sync engine — SHA256-based conflict-aware file installer.
+ *
+ * Ported from v3 `packages/cli/tools/cli/installers/core/installer.js`
+ * lines 349-455 (`copyFileWithPolicy`). Same decision tree, rewritten in
+ * plain JS + JSDoc and split into testable pieces.
+ *
+ * The engine handles one file at a time and returns the action taken.
+ * Callers loop over plugin content and aggregate results into
+ * `FileOpsCounters`.
+ *
+ * Decision tree (same as v3):
+ *
+ *   destExists?
+ *     no  → write; record fresh hash; CREATED
+ *     yes → force?
+ *       yes → overwrite; record fresh hash; UPDATED
+ *       no  → compute currentHash of dest
+ *              protected flag in index?
+ *                yes → currentHash == newHash?
+ *                  yes → clear protected; UNCHANGED (auto-converged)
+ *                  no  → stash new; keep user file; PRESERVED
+ *                no  → index.sha256 == currentHash? (file untouched since last install)
+ *                  yes → currentHash != newHash? write new; record hash; UPDATED
+ *                        else: nothing to do; UNCHANGED
+ *                  no  → (unknown baseline / locally modified)
+ *                        currentHash == newHash?
+ *                          yes → adopt new hash; UNCHANGED
+ *                          no  → stash new; keep user file; PRESERVED
+ *
+ * The `fileIndex.files[relativePath]` entry is always updated so that
+ * the next sync run has an accurate baseline.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const { sha256Hex, sha256File } = require('../../lib/hash.js');
+const { writeStash } = require('./stash.js');
+
+/**
+ * @typedef {'created' | 'updated' | 'preserved' | 'unchanged'} SyncAction
+ *
+ * @typedef {Object} FileOpsCounters
+ * @property {number} created
+ * @property {number} updated
+ * @property {number} preserved
+ * @property {number} unchanged
+ * @property {number} stashed
+ * @property {number} removed
+ * @property {string|null} updatesPath
+ *
+ * @typedef {Object} SyncOptions
+ * @property {Buffer|string} content - bytes to write at `dest`
+ * @property {string} dest - absolute destination path
+ * @property {string} relativePath - posix-style path used as the fileIndex key
+ * @property {import('./file-index.js').FileIndex} fileIndex - mutated with new hashes
+ * @property {string} cfgDir - absolute path to .agileflow/_cfg/
+ * @property {string} timestamp - ISO stamp used as the stash bucket
+ * @property {boolean} [force=false] - if true, overwrite user modifications
+ * @property {FileOpsCounters} [ops] - optional counters; if omitted, caller loses aggregate info
+ */
+
+/**
+ * @returns {FileOpsCounters}
+ */
+function emptyCounters() {
+  return {
+    created: 0,
+    updated: 0,
+    preserved: 0,
+    unchanged: 0,
+    stashed: 0,
+    removed: 0,
+    updatesPath: null,
+  };
+}
+
+/**
+ * Write `content` to `dest` atomically: write a temp file in the same
+ * directory, then `rename` it into place. Crashes mid-`writeFile`
+ * cannot leave a truncated `dest` — readers always see either the old
+ * content or the new content, never a half-write.
+ *
+ * Temp filename uses pid + random suffix so two concurrent calls in
+ * the same process (rare but possible in tests / cluster setups) don't
+ * collide on each other's temp file.
+ *
+ * @param {Buffer|string} content
+ * @param {string} dest
+ */
+async function writeContent(content, dest) {
+  await fs.promises.mkdir(path.dirname(dest), { recursive: true });
+  const tmp = `${dest}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
+  try {
+    if (typeof content === 'string') {
+      await fs.promises.writeFile(tmp, content, 'utf8');
+    } else {
+      await fs.promises.writeFile(tmp, content);
+    }
+    await fs.promises.rename(tmp, dest);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+}
+
+/**
+ * Sync a single file. Returns the action taken and mutates `fileIndex`
+ * plus `ops` (if provided).
+ *
+ * @param {SyncOptions} options
+ * @returns {Promise<SyncAction>}
+ */
+async function syncFile(options) {
+  const {
+    content,
+    dest,
+    relativePath,
+    fileIndex,
+    cfgDir,
+    timestamp,
+    force = false,
+    ops,
+  } = options;
+
+  const newHash = sha256Hex(content);
+  const existing = fileIndex.files[relativePath];
+  const existingRecord =
+    existing && typeof existing === 'object' && typeof existing.sha256 === 'string'
+      ? existing
+      : null;
+
+  const currentHash = await sha256File(dest);
+  const destExists = currentHash !== null;
+
+  if (!destExists) {
+    await writeContent(content, dest);
+    fileIndex.files[relativePath] = { sha256: newHash, protected: false };
+    if (ops) ops.created++;
+    return 'created';
+  }
+
+  if (force) {
+    await writeContent(content, dest);
+    fileIndex.files[relativePath] = { sha256: newHash, protected: false };
+    if (ops) ops.updated++;
+    return 'updated';
+  }
+
+  // Respect a previously-protected file unless it has since converged
+  // with upstream (user's edits happen to match the new content — rare
+  // but worth auto-clearing the protected flag so future updates flow).
+  if (existingRecord && existingRecord.protected) {
+    if (currentHash === newHash) {
+      fileIndex.files[relativePath] = { sha256: newHash, protected: false };
+      if (ops) ops.unchanged++;
+      return 'unchanged';
+    }
+    const stashPath = await writeStash({ cfgDir, timestamp, relativePath, content });
+    fileIndex.files[relativePath] = { sha256: currentHash, protected: true };
+    if (ops) {
+      ops.preserved++;
+      ops.stashed++;
+      ops.updatesPath = path.dirname(stashPath);
+    }
+    return 'preserved';
+  }
+
+  // Baseline path: user hasn't touched this file since the last install.
+  if (existingRecord && existingRecord.sha256 === currentHash) {
+    if (currentHash === newHash) {
+      // Nothing to do; record stays current.
+      fileIndex.files[relativePath] = { sha256: newHash, protected: false };
+      if (ops) ops.unchanged++;
+      return 'unchanged';
+    }
+    await writeContent(content, dest);
+    fileIndex.files[relativePath] = { sha256: newHash, protected: false };
+    if (ops) ops.updated++;
+    return 'updated';
+  }
+
+  // No baseline OR user-modified file. If the current content happens to
+  // match upstream, adopt the hash and move on; otherwise preserve+stash.
+  if (currentHash === newHash) {
+    fileIndex.files[relativePath] = { sha256: newHash, protected: false };
+    if (ops) ops.unchanged++;
+    return 'unchanged';
+  }
+
+  const stashPath = await writeStash({ cfgDir, timestamp, relativePath, content });
+  fileIndex.files[relativePath] = { sha256: currentHash, protected: true };
+  if (ops) {
+    ops.preserved++;
+    ops.stashed++;
+    ops.updatesPath = path.dirname(stashPath);
+  }
+  return 'preserved';
+}
+
+module.exports = { syncFile, emptyCounters };