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

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

@@ -0,0 +1,244 @@
+/**
+ * Per-CLI resume strategy table.
+ *
+ * Each entry tells the __exec wrapper:
+ *   - `resumeArgs(uuid)`        — argv to append for "resume this conversation"
+ *   - `captureUuid(cwd, opts)`  — after the CLI exits, return the UUID of the
+ *                                 newest conversation associated with this cwd
+ *                                 so we can store it back in the registry
+ *
+ * Strategies covered:
+ *   - claude:        UUID-based; conversations are jsonl files under
+ *                    `~/.claude/projects/<encoded-cwd>/`. Mirrors v3
+ *                    `claude-smart.sh`.
+ *   - codex:         `codex resume --last` resumes the most-recent
+ *                    session. Codex doesn't (yet) take a UUID positionally
+ *                    in a stable way per-cwd, so MVP uses `--last`. Better:
+ *                    parse jsonl files under ~/.codex/sessions/ and target by id (deferred).
+ *   - cursor-agent:  no published resume convention. Restart fresh.
+ *   - aider:         auto-restores from `.aider.chat.history.md` in cwd.
+ *                    No flag needed.
+ *
+ * All filesystem reads are injectable via `opts.fs` for tests.
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Encode a cwd into Claude's project directory naming convention.
+ * Claude stores conversations under `~/.claude/projects/<encoded>/`
+ * where `<encoded>` is the absolute path with `/` replaced by `-`
+ * (and a leading `-` for the root).
+ *
+ * @param {string} cwd
+ * @returns {string}
+ */
+function encodeClaudeProjectDir(cwd) {
+  // Normalize backslashes to forward slashes first so Windows paths
+  // (`C:\Users\me\app`) and POSIX paths (`/home/me/app`) hit the same
+  // encoding path. Then strip leading slashes and convert any remaining
+  // separator to `-`. Claude itself produces names like
+  // `-home-user-myproject` for `/home/user/myproject`.
+  const slashed = cwd.replace(/\\/g, "/");
+  const normalized = slashed.replace(/^\/+/, "");
+  return "-" + normalized.replace(/\//g, "-");
+}
+
+/**
+ * Find the newest non-agent .jsonl file in a Claude project directory
+ * and return its UUID (filename minus `.jsonl`). Returns null when no
+ * conversation has been recorded yet.
+ *
+ * @param {string} cwd
+ * @param {{
+ *   home?: string,
+ *   readdirSync?: typeof fs.readdirSync,
+ *   statSync?: typeof fs.statSync,
+ * }} [opts]
+ * @returns {string | null}
+ */
+function captureClaudeUuid(cwd, opts = {}) {
+  const home = opts.home || os.homedir();
+  const readdirSync = opts.readdirSync || fs.readdirSync;
+  const statSync = opts.statSync || fs.statSync;
+  const projectDir = path.join(
+    home,
+    ".claude",
+    "projects",
+    encodeClaudeProjectDir(cwd),
+  );
+  /** @type {string[]} */
+  let entries;
+  try {
+    entries = readdirSync(projectDir);
+  } catch {
+    return null;
+  }
+  let bestUuid = null;
+  let bestMtime = -Infinity;
+  for (const entry of entries) {
+    if (!entry.endsWith(".jsonl")) continue;
+    // Skip agent transcripts — those are sub-conversations spawned by
+    // a parent claude session, not the main conversation we want to
+    // resume. v3 used the same `agent-` prefix filter.
+    if (entry.startsWith("agent-")) continue;
+    const full = path.join(projectDir, entry);
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    const mtime = stat.mtimeMs || 0;
+    if (mtime > bestMtime) {
+      bestMtime = mtime;
+      bestUuid = entry.slice(0, -".jsonl".length);
+    }
+  }
+  return bestUuid;
+}
+
+/**
+ * Find the newest codex session whose first-line `payload.cwd` matches
+ * the given working directory.
+ *
+ * Codex stores sessions under
+ * `~/.codex/sessions/<YYYY>/<MM>/<DD>/rollout-<timestamp>-<UUID>.jsonl`.
+ * The first JSONL line is a `session_meta` record containing
+ * `payload.cwd` and `payload.id`. Walking that tree once per launch
+ * isn't free, but it's still a few dozen files even for active users
+ * and only runs after a session exits — so the cost is amortized.
+ *
+ * @param {string} cwd
+ * @param {{
+ *   home?: string,
+ *   readdirSync?: typeof fs.readdirSync,
+ *   statSync?: typeof fs.statSync,
+ *   readFileSync?: typeof fs.readFileSync,
+ * }} [opts]
+ * @returns {string | null}
+ */
+function captureCodexUuid(cwd, opts = {}) {
+  const home = opts.home || os.homedir();
+  const readdirSync = opts.readdirSync || fs.readdirSync;
+  const statSync = opts.statSync || fs.statSync;
+  const readFileSync = opts.readFileSync || fs.readFileSync;
+
+  const sessionsRoot = path.join(home, ".codex", "sessions");
+  /** @type {string[]} */
+  const jsonlFiles = [];
+
+  // Recurse year → month → day → files. Tree depth is fixed at 3.
+  /** @param {string} dir */
+  function collect(dir) {
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        collect(full);
+      } else if (ent.isFile() && ent.name.endsWith(".jsonl")) {
+        jsonlFiles.push(full);
+      }
+    }
+  }
+  collect(sessionsRoot);
+
+  let bestUuid = null;
+  let bestMtime = -Infinity;
+  for (const file of jsonlFiles) {
+    let stat;
+    try {
+      stat = statSync(file);
+    } catch {
+      continue;
+    }
+    const mtime = typeof stat.mtimeMs === "number" ? stat.mtimeMs : 0;
+    if (mtime <= bestMtime) continue;
+    // Cheap match: read just the first line.
+    let head;
+    try {
+      head = readFileSync(file, "utf8").split("\n", 1)[0];
+    } catch {
+      continue;
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(head);
+    } catch {
+      continue;
+    }
+    const payload = parsed && parsed.payload;
+    if (!payload || typeof payload !== "object") continue;
+    if (payload.cwd !== cwd) continue;
+    if (typeof payload.id !== "string" || !payload.id) continue;
+    bestUuid = payload.id;
+    bestMtime = mtime;
+  }
+  return bestUuid;
+}
+
+/**
+ * @typedef {Object} ResumeStrategy
+ * @property {(uuid: string | null) => string[]} resumeArgs
+ * @property {(cwd: string, opts?: any) => string | null} captureUuid
+ */
+
+/** @type {Record<string, ResumeStrategy>} */
+const RESUME_STRATEGIES = {
+  claude: {
+    resumeArgs: (uuid) => (uuid ? ["--resume", uuid] : []),
+    captureUuid: captureClaudeUuid,
+  },
+  codex: {
+    // With a stored UUID we resume that specific session, which is
+    // critical when the user has multiple parallel codex sessions
+    // across different cwds — `resume --last` would pick whichever
+    // they touched most recently, not the one tied to THIS session.
+    // Without a UUID (first launch in a cwd, or capture failed) we
+    // fall back to `--last`.
+    resumeArgs: (uuid) => {
+      if (uuid) return ["resume", uuid];
+      return ["resume", "--last"];
+    },
+    captureUuid: captureCodexUuid,
+  },
+  "cursor-agent": {
+    resumeArgs: () => [],
+    captureUuid: () => null,
+  },
+  aider: {
+    // aider auto-restores the cwd's chat history from
+    // `.aider.chat.history.md` on every invocation. No flag needed.
+    resumeArgs: () => [],
+    captureUuid: () => null,
+  },
+};
+
+/**
+ * Pick a strategy by CLI id; unknown CLIs get the "spawn fresh" no-op.
+ *
+ * @param {string} cli
+ * @returns {ResumeStrategy}
+ */
+function getResumeStrategy(cli) {
+  return (
+    RESUME_STRATEGIES[cli] || {
+      resumeArgs: () => [],
+      captureUuid: () => null,
+    }
+  );
+}
+
+module.exports = {
+  RESUME_STRATEGIES,
+  getResumeStrategy,
+  captureClaudeUuid,
+  captureCodexUuid,
+  encodeClaudeProjectDir,
+};

package/src/runtime/launch/closed-windows.js

@@ -0,0 +1,338 @@
+/**
+ * Closed-window FIFO log for `agileflow launch`.
+ *
+ * Backs the `Alt+T → reopen last closed tab` keybind. When the user
+ * closes a window via `Alt+w`, the `__close-window` subcommand
+ * captures `#W` (name) + `#{pane_current_path}` (cwd) and pushes them
+ * here BEFORE issuing `kill-window`. `__restore-window` pops the most
+ * recent entry and runs `new-window -c <cwd> -n <name>`.
+ *
+ * On-disk shape (`~/.agileflow/launch-closed-windows.json`):
+ *   {
+ *     "version": 1,
+ *     "sessions": {
+ *       "claude-myapp": [
+ *         { "id": "ab12cd", "name": "src", "cwd": "/...", "closedAt": "..." }
+ *       ]
+ *     }
+ *   }
+ *
+ * Per-session stacks are isolated so closing a tab in session A
+ * doesn't pollute session B's restore history. Each stack is capped
+ * at MAX_PER_SESSION entries (oldest evicted on push).
+ *
+ * Concurrency: same O_EXCL lock pattern as session-registry.js — two
+ * sessions running `__close-window` simultaneously won't lose each
+ * other's entries.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const crypto = require("crypto");
+
+const FILENAME = "launch-closed-windows.json";
+const LOCK_SUFFIX = ".lock";
+const LOCK_STALE_MS = 5000;
+const LOCK_MAX_ATTEMPTS = 100;
+const LOCK_RETRY_MS = 10;
+const MAX_PER_SESSION = 20;
+
+/**
+ * @typedef {Object} ClosedEntry
+ * @property {string} id          - short random id for log/debug, not used for lookup
+ * @property {string} name        - tmux window name (#W) at close time
+ * @property {string} cwd         - pane's working directory at close time
+ * @property {string} closedAt    - ISO timestamp
+ *
+ * @typedef {Object} ClosedLogShape
+ * @property {1} version
+ * @property {Record<string, ClosedEntry[]>} sessions
+ */
+
+/** @param {number} ms */
+function busyWait(ms) {
+  const target = Date.now() + ms;
+  while (Date.now() < target) {
+    /* spin */
+  }
+}
+
+/**
+ * @param {string} [home]
+ * @returns {string}
+ */
+function logPath(home) {
+  return path.join(home || os.homedir(), ".agileflow", FILENAME);
+}
+
+/** @returns {ClosedLogShape} */
+function emptyLog() {
+  return { version: 1, sessions: {} };
+}
+
+/**
+ * O_EXCL lock around `fn`. Same retry / stale-takeover policy as
+ * session-registry's withRegistryLock. Lock file lives next to the
+ * log file with a `.lock` suffix so the two registries' locks don't
+ * collide.
+ *
+ * @template T
+ * @param {string | undefined} home
+ * @param {() => T} fn
+ * @returns {T}
+ */
+function withLock(home, fn) {
+  const lockFile = logPath(home) + LOCK_SUFFIX;
+  fs.mkdirSync(path.dirname(lockFile), { recursive: true });
+  /** @type {number | null} */
+  let lockFd = null;
+  for (let attempt = 0; attempt < LOCK_MAX_ATTEMPTS; attempt++) {
+    try {
+      lockFd = fs.openSync(lockFile, "wx");
+      break;
+    } catch (err) {
+      if (!err || err.code !== "EEXIST") throw err;
+      try {
+        const stat = fs.statSync(lockFile);
+        if (Date.now() - (stat.mtimeMs || 0) > LOCK_STALE_MS) {
+          try {
+            fs.unlinkSync(lockFile);
+          } catch {
+            /* swallow */
+          }
+          continue;
+        }
+      } catch {
+        /* lockfile vanished between EEXIST and stat — loop */
+      }
+      busyWait(LOCK_RETRY_MS);
+    }
+  }
+  if (lockFd === null) {
+    throw new Error(
+      `could not acquire launch-closed-windows lock after ${LOCK_MAX_ATTEMPTS} attempts`,
+    );
+  }
+  try {
+    return fn();
+  } finally {
+    try {
+      fs.closeSync(lockFd);
+    } catch {
+      /* swallow */
+    }
+    try {
+      fs.unlinkSync(lockFile);
+    } catch {
+      /* swallow */
+    }
+  }
+}
+
+/**
+ * Read the log, forgiving on any I/O or JSON failure (same posture as
+ * session-registry). Malformed file = empty log; the user shouldn't be
+ * blocked from closing or restoring tabs because of corruption.
+ *
+ * @param {string} [home]
+ * @returns {ClosedLogShape}
+ */
+function loadLog(home) {
+  const file = logPath(home);
+  let raw;
+  try {
+    raw = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") return emptyLog();
+    return emptyLog();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return emptyLog();
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return emptyLog();
+  }
+  const sessions =
+    parsed.sessions && typeof parsed.sessions === "object"
+      ? parsed.sessions
+      : {};
+  /** @type {Record<string, ClosedEntry[]>} */
+  const sane = {};
+  for (const [sessionName, list] of Object.entries(sessions)) {
+    if (!Array.isArray(list)) continue;
+    /** @type {ClosedEntry[]} */
+    const cleaned = [];
+    for (const e of list) {
+      if (!e || typeof e !== "object") continue;
+      if (typeof e.name !== "string") continue;
+      if (typeof e.cwd !== "string" || !e.cwd) continue;
+      cleaned.push({
+        id: typeof e.id === "string" ? e.id : shortId(),
+        name: e.name,
+        cwd: e.cwd,
+        closedAt: typeof e.closedAt === "string" ? e.closedAt : "",
+      });
+    }
+    if (cleaned.length > 0) sane[sessionName] = cleaned;
+  }
+  return { version: 1, sessions: sane };
+}
+
+/**
+ * Atomic write via tmp + rename. Mirrors session-registry's pattern.
+ *
+ * @param {ClosedLogShape} log
+ * @param {string} [home]
+ * @returns {string}
+ */
+function writeLog(log, home) {
+  const file = logPath(home);
+  const dir = path.dirname(file);
+  const tmp = path.join(dir, `.${FILENAME}.tmp-${process.pid}`);
+  const content = JSON.stringify(log, null, 2) + "\n";
+  fs.mkdirSync(dir, { recursive: true });
+  try {
+    fs.writeFileSync(tmp, content, "utf8");
+    fs.renameSync(tmp, file);
+  } catch (err) {
+    try {
+      fs.unlinkSync(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+  return file;
+}
+
+/** @returns {string} */
+function shortId() {
+  return crypto.randomBytes(3).toString("hex");
+}
+
+/**
+ * Push a closed window onto the FIFO for `sessionName`. Returns the
+ * pushed entry (so callers can log/inspect it). Caps the per-session
+ * stack at MAX_PER_SESSION; the oldest entry is evicted when over.
+ *
+ * @param {{ sessionName: string, name: string, cwd: string }} args
+ * @param {string} [home]
+ * @returns {ClosedEntry}
+ */
+function pushClosed(args, home) {
+  if (!args || typeof args !== "object") {
+    throw new TypeError("pushClosed: args required");
+  }
+  if (typeof args.sessionName !== "string" || !args.sessionName) {
+    throw new TypeError("pushClosed: sessionName must be a non-empty string");
+  }
+  if (typeof args.name !== "string") {
+    throw new TypeError("pushClosed: name must be a string");
+  }
+  if (typeof args.cwd !== "string" || !args.cwd) {
+    throw new TypeError("pushClosed: cwd must be a non-empty string");
+  }
+  /** @type {ClosedEntry} */
+  const entry = {
+    id: shortId(),
+    name: args.name,
+    cwd: args.cwd,
+    closedAt: new Date().toISOString(),
+  };
+  withLock(home, () => {
+    const log = loadLog(home);
+    const list = log.sessions[args.sessionName] || [];
+    list.push(entry);
+    while (list.length > MAX_PER_SESSION) list.shift();
+    log.sessions[args.sessionName] = list;
+    writeLog(log, home);
+  });
+  return entry;
+}
+
+/**
+ * Pop the most recent closed entry for `sessionName`. Returns null
+ * when the stack is empty (or the session never had any). Done under
+ * the lock so two concurrent `__restore-window` processes don't both
+ * resurrect the same entry.
+ *
+ * @param {string} sessionName
+ * @param {string} [home]
+ * @returns {ClosedEntry | null}
+ */
+function popClosed(sessionName, home) {
+  if (typeof sessionName !== "string" || !sessionName) return null;
+  return withLock(home, () => {
+    const log = loadLog(home);
+    const list = log.sessions[sessionName];
+    if (!list || list.length === 0) return null;
+    const entry = list.pop();
+    if (list.length === 0) delete log.sessions[sessionName];
+    else log.sessions[sessionName] = list;
+    writeLog(log, home);
+    return entry || null;
+  });
+}
+
+/**
+ * Look at the most recent entry without removing it. Cheap read —
+ * no lock taken; readers tolerate a brief inconsistency window with
+ * concurrent writers.
+ *
+ * @param {string} sessionName
+ * @param {string} [home]
+ * @returns {ClosedEntry | null}
+ */
+function peekClosed(sessionName, home) {
+  if (typeof sessionName !== "string" || !sessionName) return null;
+  const log = loadLog(home);
+  const list = log.sessions[sessionName];
+  if (!list || list.length === 0) return null;
+  return list[list.length - 1];
+}
+
+/**
+ * Sweep entries older than `maxAgeMs` across all sessions. Returns the
+ * number of entries removed. Intended for a future doctor/prune
+ * integration; safe to call from anywhere.
+ *
+ * @param {number} maxAgeMs
+ * @param {string} [home]
+ * @returns {number}
+ */
+function clearOlderThan(maxAgeMs, home) {
+  if (typeof maxAgeMs !== "number" || maxAgeMs < 0) return 0;
+  return withLock(home, () => {
+    const log = loadLog(home);
+    const cutoff = Date.now() - maxAgeMs;
+    let removed = 0;
+    for (const [sessionName, list] of Object.entries(log.sessions)) {
+      const kept = list.filter((e) => {
+        const t = Date.parse(e.closedAt || "");
+        if (Number.isNaN(t)) return true; // keep entries with no parseable timestamp
+        return t >= cutoff;
+      });
+      removed += list.length - kept.length;
+      if (kept.length === 0) delete log.sessions[sessionName];
+      else log.sessions[sessionName] = kept;
+    }
+    if (removed > 0) writeLog(log, home);
+    return removed;
+  });
+}
+
+module.exports = {
+  FILENAME,
+  MAX_PER_SESSION,
+  logPath,
+  emptyLog,
+  loadLog,
+  writeLog,
+  pushClosed,
+  popClosed,
+  peekClosed,
+  clearOlderThan,
+};

package/src/runtime/launch/defaults.js

@@ -0,0 +1,66 @@
+/**
+ * Default preferences for `agileflow launch`.
+ *
+ * `launch-prefs.json` is the first user-level config in v4 (lives under
+ * `~/.agileflow/`). Returned when the file is absent and merged into a
+ * partial user file so missing keys take sensible values.
+ *
+ * @typedef {Object} LaunchCliPrefs
+ * @property {string} preferred                     - CLI to invoke by default
+ * @property {string[]} fallbackOrder               - order to try if preferred is missing
+ *
+ * @typedef {Object} LaunchTmuxPrefs
+ * @property {boolean} enabled                      - false skips tmux entirely
+ * @property {'top' | 'bottom'} statusPosition      - tmux status-position value
+ *
+ * @typedef {Object} LaunchKeybindPrefs
+ * @property {'default' | 'minimal' | 'none'} preset - keybind preset name
+ *
+ * @typedef {Object} LaunchAliasPref
+ * @property {boolean} enabled  - install `af` symlink to ~/.local/bin/af
+ *
+ * @typedef {Object} LaunchAliasesPrefs
+ * @property {LaunchAliasPref} af
+ *
+ * @typedef {Object} LaunchPrefs
+ * @property {1} version
+ * @property {LaunchCliPrefs} cli
+ * @property {LaunchTmuxPrefs} tmux
+ * @property {LaunchKeybindPrefs} keybinds
+ * @property {LaunchAliasesPrefs} aliases
+ * @property {string[]} pinned                      - reserved for slice 3 (pinning UI)
+ * @property {string} [lastUpdated]                 - ISO timestamp stamped by writePrefs
+ */
+
+const KNOWN_CLI_IDS = ["claude", "codex", "cursor-agent", "aider"];
+const STATUS_POSITIONS = ["top", "bottom"];
+const KEYBIND_PRESETS = ["default", "minimal", "none"];
+
+/** @returns {LaunchPrefs} */
+function defaultPrefs() {
+  return {
+    version: 1,
+    cli: {
+      preferred: "claude",
+      fallbackOrder: [...KNOWN_CLI_IDS],
+    },
+    tmux: {
+      enabled: true,
+      statusPosition: "bottom",
+    },
+    keybinds: {
+      preset: "default",
+    },
+    aliases: {
+      af: { enabled: false },
+    },
+    pinned: [],
+  };
+}
+
+module.exports = {
+  defaultPrefs,
+  KNOWN_CLI_IDS,
+  STATUS_POSITIONS,
+  KEYBIND_PRESETS,
+};

package/src/runtime/launch/detect-clis.js

@@ -0,0 +1,69 @@
+/**
+ * Detect which AI CLIs are installed on the user's PATH.
+ *
+ * `agileflow launch` wraps whichever CLI the user has chosen — but the
+ * onboarding picker should only offer options that actually resolve.
+ * This module owns the canonical list of known AI CLIs and the routine
+ * that filters it against the system.
+ *
+ * `commandExists` is injectable so tests don't shell out.
+ */
+const { commandExists: realCommandExists } = require("../../lib/path-check.js");
+
+/**
+ * @typedef {Object} CliDescriptor
+ * @property {string} id     - stable id used in launch-prefs.json
+ * @property {string} bin    - binary name on PATH
+ * @property {string} label  - human-readable name for pickers
+ * @property {string} hint   - one-line description shown in pickers
+ */
+
+/** @type {CliDescriptor[]} */
+const KNOWN_CLIS = [
+  {
+    id: "claude",
+    bin: "claude",
+    label: "Claude Code",
+    hint: "Anthropic's official terminal CLI",
+  },
+  {
+    id: "codex",
+    bin: "codex",
+    label: "OpenAI Codex CLI",
+    hint: "OpenAI's terminal coding agent",
+  },
+  {
+    id: "cursor-agent",
+    bin: "cursor-agent",
+    label: "Cursor Agent",
+    hint: "Cursor's standalone CLI agent",
+  },
+  {
+    id: "aider",
+    bin: "aider",
+    label: "Aider",
+    hint: "Open-source pair programming CLI",
+  },
+];
+
+/**
+ * Return descriptors for CLIs whose binary resolves on PATH.
+ *
+ * @param {(name: string) => boolean} [exists] - injectable for tests
+ * @returns {CliDescriptor[]}
+ */
+function availableClis(exists = realCommandExists) {
+  return KNOWN_CLIS.filter((c) => exists(c.bin));
+}
+
+/**
+ * Find a descriptor by id. Returns null if unknown.
+ *
+ * @param {string} id
+ * @returns {CliDescriptor | null}
+ */
+function findCli(id) {
+  return KNOWN_CLIS.find((c) => c.id === id) || null;
+}
+
+module.exports = { KNOWN_CLIS, availableClis, findCli };