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

package/src/runtime/launch/resolve-cli.js

@@ -0,0 +1,56 @@
+/**
+ * Resolve the AI CLI to launch given a prefs object.
+ *
+ * Walks `[cli.preferred, ...cli.fallbackOrder]` (deduped, preferred first),
+ * looks up each id's descriptor in the known-CLI registry, and returns
+ * the first one whose binary actually resolves on PATH. Returns null if
+ * none of the user's configured CLIs are installed — the caller surfaces
+ * the actionable error.
+ *
+ * `exists` is injectable so tests don't shell out.
+ */
+const { commandExists: realCommandExists } = require("../../lib/path-check.js");
+const { findCli } = require("./detect-clis.js");
+
+/**
+ * Build the dedup'd lookup order: preferred first, then any fallback ids
+ * that weren't the preferred. Skips ids the user has explicitly removed
+ * from fallback (i.e., empty fallbackOrder means "only try preferred").
+ *
+ * @param {{ preferred: string, fallbackOrder: string[] }} cli
+ * @returns {string[]}
+ */
+function buildLookupOrder(cli) {
+  const seen = new Set();
+  const order = [];
+  const push = (id) => {
+    if (typeof id !== "string" || !id) return;
+    if (seen.has(id)) return;
+    seen.add(id);
+    order.push(id);
+  };
+  push(cli.preferred);
+  for (const id of cli.fallbackOrder || []) push(id);
+  return order;
+}
+
+/**
+ * @param {{ cli: { preferred: string, fallbackOrder: string[] } }} prefs
+ * @param {(name: string) => boolean} [exists]
+ * @returns {{
+ *   resolved: import('./detect-clis.js').CliDescriptor | null,
+ *   tried: string[],
+ * }}
+ */
+function resolveCli(prefs, exists = realCommandExists) {
+  const tried = buildLookupOrder(prefs.cli);
+  for (const id of tried) {
+    const desc = findCli(id);
+    if (desc && exists(desc.bin)) {
+      return { resolved: desc, tried };
+    }
+  }
+  return { resolved: null, tried };
+}
+
+module.exports = { resolveCli, buildLookupOrder };

package/src/runtime/launch/restore.js

@@ -0,0 +1,152 @@
+/**
+ * Bulk-restore tmux sessions from the registry after the tmux server
+ * died (typical cause: PC reboot). Walks every entry and re-creates
+ * the corresponding tmux session in the original cwd, wired to invoke
+ * `agileflow launch __exec <name>` so the per-CLI resume strategy
+ * fires automatically.
+ *
+ * Sessions that already exist on the running tmux server are skipped —
+ * restore is idempotent. Sessions whose original cwd no longer exists
+ * are skipped with a warning (e.g., user deleted the project dir).
+ *
+ * Returns counts so the caller can show a "restored N of M" summary.
+ */
+const fs = require("fs");
+const path = require("path");
+
+const {
+  defaultRunner,
+  sessionExists,
+  createSession,
+  applyKeybindPreset,
+  applyTabFormat,
+  detectTmuxVersion,
+} = require("./tmux.js");
+const { loadRegistry } = require("./session-registry.js");
+const { resolveAgileflowBin } = require("./alias-installer.js");
+
+/**
+ * @typedef {Object} RestoreResult
+ * @property {number} restored
+ * @property {number} alreadyAlive
+ * @property {number} skipped       - cwd missing or other unrecoverable state
+ * @property {number} failed
+ * @property {Array<{ name: string, reason: string }>} notes
+ */
+
+/**
+ * @param {{
+ *   prefs: import("./defaults.js").LaunchPrefs,
+ *   runner?: ReturnType<typeof defaultRunner>,
+ *   home?: string,
+ *   agileflowBin?: string,
+ *   existsSync?: (p: string) => boolean,
+ *   log?: (msg: string) => void,
+ *   onlyName?: string,
+ *   onlyNames?: string[],
+ * }} opts
+ * @returns {RestoreResult}
+ */
+function runRestore(opts) {
+  const runner = opts.runner || defaultRunner();
+  const existsSync = opts.existsSync || ((p) => fs.existsSync(p));
+  const log =
+    typeof opts.log === "function"
+      ? opts.log
+      : (msg) => {
+          // eslint-disable-next-line no-console
+          console.error(msg);
+        };
+  const agileflowBin = opts.agileflowBin || resolveAgileflowBin();
+
+  const reg = loadRegistry(opts.home);
+  /** @type {RestoreResult} */
+  const result = {
+    restored: 0,
+    alreadyAlive: 0,
+    skipped: 0,
+    failed: 0,
+    notes: [],
+  };
+
+  /** @type {import("./session-registry.js").SessionEntry[]} */
+  let entries;
+  if (opts.onlyName) {
+    entries = reg.sessions.filter((s) => s.name === opts.onlyName);
+  } else if (Array.isArray(opts.onlyNames)) {
+    // Use a Set for O(1) lookup so a 100-entry registry restoring a
+    // 20-entry subset stays linear, not quadratic.
+    const wanted = new Set(opts.onlyNames);
+    entries = reg.sessions.filter((s) => wanted.has(s.name));
+  } else {
+    entries = reg.sessions.slice();
+  }
+
+  for (const entry of entries) {
+    if (sessionExists(entry.name, runner)) {
+      result.alreadyAlive++;
+      continue;
+    }
+    if (!existsSync(entry.cwd)) {
+      result.skipped++;
+      result.notes.push({
+        name: entry.name,
+        reason: `cwd no longer exists: ${entry.cwd}`,
+      });
+      log(
+        `agileflow launch: skipping ${entry.name} — cwd missing (${entry.cwd})`,
+      );
+      continue;
+    }
+
+    // Tmux session command: invoke our own wrapper. tmux passes argv
+    // as separate words via the new-session args we hand it.
+    const wrapperArgs = [agileflowBin, "launch", "__exec", entry.name];
+    const create = createSession(
+      {
+        name: entry.name,
+        bin: wrapperArgs[0],
+        args: wrapperArgs.slice(1),
+        cwd: entry.cwd,
+        statusPosition: opts.prefs.tmux.statusPosition,
+      },
+      runner,
+    );
+    if (create.status !== 0) {
+      result.failed++;
+      const stderr = (create.stderr || "").trim() || "tmux new-session failed";
+      result.notes.push({ name: entry.name, reason: stderr });
+      log(`agileflow launch: failed to restore ${entry.name} — ${stderr}`);
+      continue;
+    }
+    // Apply the same per-session styling launchInTmux does for fresh
+    // sessions so the tab strip looks consistent on restore. Without
+    // this, restored sessions show tmux's default green status bar
+    // instead of the AgileFlow dark strip.
+    runner.runSync(["set-option", "-t", entry.name, "status", "1"]);
+    applyTabFormat(entry.name, runner, {
+      tmuxVersion: detectTmuxVersion(runner),
+    });
+    result.restored++;
+    log(`agileflow launch: restored session ${entry.name} (${entry.cwd})`);
+  }
+
+  // Apply keybinds once after the bulk restore so the user's preset is
+  // active across all the new sessions (tmux bind-key is server-wide).
+  if (
+    result.restored > 0 &&
+    opts.prefs.keybinds &&
+    opts.prefs.keybinds.preset
+  ) {
+    const kr = applyKeybindPreset(opts.prefs.keybinds.preset, runner, {
+      agileflowBin,
+    });
+    for (const f of kr.failures) {
+      log(`agileflow launch: keybind skipped during restore — ${f.hint}`);
+    }
+  }
+
+  return result;
+}
+
+module.exports = { runRestore };

package/src/runtime/launch/schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://agileflow.dev/schemas/launch-prefs.v1.json",
+  "title": "AgileFlow launch preferences",
+  "description": "User-level preferences for `agileflow launch` (multi-CLI tmux wrapper). Lives at ~/.agileflow/launch-prefs.json.",
+  "type": "object",
+  "required": ["version", "cli", "tmux", "keybinds", "aliases", "pinned"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "cli": {
+      "type": "object",
+      "required": ["preferred", "fallbackOrder"],
+      "additionalProperties": false,
+      "properties": {
+        "preferred": {
+          "type": "string",
+          "enum": ["claude", "codex", "cursor-agent", "aider"]
+        },
+        "fallbackOrder": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["claude", "codex", "cursor-agent", "aider"]
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "tmux": {
+      "type": "object",
+      "required": ["enabled", "statusPosition"],
+      "additionalProperties": false,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "statusPosition": { "type": "string", "enum": ["top", "bottom"] }
+      }
+    },
+    "keybinds": {
+      "type": "object",
+      "required": ["preset"],
+      "additionalProperties": false,
+      "properties": {
+        "preset": {
+          "type": "string",
+          "enum": ["default", "minimal", "none"]
+        }
+      }
+    },
+    "aliases": {
+      "type": "object",
+      "required": ["af"],
+      "additionalProperties": false,
+      "properties": {
+        "af": {
+          "type": "object",
+          "required": ["enabled"],
+          "additionalProperties": false,
+          "properties": {
+            "enabled": { "type": "boolean" }
+          }
+        }
+      }
+    },
+    "pinned": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/src/runtime/launch/session-lifecycle.js

@@ -0,0 +1,313 @@
+/**
+ * Pure helpers behind `agileflow launch ls / kill / attach / prune`.
+ *
+ * Composes already-built primitives:
+ *   - registry: load / find / forget
+ *   - tmux: sessionExists / killSession / attachSession
+ *   - restore: runRestore({ onlyName }) for lazy re-creation
+ *   - worktree: removeWorktree for paired cleanup
+ *
+ * Every helper accepts a `deps` bag with injectable callables so the unit
+ * tests don't have to spawn tmux or touch a real registry. The CLI
+ * wrappers in `commands/launch.js` are the only place that wires in the
+ * real implementations.
+ */
+const fs = require("fs");
+
+const {
+  loadRegistry,
+  findSession,
+  forgetSession,
+} = require("./session-registry.js");
+const {
+  defaultRunner,
+  sessionExists: tmuxSessionExists,
+  killSession: tmuxKillSession,
+  attachSession: tmuxAttachSession,
+} = require("./tmux.js");
+const { removeWorktree } = require("./worktree.js");
+const { runRestore } = require("./restore.js");
+
+/**
+ * @typedef {import("./session-registry.js").SessionEntry & {
+ *   state: 'alive' | 'dormant' | 'missing-cwd',
+ * }} ClassifiedSession
+ */
+
+/**
+ * Return every registered session, each tagged with its current state:
+ *   - alive       → tmux has the session
+ *   - dormant     → registry has it, cwd still exists, tmux doesn't
+ *   - missing-cwd → registry has it but the cwd has been deleted
+ *
+ * Read-only — never mutates the registry. Worktree-only orphan detection
+ * lives in doctor.js; this helper just exposes raw state.
+ *
+ * @param {{
+ *   home?: string,
+ *   runner?: import("./tmux.js").TmuxRunner,
+ *   sessionExistsFn?: typeof tmuxSessionExists,
+ *   existsSync?: (p: string) => boolean,
+ * }} [deps]
+ * @returns {ClassifiedSession[]}
+ */
+function listSessions(deps = {}) {
+  const runner = deps.runner || defaultRunner();
+  const sessionExistsFn = deps.sessionExistsFn || tmuxSessionExists;
+  const existsSync = deps.existsSync || ((p) => fs.existsSync(p));
+  const reg = loadRegistry(deps.home);
+  return reg.sessions.map((entry) => {
+    const alive = sessionExistsFn(entry.name, runner);
+    const cwdExists = existsSync(entry.cwd);
+    /** @type {'alive' | 'dormant' | 'missing-cwd'} */
+    const state = alive ? "alive" : cwdExists ? "dormant" : "missing-cwd";
+    return { ...entry, state };
+  });
+}
+
+/**
+ * Kill a tmux session (if alive) and forget the registry entry. When
+ * `removeWorktree` is true and the entry has worktree metadata pointing
+ * at a directory that still exists, also remove the worktree + branch.
+ *
+ * The worktree removal is gated on caller intent rather than auto-applied
+ * so the CLI wrapper can prompt the user before destructive cleanup.
+ *
+ * Return shape lets the wrapper render a precise outcome without
+ * re-querying state:
+ *   - ok: false + reason="not in registry"  → unknown name
+ *   - ok: true + wasAlive: boolean          → kill attempted
+ *   - ok: true + worktree: { removed, branchRemoved, stderr }
+ *                                           → worktree cleanup attempted
+ *
+ * @param {{
+ *   name: string,
+ *   removeWorktree?: boolean,
+ *   home?: string,
+ *   runner?: import("./tmux.js").TmuxRunner,
+ *   sessionExistsFn?: typeof tmuxSessionExists,
+ *   killSessionFn?: typeof tmuxKillSession,
+ *   removeWorktreeFn?: typeof removeWorktree,
+ *   existsSync?: (p: string) => boolean,
+ * }} deps
+ * @returns {{
+ *   ok: boolean,
+ *   reason?: string,
+ *   wasAlive?: boolean,
+ *   worktree?: ReturnType<typeof removeWorktree> | null,
+ * }}
+ */
+function killBySessionName(deps) {
+  const runner = deps.runner || defaultRunner();
+  const sessionExistsFn = deps.sessionExistsFn || tmuxSessionExists;
+  const killFn = deps.killSessionFn || tmuxKillSession;
+  const removeWtFn = deps.removeWorktreeFn || removeWorktree;
+  const existsSync = deps.existsSync || ((p) => fs.existsSync(p));
+
+  const entry = findSession(deps.name, deps.home);
+  if (!entry) return { ok: false, reason: "not in registry" };
+
+  // Best-effort kill: ignore the return value because we proceed with
+  // forget regardless. A failed kill on an alive session leaves a tmux
+  // orphan, but the registry stays consistent.
+  const wasAlive = sessionExistsFn(entry.name, runner);
+  if (wasAlive) killFn(entry.name, runner);
+
+  // forgetSession can throw if the lockfile can't be acquired (registry
+  // contention from concurrent __exec processes). Surface that as a
+  // structured failure instead of letting the exception escape — callers
+  // expect this helper to honor the { ok, reason, ... } contract.
+  try {
+    forgetSession(deps.name, deps.home);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `could not update registry: ${err && err.message ? err.message : String(err)}`,
+      wasAlive,
+    };
+  }
+
+  /** @type {ReturnType<typeof removeWorktree> | null} */
+  let wt = null;
+  if (
+    deps.removeWorktree &&
+    entry.worktree &&
+    entry.worktree.path &&
+    existsSync(entry.worktree.path)
+  ) {
+    wt = removeWtFn({
+      path: entry.worktree.path,
+      branch: entry.worktree.branch || undefined,
+    });
+  }
+  return { ok: true, wasAlive, worktree: wt };
+}
+
+/**
+ * Attach to a registered session, lazily restoring it from the registry
+ * if the tmux server doesn't currently have it. The lazy-restore step is
+ * what makes this useful after a reboot — `agileflow launch attach foo`
+ * Just Works whether or not foo is currently on the server.
+ *
+ * Failure cases (return { ok: false, reason }):
+ *   - "not in registry"   → unknown name
+ *   - "cwd missing"       → original directory deleted; can't restore
+ *   - "could not restore" → tmux refused new-session (notes carries why)
+ *
+ * @param {{
+ *   name: string,
+ *   home?: string,
+ *   prefs: import("./defaults.js").LaunchPrefs,
+ *   agileflowBin?: string,
+ *   runner?: import("./tmux.js").TmuxRunner,
+ *   sessionExistsFn?: typeof tmuxSessionExists,
+ *   attachSessionFn?: typeof tmuxAttachSession,
+ *   runRestoreImpl?: typeof runRestore,
+ *   existsSync?: (p: string) => boolean,
+ * }} deps
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   reason?: string,
+ *   restored?: boolean,
+ *   attach?: Awaited<ReturnType<typeof tmuxAttachSession>>,
+ *   notes?: Array<{ name: string, reason: string }>,
+ * }>}
+ */
+async function attachByName(deps) {
+  const runner = deps.runner || defaultRunner();
+  const sessionExistsFn = deps.sessionExistsFn || tmuxSessionExists;
+  const attachFn = deps.attachSessionFn || tmuxAttachSession;
+  const restoreFn = deps.runRestoreImpl || runRestore;
+  const existsSync = deps.existsSync || ((p) => fs.existsSync(p));
+
+  const entry = findSession(deps.name, deps.home);
+  if (!entry) return { ok: false, reason: "not in registry" };
+  if (!existsSync(entry.cwd)) return { ok: false, reason: "cwd missing" };
+
+  let restored = false;
+  if (!sessionExistsFn(entry.name, runner)) {
+    const r = restoreFn({
+      prefs: deps.prefs,
+      runner,
+      home: deps.home,
+      agileflowBin: deps.agileflowBin,
+      onlyName: deps.name,
+    });
+    if (r.restored === 0) {
+      return { ok: false, reason: "could not restore", notes: r.notes };
+    }
+    restored = true;
+  }
+  const attach = await attachFn(entry.name, runner);
+  return { ok: true, restored, attach };
+}
+
+/**
+ * Return the registry entries that are safe to forget in bulk:
+ *   - dormant + cwd missing (project deleted)
+ *   - dormant + worktree dir missing (someone `git worktree remove`'d it)
+ *
+ * Alive sessions are NEVER candidates. Dormant entries with a live cwd
+ * stay too — the user likely just shut tmux down and intends to restore.
+ *
+ * Each candidate is annotated with `reason` so the CLI wrapper can show
+ * the user why it's offering the cleanup.
+ *
+ * @param {{
+ *   home?: string,
+ *   runner?: import("./tmux.js").TmuxRunner,
+ *   sessionExistsFn?: typeof tmuxSessionExists,
+ *   existsSync?: (p: string) => boolean,
+ * }} [deps]
+ * @returns {Array<ClassifiedSession & { reason: string }>}
+ */
+function pruneCandidates(deps = {}) {
+  const existsSync = deps.existsSync || ((p) => fs.existsSync(p));
+  const classified = listSessions(deps);
+  /** @type {Array<ClassifiedSession & { reason: string }>} */
+  const out = [];
+  for (const c of classified) {
+    if (c.state === "alive") continue;
+    // Pinned entries are explicit "always keep" — never surface them as
+    // prune candidates, even if their cwd disappeared. The user has to
+    // unpin first if they really want to forget.
+    if (c.pinned) continue;
+    if (c.state === "missing-cwd") {
+      out.push({ ...c, reason: `cwd missing: ${c.cwd}` });
+      continue;
+    }
+    if (c.worktree && c.worktree.path && !existsSync(c.worktree.path)) {
+      out.push({
+        ...c,
+        reason: `worktree dir missing: ${c.worktree.path}`,
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * Apply a prune selection: forget each named entry, optionally remove
+ * its worktree (only when the path still exists — pruneCandidates
+ * surfaces missing-dir cases, but we don't want to issue `git worktree
+ * remove` on something the user already cleaned up manually).
+ *
+ * Returns counts so the CLI wrapper can print a one-line summary.
+ *
+ * @param {{
+ *   selections: Array<{ name: string }>,
+ *   removeWorktrees?: boolean,
+ *   home?: string,
+ *   removeWorktreeFn?: typeof removeWorktree,
+ *   existsSync?: (p: string) => boolean,
+ * }} deps
+ * @returns {{ forgotten: number, worktreesRemoved: number, errors: Array<{ name: string, error: string }> }}
+ */
+function applyPrune(deps) {
+  const removeWtFn = deps.removeWorktreeFn || removeWorktree;
+  const existsSync = deps.existsSync || ((p) => fs.existsSync(p));
+  let forgotten = 0;
+  let worktreesRemoved = 0;
+  /** @type {Array<{ name: string, error: string }>} */
+  const errors = [];
+
+  for (const sel of deps.selections || []) {
+    const entry = findSession(sel.name, deps.home);
+    if (!entry) {
+      // Concurrent prune from another process? Skip; nothing to do.
+      continue;
+    }
+    if (
+      deps.removeWorktrees &&
+      entry.worktree &&
+      entry.worktree.path &&
+      existsSync(entry.worktree.path)
+    ) {
+      try {
+        const r = removeWtFn({
+          path: entry.worktree.path,
+          branch: entry.worktree.branch || undefined,
+        });
+        if (r.removed) worktreesRemoved++;
+        if (r.stderr) errors.push({ name: sel.name, error: r.stderr });
+      } catch (err) {
+        errors.push({ name: sel.name, error: err.message || String(err) });
+      }
+    }
+    try {
+      forgetSession(sel.name, deps.home);
+      forgotten++;
+    } catch (err) {
+      errors.push({ name: sel.name, error: err.message || String(err) });
+    }
+  }
+  return { forgotten, worktreesRemoved, errors };
+}
+
+module.exports = {
+  listSessions,
+  killBySessionName,
+  attachByName,
+  pruneCandidates,
+  applyPrune,
+};