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

package/src/runtime/launch/worktree.js

@@ -0,0 +1,260 @@
+/**
+ * Create a git worktree for `agileflow launch new <name>`.
+ *
+ * Mirrors v3 `worktree-create.sh` defaults: sibling dir at
+ * `../<repo>-<sanitized-name>`, new branch `<sanitized-name>` off the
+ * current HEAD (or a caller-supplied base branch). Fails cleanly on the
+ * common pre-conditions: not in a repo, target dir already exists,
+ * branch already exists.
+ *
+ * `exec` is injectable so tests don't shell out to git. The exec must
+ * return `{ status: number, stdout: string, stderr: string }` (the
+ * shape `child_process.spawnSync({ encoding: "utf8" })` produces).
+ */
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+/**
+ * @typedef {{
+ *   status: number,
+ *   stdout: string,
+ *   stderr: string,
+ * }} GitExecResult
+ *
+ * @typedef {(args: string[]) => GitExecResult} GitExec
+ */
+
+const NAME_SANITIZE = /[^A-Za-z0-9._-]+/g;
+
+/**
+ * Build a typed error with a stable `code` so callers can branch on it.
+ *
+ * @param {string} message
+ * @param {string} code
+ * @returns {Error}
+ */
+function makeWorktreeError(message, code) {
+  const err = new Error(message);
+  /** @type {any} */ (err).code = code;
+  return err;
+}
+
+/**
+ * Default exec implementation — actually spawns `git` synchronously.
+ *
+ * @type {GitExec}
+ */
+function defaultGitExec(args) {
+  const result = spawnSync("git", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  return {
+    status: typeof result.status === "number" ? result.status : 1,
+    stdout: result.stdout || "",
+    stderr: result.stderr || "",
+  };
+}
+
+/**
+ * Sanitize a user-supplied worktree name. Lets alphanumerics, dot,
+ * underscore, and hyphen pass; collapses other characters to `-`.
+ *
+ * @param {string} name
+ * @returns {string}
+ */
+function sanitizeName(name) {
+  if (typeof name !== "string") return "";
+  return name.replace(NAME_SANITIZE, "-").replace(/^-+|-+$/g, "");
+}
+
+/**
+ * Create a new git worktree at `../<repo>-<name>` with branch `<name>`
+ * off the current HEAD (or `baseBranch` if supplied).
+ *
+ * @param {{
+ *   name: string,
+ *   baseBranch?: string,
+ *   exec?: GitExec,
+ *   fsExists?: (p: string) => boolean,
+ * }} opts
+ * @returns {{ path: string, branch: string, base: string }}
+ */
+function createWorktree(opts) {
+  const exec = opts.exec || defaultGitExec;
+  const exists = opts.fsExists || ((p) => fs.existsSync(p));
+
+  // 1. Must be inside a git work tree.
+  const top = exec(["rev-parse", "--show-toplevel"]);
+  if (top.status !== 0) {
+    throw makeWorktreeError(
+      `not in a git repository (${top.stderr.trim() || "rev-parse failed"})`,
+      "EWT_NOT_REPO",
+    );
+  }
+  const repoRoot = top.stdout.trim();
+  if (!repoRoot) {
+    throw makeWorktreeError(
+      "git rev-parse --show-toplevel returned no output",
+      "EWT_NOT_REPO",
+    );
+  }
+  const repoName = path.basename(repoRoot);
+  if (!repoName) {
+    // path.basename("/") is "" — degenerate setup (repo at filesystem
+    // root). Worktree path would resolve to "/-<name>" which is
+    // never what the user wants.
+    throw makeWorktreeError(
+      `repository root has no name (got "${repoRoot}") — cannot derive worktree path`,
+      "EWT_NOT_REPO",
+    );
+  }
+
+  // 2. Sanitize.
+  const safe = sanitizeName(opts.name || "");
+  if (!safe) {
+    throw makeWorktreeError(
+      "worktree name is empty after sanitizing",
+      "EWT_BAD_NAME",
+    );
+  }
+
+  // 3. Compute target dir; reject if it already exists.
+  const wtPath = path.resolve(repoRoot, "..", `${repoName}-${safe}`);
+  if (exists(wtPath)) {
+    throw makeWorktreeError(
+      `worktree directory already exists: ${wtPath}`,
+      "EWT_DIR_EXISTS",
+    );
+  }
+
+  // 4. Determine base branch.
+  let base = opts.baseBranch;
+  if (!base) {
+    const head = exec(["rev-parse", "--abbrev-ref", "HEAD"]);
+    if (head.status !== 0) {
+      throw makeWorktreeError(
+        `could not determine current branch: ${head.stderr.trim()}`,
+        "EWT_NO_HEAD",
+      );
+    }
+    base = head.stdout.trim();
+    if (base === "HEAD") {
+      // `git rev-parse --abbrev-ref HEAD` returns the literal string
+      // "HEAD" when the working tree is in a detached-HEAD state.
+      // Passing that to `git worktree add -b` would fail with a less
+      // helpful "fatal: invalid reference: HEAD" — fail clearly here.
+      throw makeWorktreeError(
+        "cannot create worktree from a detached HEAD — check out a branch first",
+        "EWT_NO_HEAD",
+      );
+    }
+  }
+
+  // 5. New branch must not already exist (otherwise `git worktree add -b`
+  // would fail with a less actionable error).
+  const refCheck = exec([
+    "show-ref",
+    "--verify",
+    "--quiet",
+    `refs/heads/${safe}`,
+  ]);
+  if (refCheck.status === 0) {
+    throw makeWorktreeError(
+      `branch '${safe}' already exists`,
+      "EWT_BRANCH_EXISTS",
+    );
+  }
+
+  // 6. Create it.
+  const wt = exec(["worktree", "add", "-b", safe, wtPath, base]);
+  if (wt.status !== 0) {
+    const stderr = wt.stderr.trim();
+    // Map git's "already exists" failures back to the typed codes our
+    // pre-check would have thrown — covers the TOCTOU window where
+    // another process created the dir or branch between our checks
+    // and `git worktree add`. The caller already has actionable hints
+    // wired up for EWT_DIR_EXISTS / EWT_BRANCH_EXISTS, but only the
+    // generic "re-run with DEBUG=1" for EWT_CREATE.
+    if (/refs\/heads\/.*already exists/i.test(stderr)) {
+      throw makeWorktreeError(
+        `branch '${safe}' already exists`,
+        "EWT_BRANCH_EXISTS",
+      );
+    }
+    if (/already exists/i.test(stderr)) {
+      throw makeWorktreeError(
+        `worktree directory already exists: ${wtPath}`,
+        "EWT_DIR_EXISTS",
+      );
+    }
+    throw makeWorktreeError(
+      `git worktree add failed: ${stderr || "unknown error"}`,
+      "EWT_CREATE",
+    );
+  }
+
+  return { path: wtPath, branch: safe, base };
+}
+
+/**
+ * Roll back a worktree created by `createWorktree`. Removes both the
+ * worktree directory (via `git worktree remove`) and the branch (via
+ * `git branch -D`). Used by `parallel-session.js` to keep the repo
+ * clean when a tmux session creation fails after the worktree was
+ * already established.
+ *
+ * Best-effort: surfaces partial failures via `removed`/`branchRemoved`
+ * flags so the caller can warn the user about what's left behind.
+ * Doesn't throw on individual git failures — the goal is rollback,
+ * not perfect cleanup.
+ *
+ * @param {{
+ *   path: string,
+ *   branch?: string,
+ *   exec?: GitExec,
+ * }} opts
+ * @returns {{
+ *   removed: boolean,
+ *   branchRemoved: boolean,
+ *   stderr: string,
+ * }}
+ */
+function removeWorktree(opts) {
+  const exec = opts.exec || defaultGitExec;
+  let removed = false;
+  let branchRemoved = false;
+  const stderrParts = [];
+
+  // `git worktree remove -f` so locked / dirty worktrees still get
+  // cleaned up — rollback is a "we just created this, take it back"
+  // operation so force is appropriate.
+  const wt = exec(["worktree", "remove", "-f", opts.path]);
+  if (wt.status === 0) {
+    removed = true;
+  } else if (wt.stderr) {
+    stderrParts.push(`worktree remove: ${wt.stderr.trim()}`);
+  }
+
+  // Branch removal: only attempted if a branch name was supplied.
+  // `git branch -D` force-deletes regardless of merge state.
+  if (opts.branch) {
+    const br = exec(["branch", "-D", opts.branch]);
+    if (br.status === 0) {
+      branchRemoved = true;
+    } else if (br.stderr) {
+      stderrParts.push(`branch -D: ${br.stderr.trim()}`);
+    }
+  }
+
+  return { removed, branchRemoved, stderr: stderrParts.join("; ") };
+}
+
+module.exports = {
+  createWorktree,
+  removeWorktree,
+  sanitizeName,
+  defaultGitExec,
+  makeWorktreeError,
+};

package/src/runtime/plugins/registry.js

@@ -5,13 +5,20 @@
  * (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 fs = require("fs");
+const path = require("path");
+const yaml = require("js-yaml");
 
-const PLUGINS_DIR = path.join(__dirname, '..', '..', '..', 'content', 'plugins');
+const PLUGINS_DIR = path.join(
+  __dirname,
+  "..",
+  "..",
+  "..",
+  "content",
+  "plugins",
+);
 
-const REQUIRED_FIELDS = ['id', 'name', 'description', 'version'];
+const REQUIRED_FIELDS = ["id", "name", "description", "version"];
 
 /**
  * @typedef {Object} PluginManifest
@@ -23,7 +30,6 @@ const REQUIRED_FIELDS = ['id', 'name', 'description', 'version'];
  * @property {boolean} [cannotDisable]
  * @property {string[]} [depends]
  * @property {{
- *   commands?: object[],
  *   skills?: object[],
  *   agents?: object[],
  *   hooks?: object[],
@@ -38,13 +44,13 @@ const REQUIRED_FIELDS = ['id', 'name', 'description', 'version'];
  * @returns {PluginManifest}
  */
 function loadPlugin(pluginDir) {
-  const manifestPath = path.join(pluginDir, 'plugin.yaml');
+  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');
+    raw = fs.readFileSync(manifestPath, "utf8");
   } catch (err) {
     throw new Error(`Cannot read ${manifestPath}: ${err.message}`);
   }
@@ -54,13 +60,13 @@ function loadPlugin(pluginDir) {
   } catch (err) {
     throw new Error(`Invalid YAML in ${manifestPath}: ${err.message}`);
   }
-  if (!parsed || typeof parsed !== 'object') {
+  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(', ')}`,
+      `Plugin ${path.basename(pluginDir)} missing required fields: ${missing.join(", ")}`,
     );
   }
   // `depends` is optional, but if present it MUST be an array — silently
@@ -83,7 +89,6 @@ function loadPlugin(pluginDir) {
     cannotDisable: Boolean(parsed.cannotDisable),
     depends,
     provides: parsed.provides || {
-      commands: [],
       skills: [],
       agents: [],
       hooks: [],

package/src/runtime/plugins/validator.js

@@ -26,13 +26,7 @@ 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',
-]);
+const VALID_PROVIDES_KEYS = new Set(["skills", "agents", "hooks", "templates"]);
 
 /**
  * Validate a single plugin manifest. Pure: no I/O.
@@ -43,18 +37,26 @@ const VALID_PROVIDES_KEYS = new Set([
 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.' }];
+  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.');
+  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).`,
@@ -62,52 +64,60 @@ function validatePlugin(plugin) {
   }
 
   // name
-  if (typeof plugin.name !== 'string' || !plugin.name.trim()) {
-    error('`name` must be a non-empty string.');
+  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.');
+  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.');
+    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).');
+  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).`);
+    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.enabledByDefault !== "boolean") {
+    error("`enabledByDefault` must be a boolean.");
   }
-  if (typeof plugin.cannotDisable !== 'boolean') {
-    error('`cannotDisable` 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`.');
+    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.');
+    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" || !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.');
+      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 (typeof dep === "string") {
         if (seen.has(dep)) {
           warn(`Duplicate dependency "${dep}" in \`depends\` (deduplicate).`);
         }
@@ -118,12 +128,16 @@ function validatePlugin(plugin) {
 
   // 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.');
+    if (typeof plugin.provides !== "object" || Array.isArray(plugin.provides)) {
+      error(
+        "`provides` must be an object with arrays of 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(', ')}.`);
+          warn(
+            `\`provides.${key}\` is not a recognized key — expected one of: ${[...VALID_PROVIDES_KEYS].join(", ")}.`,
+          );
         }
       }
       for (const key of VALID_PROVIDES_KEYS) {
@@ -154,10 +168,10 @@ function validatePluginSet(plugins) {
   }
   const ids = new Set();
   for (const p of plugins) {
-    if (typeof p.id === 'string') {
+    if (typeof p.id === "string") {
       if (ids.has(p.id)) {
         issues.push({
-          severity: 'error',
+          severity: "error",
           pluginId: p.id,
           message: `Duplicate plugin id "${p.id}".`,
         });
@@ -167,9 +181,9 @@ function validatePluginSet(plugins) {
   }
   for (const p of plugins) {
     for (const dep of p.depends || []) {
-      if (typeof dep === 'string' && !ids.has(dep)) {
+      if (typeof dep === "string" && !ids.has(dep)) {
         issues.push({
-          severity: 'error',
+          severity: "error",
           pluginId: p.id,
           message: `Depends on unknown plugin "${dep}".`,
         });
@@ -184,7 +198,7 @@ function validatePluginSet(plugins) {
  * @returns {boolean}
  */
 function hasErrors(issues) {
-  return issues.some((i) => i.severity === 'error');
+  return issues.some((i) => i.severity === "error");
 }
 
 module.exports = {