agileflow 3.4.3 → 4.0.0-alpha.1

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 };

package/src/runtime/plugins/registry.js

@@ -0,0 +1,132 @@
+/**
+ * Plugin registry — discovers plugin manifests under apps/cli/content/plugins/.
+ *
+ * Phase 2a scope: discover + shallow-validate plugin.yaml. Full validation
+ * (depends resolution, cycle detection, command/skill cross-refs) lands
+ * with the full validator in Phase 2b.
+ */
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const PLUGINS_DIR = path.join(__dirname, '..', '..', '..', 'content', 'plugins');
+
+const REQUIRED_FIELDS = ['id', 'name', 'description', 'version'];
+
+/**
+ * @typedef {Object} PluginManifest
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ * @property {string} version
+ * @property {boolean} [enabledByDefault]
+ * @property {boolean} [cannotDisable]
+ * @property {string[]} [depends]
+ * @property {{
+ *   commands?: object[],
+ *   skills?: object[],
+ *   agents?: object[],
+ *   hooks?: object[],
+ *   templates?: object[],
+ * }} [provides]
+ * @property {string} dir - absolute path of the plugin directory (computed)
+ */
+
+/**
+ * Parse and validate a single plugin.yaml.
+ * @param {string} pluginDir
+ * @returns {PluginManifest}
+ */
+function loadPlugin(pluginDir) {
+  const manifestPath = path.join(pluginDir, 'plugin.yaml');
+  if (!fs.existsSync(manifestPath)) {
+    throw new Error(`Missing plugin.yaml at ${pluginDir}`);
+  }
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8');
+  } catch (err) {
+    throw new Error(`Cannot read ${manifestPath}: ${err.message}`);
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    throw new Error(`Invalid YAML in ${manifestPath}: ${err.message}`);
+  }
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`Empty or non-object plugin.yaml at ${manifestPath}`);
+  }
+  const missing = REQUIRED_FIELDS.filter((k) => parsed[k] == null);
+  if (missing.length) {
+    throw new Error(
+      `Plugin ${path.basename(pluginDir)} missing required fields: ${missing.join(', ')}`,
+    );
+  }
+  // `depends` is optional, but if present it MUST be an array — silently
+  // coercing `depends: "core"` to `[]` would drop the author's intent.
+  let depends = [];
+  if (parsed.depends != null) {
+    if (!Array.isArray(parsed.depends)) {
+      throw new Error(
+        `Plugin ${path.basename(pluginDir)}: 'depends' must be an array of plugin ids (got ${typeof parsed.depends})`,
+      );
+    }
+    depends = parsed.depends;
+  }
+  return {
+    id: parsed.id,
+    name: parsed.name,
+    description: parsed.description,
+    version: parsed.version,
+    enabledByDefault: Boolean(parsed.enabledByDefault),
+    cannotDisable: Boolean(parsed.cannotDisable),
+    depends,
+    provides: parsed.provides || {
+      commands: [],
+      skills: [],
+      agents: [],
+      hooks: [],
+      templates: [],
+    },
+    dir: pluginDir,
+  };
+}
+
+/**
+ * Discover all plugins in the bundled content/plugins/ directory.
+ * @param {string} [root=PLUGINS_DIR]
+ * @returns {PluginManifest[]} sorted: required (cannotDisable) first, then alpha by id
+ */
+function discoverPlugins(root = PLUGINS_DIR) {
+  if (!fs.existsSync(root)) return [];
+  const entries = fs.readdirSync(root, { withFileTypes: true });
+  const plugins = entries
+    .filter((e) => e.isDirectory())
+    .map((e) => loadPlugin(path.join(root, e.name)));
+  plugins.sort((a, b) => {
+    if (a.cannotDisable !== b.cannotDisable) {
+      return a.cannotDisable ? -1 : 1;
+    }
+    return a.id.localeCompare(b.id);
+  });
+  const ids = new Set();
+  for (const p of plugins) {
+    if (ids.has(p.id)) {
+      throw new Error(`Duplicate plugin id: ${p.id}`);
+    }
+    ids.add(p.id);
+  }
+  return plugins;
+}
+
+/**
+ * @param {string} id
+ * @param {string} [root=PLUGINS_DIR]
+ * @returns {PluginManifest|null}
+ */
+function getPlugin(id, root = PLUGINS_DIR) {
+  return discoverPlugins(root).find((p) => p.id === id) || null;
+}
+
+module.exports = { discoverPlugins, getPlugin, loadPlugin, PLUGINS_DIR };

package/src/runtime/plugins/resolver.js

@@ -0,0 +1,138 @@
+/**
+ * Plugin dependency resolver.
+ *
+ * Given a set of discovered plugins and the user's selection, computes:
+ *   - the transitive closure of dependencies (auto-enable anything the
+ *     user-selected plugins depend on),
+ *   - a topological install order (dependencies before dependents),
+ *   - cycle detection (throws with the offending cycle path).
+ *
+ * Plugins with `cannotDisable: true` (currently just `core`) are always
+ * included in the resolved set even if not in `userSelected`.
+ */
+
+/**
+ * @typedef {import('./registry.js').PluginManifest} PluginManifest
+ *
+ * @typedef {Object} ResolveResult
+ * @property {PluginManifest[]} ordered
+ *   Plugins in install order — dependencies appear before dependents.
+ * @property {string[]} autoEnabled
+ *   Ids that were pulled in because something else depended on them
+ *   (i.e. not in `userSelected` and not `cannotDisable`).
+ */
+
+const COLOR_WHITE = 0;
+const COLOR_GRAY = 1;
+const COLOR_BLACK = 2;
+
+/**
+ * Validate that every plugin's `depends` references resolve to a known
+ * id in the discovered set. Thrown errors quote both the dependent and
+ * the missing dependency.
+ *
+ * @param {PluginManifest[]} discovered
+ * @param {Map<string, PluginManifest>} byId
+ */
+function assertDependsExist(discovered, byId) {
+  for (const p of discovered) {
+    for (const dep of p.depends || []) {
+      if (typeof dep !== 'string' || !dep) {
+        throw new Error(
+          `Plugin "${p.id}" has an invalid entry in 'depends': ${JSON.stringify(dep)}`,
+        );
+      }
+      if (!byId.has(dep)) {
+        throw new Error(
+          `Plugin "${p.id}" depends on unknown plugin "${dep}"`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * @param {PluginManifest[]} discovered
+ * @param {Iterable<string>} userSelected - ids the user explicitly enabled
+ * @returns {ResolveResult}
+ */
+function resolvePlugins(discovered, userSelected) {
+  const byId = new Map(discovered.map((p) => [p.id, p]));
+  assertDependsExist(discovered, byId);
+
+  const userSet = new Set(userSelected);
+  // Reject unknown user-selected ids loudly so callers don't silently
+  // drop a typo. The wizard's pluginsFromCsv layer also surfaces this,
+  // but direct callers of resolvePlugins (CI, programmatic install)
+  // get the same protection here.
+  for (const id of userSet) {
+    if (!byId.has(id)) {
+      const known = [...byId.keys()].sort().join(', ');
+      throw new Error(
+        `User-selected plugin "${id}" was not discovered. Available: ${known || '(none)'}`,
+      );
+    }
+  }
+  // Initial target set: cannotDisable (core) + user-selected.
+  /** @type {Set<string>} */
+  const target = new Set();
+  for (const p of discovered) {
+    if (p.cannotDisable || userSet.has(p.id)) {
+      target.add(p.id);
+    }
+  }
+
+  // Walk transitive dependencies to grow `target`.
+  const queue = [...target];
+  while (queue.length) {
+    const id = queue.shift();
+    const p = byId.get(id);
+    for (const dep of p.depends || []) {
+      if (!target.has(dep)) {
+        target.add(dep);
+        queue.push(dep);
+      }
+    }
+  }
+
+  // DFS topological sort with three-color cycle detection.
+  /** @type {Map<string, number>} */
+  const color = new Map();
+  /** @type {string[]} */
+  const order = [];
+
+  /**
+   * @param {string} id
+   * @param {string[]} stack - the current DFS path; used for cycle reporting
+   */
+  function visit(id, stack) {
+    const c = color.get(id) ?? COLOR_WHITE;
+    if (c === COLOR_BLACK) return;
+    if (c === COLOR_GRAY) {
+      const cycleStart = stack.indexOf(id);
+      const cycle = [...stack.slice(cycleStart), id].join(' -> ');
+      throw new Error(`Plugin dependency cycle detected: ${cycle}`);
+    }
+    color.set(id, COLOR_GRAY);
+    const p = byId.get(id);
+    const nextStack = [...stack, id];
+    for (const dep of p.depends || []) {
+      visit(dep, nextStack);
+    }
+    color.set(id, COLOR_BLACK);
+    order.push(id);
+  }
+
+  for (const id of target) {
+    visit(id, []);
+  }
+
+  const ordered = order.map((id) => byId.get(id));
+  const autoEnabled = [...target].filter((id) => {
+    const p = byId.get(id);
+    return !userSet.has(id) && !p.cannotDisable;
+  });
+  return { ordered, autoEnabled };
+}
+
+module.exports = { resolvePlugins };

package/src/runtime/plugins/validator.js

@@ -0,0 +1,196 @@
+/**
+ * Strict plugin.yaml validator.
+ *
+ * Layered on top of `registry.js::loadPlugin`, which already does
+ * lightweight YAML-parse + required-field checks. The strict validator
+ * adds quality / consistency rules that we want to enforce in CI and in
+ * the upcoming `agileflow doctor` command, but which we don't want to
+ * fail on at first-load (so a slightly nonconforming third-party plugin
+ * still partially loads for diagnostic purposes).
+ *
+ * Returns an array of `Issue` objects. Empty array means valid.
+ */
+
+/**
+ * @typedef {Object} Issue
+ * @property {'error' | 'warning'} severity
+ * @property {string} pluginId
+ * @property {string} message
+ *
+ * @typedef {import('./registry.js').PluginManifest} PluginManifest
+ */
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+// Permissive semver: MAJOR.MINOR.PATCH with optional -prerelease and +build.
+const SEMVER_PATTERN =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** @type {ReadonlySet<string>} */
+const VALID_PROVIDES_KEYS = new Set([
+  'commands',
+  'skills',
+  'agents',
+  'hooks',
+  'templates',
+]);
+
+/**
+ * Validate a single plugin manifest. Pure: no I/O.
+ *
+ * @param {PluginManifest} plugin
+ * @returns {Issue[]}
+ */
+function validatePlugin(plugin) {
+  /** @type {Issue[]} */
+  const issues = [];
+  const id = plugin && typeof plugin.id === 'string' ? plugin.id : '<unknown>';
+
+  const error = (msg) => issues.push({ severity: 'error', pluginId: id, message: msg });
+  const warn = (msg) => issues.push({ severity: 'warning', pluginId: id, message: msg });
+
+  if (!plugin || typeof plugin !== 'object') {
+    return [{ severity: 'error', pluginId: id, message: 'Plugin manifest is not an object.' }];
+  }
+
+  // id format
+  if (typeof plugin.id !== 'string') {
+    error('`id` must be a string.');
+  } else if (!ID_PATTERN.test(plugin.id)) {
+    error(
+      `\`id\` "${plugin.id}" must match /^[a-z0-9][a-z0-9-]{0,63}$/ (lowercase, kebab-case, max 64 chars).`,
+    );
+  }
+
+  // name
+  if (typeof plugin.name !== 'string' || !plugin.name.trim()) {
+    error('`name` must be a non-empty string.');
+  }
+
+  // description
+  if (typeof plugin.description !== 'string' || !plugin.description.trim()) {
+    error('`description` must be a non-empty string.');
+  } else if (plugin.description.length < 16) {
+    warn('`description` is very short — aim for at least one meaningful sentence.');
+  }
+
+  // version
+  if (typeof plugin.version !== 'string') {
+    error('`version` must be a string (semver).');
+  } else if (!SEMVER_PATTERN.test(plugin.version)) {
+    error(`\`version\` "${plugin.version}" must be a valid semver (MAJOR.MINOR.PATCH).`);
+  }
+
+  // booleans
+  if (typeof plugin.enabledByDefault !== 'boolean') {
+    error('`enabledByDefault` must be a boolean.');
+  }
+  if (typeof plugin.cannotDisable !== 'boolean') {
+    error('`cannotDisable` must be a boolean.');
+  }
+
+  // cannotDisable implies enabledByDefault
+  if (plugin.cannotDisable === true && plugin.enabledByDefault === false) {
+    error('A plugin with `cannotDisable: true` must also have `enabledByDefault: true`.');
+  }
+
+  // depends
+  if (!Array.isArray(plugin.depends)) {
+    error('`depends` must be an array of plugin ids.');
+  } else {
+    for (const dep of plugin.depends) {
+      if (typeof dep !== 'string' || !ID_PATTERN.test(dep)) {
+        error(`\`depends\` entry ${JSON.stringify(dep)} must be a valid plugin id.`);
+      }
+      if (typeof dep === 'string' && dep === plugin.id) {
+        error('A plugin cannot depend on itself.');
+      }
+    }
+    const seen = new Set();
+    for (const dep of plugin.depends) {
+      if (typeof dep === 'string') {
+        if (seen.has(dep)) {
+          warn(`Duplicate dependency "${dep}" in \`depends\` (deduplicate).`);
+        }
+        seen.add(dep);
+      }
+    }
+  }
+
+  // provides — allowed shape
+  if (plugin.provides != null) {
+    if (typeof plugin.provides !== 'object' || Array.isArray(plugin.provides)) {
+      error('`provides` must be an object with arrays of commands/skills/agents/hooks/templates.');
+    } else {
+      for (const key of Object.keys(plugin.provides)) {
+        if (!VALID_PROVIDES_KEYS.has(key)) {
+          warn(`\`provides.${key}\` is not a recognized key — expected one of: ${[...VALID_PROVIDES_KEYS].join(', ')}.`);
+        }
+      }
+      for (const key of VALID_PROVIDES_KEYS) {
+        const v = plugin.provides[key];
+        if (v != null && !Array.isArray(v)) {
+          error(`\`provides.${key}\` must be an array (got ${typeof v}).`);
+        }
+      }
+    }
+  }
+
+  return issues;
+}
+
+/**
+ * Validate all plugins together, including cross-plugin invariants:
+ *   - unique ids (registry already detects this, but we double-check)
+ *   - depends references resolve to known ids
+ *
+ * @param {PluginManifest[]} plugins
+ * @returns {Issue[]}
+ */
+function validatePluginSet(plugins) {
+  /** @type {Issue[]} */
+  const issues = [];
+  for (const p of plugins) {
+    issues.push(...validatePlugin(p));
+  }
+  const ids = new Set();
+  for (const p of plugins) {
+    if (typeof p.id === 'string') {
+      if (ids.has(p.id)) {
+        issues.push({
+          severity: 'error',
+          pluginId: p.id,
+          message: `Duplicate plugin id "${p.id}".`,
+        });
+      }
+      ids.add(p.id);
+    }
+  }
+  for (const p of plugins) {
+    for (const dep of p.depends || []) {
+      if (typeof dep === 'string' && !ids.has(dep)) {
+        issues.push({
+          severity: 'error',
+          pluginId: p.id,
+          message: `Depends on unknown plugin "${dep}".`,
+        });
+      }
+    }
+  }
+  return issues;
+}
+
+/**
+ * @param {Issue[]} issues
+ * @returns {boolean}
+ */
+function hasErrors(issues) {
+  return issues.some((i) => i.severity === 'error');
+}
+
+module.exports = {
+  validatePlugin,
+  validatePluginSet,
+  hasErrors,
+  ID_PATTERN,
+  SEMVER_PATTERN,
+};