agileflow 3.4.3 → 4.0.0-alpha.10

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/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,
+};

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