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

package/src/runtime/installer/install.js

@@ -35,15 +35,28 @@ const {
   buildHookManifest,
 } = require("../hooks/aggregator.js");
 const { normalizeManifest } = require("../hooks/manifest-loader.js");
-const { capabilitiesFor } = require("../ide/capabilities.js");
+const { capabilitiesFor, SUPPORTED_IDES } = require("../ide/capabilities.js");
 const {
   writeClaudeCodeSettings,
   removeClaudeCodeSettings,
 } = require("../ide/claude-code-settings.js");
+const {
+  writeCodexConfig,
+  removeCodexConfig,
+} = require("../ide/codex-config.js");
 const {
   mirrorClaudeCodeSkills,
   unmirrorClaudeCodeSkills,
 } = require("../ide/claude-code-skills.js");
+const {
+  mirrorClaudeCodeAgents,
+  unmirrorClaudeCodeAgents,
+} = require("../ide/claude-code-content.js");
+const { loadSkill } = require("../skills/validator.js");
+const {
+  resolveSkillsDir,
+  resolveLearnFile,
+} = require("../skills/learnings.js");
 
 /**
  * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
@@ -53,9 +66,12 @@ const {
  * @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 {string} [ide='claude-code'] - DEPRECATED single-target shorthand (use `ides`)
+ * @property {string[]} [ides] - target IDEs for capability gating; takes precedence over `ide`
  * @property {Record<string, boolean>} [behaviors] - behavior preset toggles
+ * @property {boolean} [learningsEnabled=true] - global learnings on/off
  * @property {boolean} [force=false] - overwrite user modifications
+ * @property {import('../config/defaults.js').AgileflowConfig} [config] - merged config used for skill rendering
  *
  * @typedef {Object} InstallResult
  * @property {string[]} ordered - plugin ids in install order
@@ -67,10 +83,15 @@ const {
  * @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 {string|null} codexConfigPath - path of the written .codex/config.toml, or null
+ * @property {string[]} skillsMirrored - skill ids copied across all skill-supporting IDEs
+ * @property {string[]} skillsPruned - skill ids removed from skill dirs
  * @property {Array<{skillId:string, error:string}>} [skillsSkipped] - skills with missing source
- * @property {string} ide - the target IDE for this install
+ * @property {string[]} agentsMirrored - Claude Code subagents mirrored from enabled plugins
+ * @property {Array<{id:string, error:string}>} [agentsSkipped] - agents with missing source
+ * @property {string[]} docsScaffolded - doc dirs created on first install
+ * @property {string[]} learningsScaffolded - skill ids whose learnings file was newly created
+ * @property {string[]} ides - the target IDEs for this install
  */
 
 /**
@@ -191,6 +212,124 @@ async function removeDisabledPlugins(
   return removed;
 }
 
+/**
+ * Scaffold `_learnings/<file>.yaml` files for every skill in the ordered
+ * plugin set whose frontmatter declares `learns.enabled: true`. Idempotent:
+ * existing files are left untouched.
+ *
+ * @param {PluginManifest[]} ordered
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>} skill ids whose learnings file was newly created
+ */
+async function scaffoldSkillLearnings(ordered, projectRoot) {
+  /** @type {string[]} */
+  const created = [];
+  const skillsDir = resolveSkillsDir(projectRoot);
+  for (const plugin of ordered) {
+    const skills = (plugin.provides && plugin.provides.skills) || [];
+    for (const s of skills) {
+      const skillDir = s && s.dir ? path.join(plugin.dir, s.dir) : null;
+      if (!skillDir) continue;
+      const skillPath = path.join(skillDir, "SKILL.md");
+      let manifest;
+      try {
+        manifest = await loadSkill(skillPath);
+      } catch {
+        continue; // validator will surface the load failure separately
+      }
+      const fm = manifest.frontmatter;
+      if (!fm || !fm.learns || fm.learns.enabled !== true) continue;
+      const learnFile =
+        typeof fm.learns.file === "string" && fm.learns.file
+          ? fm.learns.file
+          : undefined;
+      const p = resolveLearnFile(skillsDir, manifest.skillId, learnFile);
+      await fs.promises.mkdir(path.dirname(p), { recursive: true });
+      try {
+        await fs.promises.access(p);
+      } catch (err) {
+        if (err.code !== "ENOENT") throw err;
+        const header = `# AgileFlow skill learnings — ${manifest.skillId}\n# Append-only signals; oldest trimmed when count exceeds maxEntries.\nentries: []\n`;
+        await fs.promises.writeFile(p, header, "utf8");
+        created.push(manifest.skillId);
+      }
+    }
+  }
+  return created;
+}
+
+/**
+ * Standard docs folder layout that AgileFlow expects at the project root.
+ * Only created on first install (dirs that already exist are skipped).
+ */
+const DOCS_DIRS = [
+  "docs/00-meta",
+  "docs/01-brainstorming",
+  "docs/02-practices",
+  "docs/03-decisions",
+  "docs/04-architecture",
+  "docs/05-epics",
+  "docs/06-stories",
+  "docs/07-testing",
+  "docs/08-project",
+  "docs/09-agents",
+  "docs/10-research",
+];
+
+/**
+ * Scaffold the project docs folder on first install.
+ * Returns the list of dirs that were newly created.
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>}
+ */
+async function scaffoldDocs(projectRoot) {
+  const created = [];
+  for (const rel of DOCS_DIRS) {
+    const dir = path.join(projectRoot, rel);
+    try {
+      await fs.promises.access(dir);
+    } catch (err) {
+      if (err.code !== "ENOENT") throw err;
+      await fs.promises.mkdir(dir, { recursive: true });
+      created.push(rel);
+    }
+  }
+
+  // Seed docs/09-agents/status.json only when newly created.
+  if (created.includes("docs/09-agents")) {
+    const statusPath = path.join(projectRoot, "docs/09-agents/status.json");
+    const seed = JSON.stringify(
+      { updated: new Date().toISOString(), epics: {}, stories: {} },
+      null,
+      2,
+    );
+    await fs.promises.writeFile(statusPath, seed + "\n", "utf8");
+  }
+
+  // Seed docs/00-meta/agileflow-metadata.json only when newly created.
+  if (created.includes("docs/00-meta")) {
+    const metaPath = path.join(
+      projectRoot,
+      "docs/00-meta/agileflow-metadata.json",
+    );
+    const seed = JSON.stringify(
+      {
+        version: "4.0.0",
+        created: new Date().toISOString(),
+        updated: new Date().toISOString(),
+        docsFolder: "docs",
+        archival: { threshold_days: 30, enabled: true },
+        features: {},
+      },
+      null,
+      2,
+    );
+    await fs.promises.writeFile(metaPath, seed + "\n", "utf8");
+  }
+
+  return created;
+}
+
 /**
  * @param {InstallOptions} options
  * @returns {Promise<InstallResult>}
@@ -201,11 +340,27 @@ async function installPlugins(options) {
     userSelected,
     agileflowDir,
     cliVersion,
-    ide = "claude-code",
+    ide,
+    ides,
     behaviors,
+    learningsEnabled = true,
     force = false,
+    config,
   } = options;
 
+  // Resolve the multi-target list. Prefer `ides` (new); fall back to
+  // `ide` (legacy single-target callers — including current tests).
+  /** @type {string[]} */
+  const targetIdes =
+    Array.isArray(ides) && ides.length
+      ? ides
+      : typeof ide === "string" && ide
+        ? [ide]
+        : ["claude-code"];
+  // Per-target capabilities; first target is the "primary" used to
+  // decide hook-manifest / settings.json writes.
+  const primaryIde = targetIdes[0];
+
   // 1. Strict-validate. Errors abort; warnings are surfaced elsewhere.
   const issues = validatePluginSet(discovered);
   if (hasErrors(issues)) {
@@ -266,9 +421,18 @@ async function installPlugins(options) {
   //    contribution NOW prevents step 8 from registering hook
   //    dispatchers in settings.json that point at an unparseable
   //    manifest.
-  const caps = capabilitiesFor(ide);
+  //
+  //    Hook manifest is a global artifact (only one .agileflow/
+  //    hook-manifest.yaml exists per project). We write it whenever ANY
+  //    selected target supports hooks; otherwise we remove any stale
+  //    manifest from a prior hook-capable install.
+  const targetCaps = targetIdes.map((id) => ({
+    id,
+    caps: capabilitiesFor(id),
+  }));
+  const anyHooks = targetCaps.some(({ caps }) => caps.hooks);
   let hookManifestPath = null;
-  if (caps.hooks) {
+  if (anyHooks) {
     const manifestObj = buildHookManifest(ordered, behaviors);
     try {
       normalizeManifest(manifestObj);
@@ -284,31 +448,87 @@ async function installPlugins(options) {
     await removeAggregatedManifest(agileflowDir);
   }
 
-  // 8. Register or unregister our hook dispatchers in
-  //    `.claude/settings.json`. Only when ide=claude-code.
+  // 8. Register hook dispatchers in `.claude/settings.json` iff
+  //    claude-code is in the target set; otherwise remove any prior
+  //    registration we may have written.
   const projectRoot = path.dirname(agileflowDir);
   let settingsPath = null;
-  if (ide === "claude-code") {
+  let agentsMirrored = [];
+  let agentsSkipped = [];
+  if (targetIdes.includes("claude-code")) {
     settingsPath = await writeClaudeCodeSettings(projectRoot);
+    const agentMirror = await mirrorClaudeCodeAgents(ordered, projectRoot);
+    agentsMirrored = agentMirror.mirrored;
+    agentsSkipped = agentMirror.skipped;
   } else {
     await removeClaudeCodeSettings(projectRoot);
+    await unmirrorClaudeCodeAgents(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 || [];
+  let codexConfigPath = null;
+  if (targetIdes.includes("codex")) {
+    codexConfigPath = await writeCodexConfig(projectRoot);
   } else {
-    skillsPruned = await unmirrorClaudeCodeSkills(projectRoot);
+    await removeCodexConfig(projectRoot);
   }
 
+  // 9. Mirror skills into EACH selected IDE's skills dir. For IDEs that
+  //    don't support skills, unmirror so a previous install doesn't
+  //    leave stale files behind.
+  /** @type {Set<string>} */
+  const mirroredSet = new Set();
+  /** @type {Set<string>} */
+  const prunedSet = new Set();
+  /** @type {Array<{skillId:string, error:string}>} */
+  let skillsSkipped = [];
+  for (const target of targetCaps) {
+    const { caps } = target;
+    if (caps.skills) {
+      const r = await mirrorClaudeCodeSkills(
+        ordered,
+        projectRoot,
+        caps.skillsDir,
+        {
+          targetIde: target.id,
+          config,
+        },
+      );
+      r.mirrored.forEach((s) => mirroredSet.add(s));
+      r.pruned.forEach((s) => prunedSet.add(s));
+      if (r.skipped) skillsSkipped = skillsSkipped.concat(r.skipped);
+    } else {
+      const removed = await unmirrorClaudeCodeSkills(
+        projectRoot,
+        caps.skillsDir,
+      );
+      removed.forEach((s) => prunedSet.add(s));
+    }
+  }
+  // Also unmirror from any *unselected* IDE's skills dir so a
+  // re-install with a narrower target set actually removes the old
+  // mirrors. Cheap belt-and-suspenders — unmirror is a no-op when the
+  // dir doesn't exist.
+  for (const id of SUPPORTED_IDES) {
+    if (targetIdes.includes(id)) continue;
+    const caps = capabilitiesFor(id);
+    const removed = await unmirrorClaudeCodeSkills(projectRoot, caps.skillsDir);
+    removed.forEach((s) => prunedSet.add(s));
+  }
+  const skillsMirrored = [...mirroredSet];
+  const skillsPruned = [...prunedSet];
+  const anySkills = targetCaps.some(({ caps }) => caps.skills);
+
+  // 10. Scaffold the project docs folder on first install.
+  const docsScaffolded = await scaffoldDocs(projectRoot);
+
+  // 11. Scaffold persistent learnings files for skills that opt in.
+  //     Lives in .agileflow/skills/_learnings/ — outside the mirror wipe
+  //     zone so re-installs never destroy accumulated signals.
+  const learningsScaffolded =
+    anySkills && learningsEnabled
+      ? await scaffoldSkillLearnings(ordered, projectRoot)
+      : [];
+
   return {
     ordered: ordered.map((p) => p.id),
     autoEnabled,
@@ -319,10 +539,18 @@ async function installPlugins(options) {
     timestamp,
     hookManifestPath,
     settingsPath,
+    codexConfigPath,
     skillsMirrored,
     skillsPruned,
     skillsSkipped,
-    ide,
+    agentsMirrored,
+    agentsSkipped,
+    docsScaffolded,
+    learningsScaffolded,
+    ides: targetIdes,
+    // Back-compat: keep `ide` as the primary so existing callers /
+    // test assertions keep working without a sweep.
+    ide: primaryIde,
   };
 }
 

package/src/runtime/launch/alias-installer.js

@@ -0,0 +1,191 @@
+/**
+ * Install / uninstall the `af` short alias for `agileflow launch`.
+ *
+ * Strategy: symlink `~/.local/bin/af` → the active `agileflow` binary.
+ * `~/.local/bin` is the XDG-standard user-scoped bin directory — no
+ * sudo required, no global mutation. Most modern Linux/macOS setups
+ * include it on PATH (via `~/.profile` / `~/.zprofile`); if not, we
+ * surface a clear warning telling the user how to add it.
+ *
+ * On Windows the symlink approach is fragile (requires Developer Mode
+ * or admin); slice 1 reports `unsupported` and the user can copy the
+ * suggested PowerShell function from the warning. Slice 4 can add a
+ * proper Windows shim.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+/**
+ * Resolve where the `af` symlink should live.
+ *
+ * @param {string} [home]
+ * @returns {string}
+ */
+function aliasPath(home) {
+  return path.join(home || os.homedir(), ".local", "bin", "af");
+}
+
+/**
+ * Best-effort: locate the `agileflow` binary that should be the symlink
+ * target. Prefers `process.argv[1]` (the script Node was invoked with)
+ * which is what the user actually ran — falls back to "agileflow" so
+ * the symlink resolves via PATH if the absolute path can't be inferred.
+ *
+ * @param {NodeJS.Process} [proc]
+ * @returns {string}
+ */
+function resolveAgileflowBin(proc = process) {
+  const argv1 = proc && proc.argv && proc.argv[1];
+  if (argv1) {
+    try {
+      const resolved = fs.realpathSync(argv1);
+      return resolved;
+    } catch {
+      /* fall through */
+    }
+  }
+  return "agileflow";
+}
+
+/**
+ * Check whether `~/.local/bin` is on the user's PATH.
+ *
+ * @param {string} [home]
+ * @param {string} [pathEnv]
+ * @returns {boolean}
+ */
+function localBinOnPath(home, pathEnv) {
+  const target = path.join(home || os.homedir(), ".local", "bin");
+  const env = typeof pathEnv === "string" ? pathEnv : process.env.PATH || "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  return env
+    .split(sep)
+    .map((p) => p.replace(/[/\\]+$/, ""))
+    .includes(target.replace(/[/\\]+$/, ""));
+}
+
+/**
+ * @typedef {Object} AliasInstallResult
+ * @property {'installed' | 'updated' | 'unchanged' | 'unsupported' | 'failed'} status
+ * @property {string} path           - where the symlink was written (or attempted)
+ * @property {string} [target]       - what it points at, when installed
+ * @property {string} [message]      - human-readable detail (for failures / warnings)
+ * @property {boolean} [onPath]      - whether the alias directory is on PATH
+ */
+
+/**
+ * Create or refresh the `af` symlink.
+ *
+ * @param {{ home?: string, proc?: NodeJS.Process }} [opts]
+ * @returns {Promise<AliasInstallResult>}
+ */
+async function installAfAlias(opts = {}) {
+  if (process.platform === "win32") {
+    return {
+      status: "unsupported",
+      path: aliasPath(opts.home),
+      message:
+        "Windows symlinks require Developer Mode or admin. Slice 4 will add a proper shim. " +
+        "For now: add `function af { agileflow launch @args }` to your PowerShell profile.",
+    };
+  }
+
+  const link = aliasPath(opts.home);
+  const target = resolveAgileflowBin(opts.proc);
+  const onPath = localBinOnPath(opts.home);
+
+  try {
+    await fs.promises.mkdir(path.dirname(link), { recursive: true });
+
+    // If a symlink already exists, check whether it points at the same target.
+    let existing = null;
+    try {
+      existing = await fs.promises.readlink(link);
+    } catch {
+      /* not a symlink or absent */
+    }
+
+    if (existing === target) {
+      return { status: "unchanged", path: link, target, onPath };
+    }
+
+    // Remove anything in the way (broken symlink, old file). Don't blow
+    // away a non-symlink regular file — the user may have put it there.
+    let removed = false;
+    try {
+      const stat = await fs.promises.lstat(link);
+      if (stat.isSymbolicLink()) {
+        await fs.promises.unlink(link);
+        removed = true;
+      } else {
+        return {
+          status: "failed",
+          path: link,
+          message: `${link} exists and is not a symlink — leaving it alone. Remove it manually if you want the alias.`,
+          onPath,
+        };
+      }
+    } catch {
+      /* doesn't exist — fine */
+    }
+
+    await fs.promises.symlink(target, link);
+    return {
+      status: removed ? "updated" : "installed",
+      path: link,
+      target,
+      onPath,
+    };
+  } catch (err) {
+    return {
+      status: "failed",
+      path: link,
+      message: `could not create symlink: ${err.message}`,
+      onPath,
+    };
+  }
+}
+
+/**
+ * Remove the `af` symlink if it points at agileflow. Safe no-op otherwise.
+ *
+ * @param {{ home?: string }} [opts]
+ * @returns {Promise<{ status: 'removed' | 'absent' | 'skipped' | 'failed', path: string, message?: string }>}
+ */
+async function uninstallAfAlias(opts = {}) {
+  const link = aliasPath(opts.home);
+  try {
+    const stat = await fs.promises.lstat(link);
+    if (!stat.isSymbolicLink()) {
+      return {
+        status: "skipped",
+        path: link,
+        message: `${link} is not a symlink — leaving it alone.`,
+      };
+    }
+    const target = await fs.promises.readlink(link);
+    if (!/agileflow/i.test(target)) {
+      return {
+        status: "skipped",
+        path: link,
+        message: `${link} points at ${target}; not removing.`,
+      };
+    }
+    await fs.promises.unlink(link);
+    return { status: "removed", path: link };
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      return { status: "absent", path: link };
+    }
+    return { status: "failed", path: link, message: err.message };
+  }
+}
+
+module.exports = {
+  aliasPath,
+  resolveAgileflowBin,
+  localBinOnPath,
+  installAfAlias,
+  uninstallAfAlias,
+};