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

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

@@ -0,0 +1,247 @@
+/**
+ * Spawn a parallel tmux session — same-dir or worktree-backed — and
+ * switch the user's existing client to it.
+ *
+ * Used by `agileflow launch new [name]`, which the default keybind
+ * preset binds to Alt+s (no name → same-dir) and Alt+n (prompts for a
+ * name → worktree). The caller has already verified we're inside a
+ * tmux client; this module assumes that and uses `switch-client` to
+ * swap rather than `attach-session`.
+ *
+ * No-name vs name flow:
+ *   - No name: target dir is `process.cwd()`. New session uses
+ *     `nextFreeSessionName(<cli>-<dir>, ...)` so it gets a `-2`, `-3`
+ *     suffix when the canonical name is taken.
+ *   - Name: `createWorktree({ name })` first, then the same fresh-name
+ *     spawn against the worktree dir.
+ */
+const path = require("path");
+const {
+  baseSessionName,
+  nextFreeSessionName,
+  sessionExists,
+  createSession,
+  applyKeybindPreset,
+  defaultRunner,
+} = require("./tmux.js");
+const { createWorktree, removeWorktree } = require("./worktree.js");
+const { recordSession, forgetSession } = require("./session-registry.js");
+const { resolveAgileflowBin } = require("./alias-installer.js");
+
+/**
+ * @typedef {Object} ParallelSpawnResult
+ * @property {string} sessionName  - the new session's tmux name
+ * @property {string} cwd          - the directory the session was created in (cwd or worktree path)
+ * @property {{ path: string, branch: string, base: string }} [worktree]
+ *                                 - only set when `name` was supplied
+ */
+
+/**
+ * Build a typed error so callers can branch on `err.code`. Mirrors the
+ * pattern used elsewhere in the launch runtime.
+ *
+ * @param {string} message
+ * @param {string} code
+ * @returns {Error}
+ */
+function makeSpawnError(message, code) {
+  const err = new Error(message);
+  /** @type {any} */ (err).code = code;
+  return err;
+}
+
+/**
+ * Resolve the directory for the new session. With `name`, create a
+ * worktree first and use its path. Pure logic so tests can verify the
+ * branching without spawning anything.
+ *
+ * @param {{
+ *   name?: string,
+ *   cwd: string,
+ *   createWorktreeImpl?: typeof createWorktree,
+ * }} opts
+ * @returns {{ cwd: string, worktree?: { path: string, branch: string, base: string } }}
+ */
+function resolveSpawnDir(opts) {
+  if (!opts.name) {
+    return { cwd: opts.cwd };
+  }
+  const impl = opts.createWorktreeImpl || createWorktree;
+  const wt = impl({ name: opts.name });
+  return { cwd: wt.path, worktree: wt };
+}
+
+/**
+ * Spawn a new tmux session and switch the user's client to it.
+ *
+ * @param {{
+ *   bin: string,
+ *   name?: string,
+ *   prefs: import("./defaults.js").LaunchPrefs,
+ *   cwd?: string,
+ *   runner?: ReturnType<typeof defaultRunner>,
+ *   log?: (msg: string) => void,
+ *   createWorktreeImpl?: typeof createWorktree,
+ *   removeWorktreeImpl?: typeof removeWorktree,
+ * }} opts
+ * @returns {Promise<ParallelSpawnResult>}
+ */
+async function runParallelSpawn(opts) {
+  const runner = opts.runner || defaultRunner();
+  const removeWt = opts.removeWorktreeImpl || removeWorktree;
+  const log =
+    typeof opts.log === "function"
+      ? opts.log
+      : (msg) => {
+          // eslint-disable-next-line no-console
+          console.error(msg);
+        };
+
+  const { cwd: targetCwd, worktree } = resolveSpawnDir({
+    name: opts.name,
+    cwd: opts.cwd || process.cwd(),
+    createWorktreeImpl: opts.createWorktreeImpl,
+  });
+
+  if (worktree) {
+    log(
+      `agileflow launch: created worktree at ${worktree.path} on branch ${worktree.branch}`,
+    );
+  }
+
+  // Once we've created the worktree we OWN it — if any of the tmux steps
+  // below fail, roll it back so the user isn't left with an orphan dir
+  // + branch they have to clean up by hand. The rollback helper itself
+  // is best-effort; on failure we surface a warning but still re-throw
+  // the original tmux error.
+  // Track the session name across the try/catch boundary so the
+  // rollback path can also forget the registry entry we added.
+  /** @type {string | null} */
+  let registeredName = null;
+  try {
+    const cliId = path.basename(opts.bin);
+    const base = baseSessionName(cliId, targetCwd);
+    // Always pick a fresh name. `new` semantics are "I want a parallel
+    // session" — never "reattach". `nextFreeSessionName` walks
+    // base, base-2, base-3, ... until it finds an unused slot.
+    const sessionName = nextFreeSessionName(base, (n) =>
+      sessionExists(n, runner),
+    );
+    registeredName = sessionName;
+
+    // Record the session in the cross-reboot registry BEFORE spawning
+    // so the __exec wrapper can find its entry. If the spawn fails we
+    // unrecord in the catch block below.
+    recordSession({
+      name: sessionName,
+      cli: cliId,
+      cwd: targetCwd,
+      uuid: null,
+      worktree: worktree
+        ? { path: worktree.path, branch: worktree.branch, base: worktree.base }
+        : undefined,
+    });
+
+    const agileflowBin = resolveAgileflowBin();
+    const create = createSession(
+      {
+        name: sessionName,
+        bin: agileflowBin,
+        args: ["launch", "__exec", sessionName],
+        cwd: targetCwd,
+        statusPosition: opts.prefs.tmux.statusPosition,
+      },
+      runner,
+    );
+    if (create.status !== 0) {
+      if (create.error) throw create.error;
+
+      // Race recovery: in the same-dir (no-name) case, another
+      // `agileflow launch new` invocation could have grabbed our
+      // candidate name between the nextFreeSessionName probe and the
+      // new-session call. If the session is alive now, treat this as
+      // "user got what they wanted" and switch-client to it. We don't
+      // do this for the worktree path because the worktree dir is
+      // freshly created and unique, so the name collision shouldn't
+      // happen — if it does, something weirder is going on and the
+      // user should see the original error.
+      if (!opts.name && sessionExists(sessionName, runner)) {
+        log(
+          `agileflow launch: race-recovered, attaching to session ${sessionName}`,
+        );
+      } else {
+        const stderr = create.stderr.trim() || "tmux new-session failed";
+        throw makeSpawnError(`tmux: ${stderr}`, "ETMUX_CREATE");
+      }
+    }
+
+    // Apply the user's keybind preset to the (server-wide) bindings table.
+    // Same call the engine makes on every launch, so the new session
+    // inherits the same Alt+q etc. as the parent.
+    if (opts.prefs.keybinds && opts.prefs.keybinds.preset) {
+      const result = applyKeybindPreset(opts.prefs.keybinds.preset, runner);
+      for (const f of result.failures) {
+        log(`agileflow launch: keybind skipped — ${f.hint}`);
+      }
+    }
+
+    // Swap the user's tmux client to the new session. If switch-client
+    // fails the session is still alive — surface its name so the user
+    // can attach manually.
+    const sw = runner.runSync(["switch-client", "-t", sessionName]);
+    if (sw.status !== 0) {
+      throw makeSpawnError(
+        `switch-client failed: ${sw.stderr.trim() || "unknown error"}; ` +
+          `session "${sessionName}" is still running — \`tmux attach -t ${sessionName}\` to enter it.`,
+        "ETMUX_SWITCH",
+      );
+    }
+
+    log(`agileflow launch: switched to new session ${sessionName}`);
+    return { sessionName, cwd: targetCwd, worktree };
+  } catch (err) {
+    // Forget the registry entry we added — the spawn didn't succeed
+    // so there's nothing to restore later. Worst case: a tmux session
+    // exists but isn't in the registry (cosmetic; user can attach
+    // manually via `tmux attach -t <name>`).
+    if (registeredName) {
+      try {
+        forgetSession(registeredName);
+      } catch {
+        /* swallow */
+      }
+    }
+    // Rollback path. Worktree got created but a subsequent step (tmux
+    // create / keybind apply / switch-client) failed — remove the
+    // worktree dir + branch so the repo state matches the launch state
+    // (i.e., as if the user had never pressed Alt+n).
+    if (worktree) {
+      try {
+        const result = removeWt({
+          path: worktree.path,
+          branch: worktree.branch,
+        });
+        if (result.removed && result.branchRemoved) {
+          log(
+            `agileflow launch: rolled back worktree ${worktree.path} + branch ${worktree.branch}`,
+          );
+        } else {
+          log(
+            `agileflow launch: worktree rollback partial — manual cleanup may be needed (${result.stderr})`,
+          );
+        }
+      } catch (rollbackErr) {
+        log(
+          `agileflow launch: rollback failed — leftover at ${worktree.path}: ${rollbackErr.message}`,
+        );
+      }
+    }
+    throw err;
+  }
+}
+
+module.exports = {
+  runParallelSpawn,
+  resolveSpawnDir,
+  makeSpawnError,
+};

package/src/runtime/launch/prefs.js

@@ -0,0 +1,211 @@
+/**
+ * Read / write `~/.agileflow/launch-prefs.json` — the first user-level
+ * config in v4.
+ *
+ * Mirrors the atomic-write pattern from `runtime/config/writer.js`:
+ * render to a sibling temp file, then `fs.rename()` into place so a
+ * concurrent read either sees the old content or the new content,
+ * never a torn half-write.
+ *
+ * Validation here is *shape-light* on read: missing keys are filled
+ * from `defaultPrefs()`, unknown extras are dropped. The JSON schema
+ * (`schema.json`) is the authoritative contract for editor tooling.
+ */
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const {
+  defaultPrefs,
+  KNOWN_CLI_IDS,
+  STATUS_POSITIONS,
+  KEYBIND_PRESETS,
+} = require("./defaults.js");
+
+const FILENAME = "launch-prefs.json";
+const SCHEMA_REF = "./node_modules/agileflow/src/runtime/launch/schema.json";
+
+/**
+ * @param {string} [home] - override for tests; defaults to os.homedir()
+ * @returns {string}
+ */
+function prefsPath(home) {
+  const root = home || os.homedir();
+  return path.join(root, ".agileflow", FILENAME);
+}
+
+/**
+ * Merge a partial prefs object on top of defaults, sanitizing unknown
+ * enum values back to their defaults. Returns a fresh object — never
+ * mutates the input.
+ *
+ * @param {Partial<import('./defaults.js').LaunchPrefs>} [partial]
+ * @returns {import('./defaults.js').LaunchPrefs}
+ */
+function mergeWithDefaults(partial = {}) {
+  const base = defaultPrefs();
+
+  const cli = partial.cli || {};
+  const preferred = KNOWN_CLI_IDS.includes(cli.preferred)
+    ? cli.preferred
+    : base.cli.preferred;
+  const fallbackOrder = Array.isArray(cli.fallbackOrder)
+    ? cli.fallbackOrder.filter((id) => KNOWN_CLI_IDS.includes(id))
+    : base.cli.fallbackOrder;
+
+  const tmux = partial.tmux || {};
+  const tmuxEnabled =
+    typeof tmux.enabled === "boolean" ? tmux.enabled : base.tmux.enabled;
+  const statusPosition = STATUS_POSITIONS.includes(tmux.statusPosition)
+    ? tmux.statusPosition
+    : base.tmux.statusPosition;
+
+  const keybinds = partial.keybinds || {};
+  const preset = KEYBIND_PRESETS.includes(keybinds.preset)
+    ? keybinds.preset
+    : base.keybinds.preset;
+
+  const aliases = partial.aliases || {};
+  const afEnabled =
+    aliases.af && typeof aliases.af.enabled === "boolean"
+      ? aliases.af.enabled
+      : base.aliases.af.enabled;
+
+  const pinned = Array.isArray(partial.pinned)
+    ? partial.pinned.filter((s) => typeof s === "string")
+    : base.pinned;
+
+  // Invariant: `preferred` must appear in `fallbackOrder` (the latter is
+  // documented as "order to try if preferred is missing", which only
+  // makes sense if preferred itself is in the chain). Hand-edited prefs
+  // can violate this — we repair it here rather than at every read site.
+  let resolvedFallback = fallbackOrder.length
+    ? fallbackOrder
+    : base.cli.fallbackOrder;
+  if (!resolvedFallback.includes(preferred)) {
+    resolvedFallback = [preferred, ...resolvedFallback];
+  }
+
+  return {
+    version: 1,
+    cli: {
+      preferred,
+      fallbackOrder: resolvedFallback,
+    },
+    tmux: { enabled: tmuxEnabled, statusPosition },
+    keybinds: { preset },
+    aliases: { af: { enabled: afEnabled } },
+    pinned,
+  };
+}
+
+/**
+ * Load prefs from disk. Returns defaults if the file is absent.
+ * Throws on invalid JSON so the caller can surface an actionable error.
+ *
+ * @param {string} [home]
+ * @returns {Promise<{
+ *   prefs: import('./defaults.js').LaunchPrefs,
+ *   source: 'file' | 'defaults',
+ *   path: string,
+ * }>}
+ */
+async function loadPrefs(home) {
+  const file = prefsPath(home);
+  let raw;
+  try {
+    raw = await fs.promises.readFile(file, "utf8");
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      return { prefs: defaultPrefs(), source: "defaults", path: file };
+    }
+    throw err;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    const wrapped = new Error(`could not parse ${file}: ${err.message}`);
+    wrapped.cause = err;
+    throw wrapped;
+  }
+
+  // JSON.parse can return null, primitives, or arrays — any of which
+  // would crash `mergeWithDefaults` at the first property access. Reject
+  // them with the same "could not parse" shape so the caller's error
+  // path is the only one users see.
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    const kind =
+      parsed === null
+        ? "null"
+        : Array.isArray(parsed)
+          ? "array"
+          : typeof parsed;
+    throw new Error(
+      `could not parse ${file}: expected a JSON object, got ${kind}`,
+    );
+  }
+
+  return { prefs: mergeWithDefaults(parsed), source: "file", path: file };
+}
+
+/**
+ * Atomically write prefs to disk. Stamps `lastUpdated` with the current
+ * ISO timestamp. Ensures `~/.agileflow/` exists.
+ *
+ * @param {import('./defaults.js').LaunchPrefs} next
+ * @param {string} [home]
+ * @returns {Promise<string>} absolute path of the written file
+ */
+async function writePrefs(next, home) {
+  const merged = mergeWithDefaults(next);
+  const file = prefsPath(home);
+  const dir = path.dirname(file);
+  const tmp = path.join(dir, `.${FILENAME}.tmp-${process.pid}`);
+
+  const payload = {
+    $schema: SCHEMA_REF,
+    ...merged,
+    lastUpdated: new Date().toISOString(),
+  };
+  const content = JSON.stringify(payload, null, 2) + "\n";
+
+  try {
+    await fs.promises.mkdir(dir, { recursive: true });
+    await fs.promises.writeFile(tmp, content, "utf8");
+    await fs.promises.rename(tmp, file);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+  return file;
+}
+
+/**
+ * Whether a prefs file exists on disk.
+ * @param {string} [home]
+ * @returns {Promise<boolean>}
+ */
+async function prefsExist(home) {
+  try {
+    await fs.promises.access(prefsPath(home), fs.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  FILENAME,
+  SCHEMA_REF,
+  prefsPath,
+  mergeWithDefaults,
+  loadPrefs,
+  writePrefs,
+  prefsExist,
+};

package/src/runtime/launch/project-prefs.js

@@ -0,0 +1,234 @@
+/**
+ * Per-project launch prefs cascade.
+ *
+ * Layering (lowest-priority first):
+ *   1. Built-in defaults from `defaults.js`
+ *   2. Global user prefs   `~/.agileflow/launch-prefs.json`
+ *   3. Project prefs       `<repo>/.agileflow/launch.json`
+ *
+ * The project file is searched by walking up from `cwd` until either:
+ *   - we find a `.agileflow/launch.json`, or
+ *   - we cross a `.git` boundary (the repo root — beyond it we're in a
+ *     different project's territory), or
+ *   - we hit the filesystem root.
+ *
+ * Per-key partial override: a project file can specify ONLY the keys it
+ * cares about. Unspecified keys fall through to the global file's value,
+ * which in turn falls through to defaults. This lets a repo flip just
+ * `tmux.enabled` without having to mirror the whole prefs shape.
+ *
+ * Project file shape mirrors `launch-prefs.json` minus `$schema` and
+ * `lastUpdated`. Hand-edited files are normal; unknown extras are
+ * dropped silently (same posture as the global loader).
+ */
+const fs = require("fs");
+const path = require("path");
+
+const { loadPrefs } = require("./prefs.js");
+
+const PROJECT_DIR = ".agileflow";
+const PROJECT_FILENAME = "launch.json";
+
+/**
+ * Walk up from `cwd` looking for a `.agileflow/launch.json`. Stops at
+ * the filesystem root, or at the first directory containing a `.git`
+ * entry — beyond a repo boundary we shouldn't be inheriting another
+ * project's prefs.
+ *
+ * @param {string} cwd
+ * @param {{
+ *   existsSync?: (p: string) => boolean,
+ *   statSync?: typeof fs.statSync,
+ * }} [opts]
+ * @returns {string | null}
+ */
+function findProjectPrefsFile(cwd, opts = {}) {
+  const existsSync = opts.existsSync || ((p) => fs.existsSync(p));
+  const statSync = opts.statSync || fs.statSync;
+  let dir = path.resolve(cwd);
+  // Cap the walk at 64 ancestors. Filesystems hit root long before that
+  // in practice; the cap exists so a pathological symlink loop can't
+  // stall us.
+  for (let i = 0; i < 64; i++) {
+    const candidate = path.join(dir, PROJECT_DIR, PROJECT_FILENAME);
+    if (existsSync(candidate)) {
+      try {
+        if (statSync(candidate).isFile()) return candidate;
+      } catch {
+        /* swallow — vanished between exists + stat */
+      }
+    }
+    // Repo boundary check happens AFTER the in-dir search so the repo
+    // root itself can host the project prefs (the common case).
+    if (existsSync(path.join(dir, ".git"))) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null; // hit filesystem root
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Read + parse a project prefs file. Returns null on missing file,
+ * malformed JSON, or non-object payload — same forgiving posture as
+ * `loadRegistry`. Surfacing a hard error here would block `launch` for
+ * what is almost always a manual-edit typo.
+ *
+ * @param {string} file
+ * @param {{ readFileSync?: typeof fs.readFileSync }} [opts]
+ * @returns {Partial<import("./defaults.js").LaunchPrefs> | null}
+ */
+function readProjectPrefs(file, opts = {}) {
+  const readFileSync = opts.readFileSync || fs.readFileSync;
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    // eslint-disable-next-line no-console
+    console.error(
+      `agileflow launch: ${file} is not valid JSON — ignoring project prefs.`,
+    );
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+  return /** @type {Partial<import("./defaults.js").LaunchPrefs>} */ (parsed);
+}
+
+/**
+ * Layer a partial prefs object over an already-merged base. Mirrors the
+ * shape and validation of `mergeWithDefaults` but uses `base` (the
+ * global-merged prefs) as the fallback instead of the built-in defaults.
+ *
+ * Per-key semantics:
+ *   - cli, tmux, keybinds, aliases: partial sub-object override. Any
+ *     leaf that the project omits inherits from `base`.
+ *   - pinned: project array (when present) REPLACES base entirely —
+ *     "pinned" is conceptually a list, not a deep-merge dictionary.
+ *
+ * Unknown enum values fall back to the corresponding `base` value (NOT
+ * defaults) so a typo in the project file degrades gracefully.
+ *
+ * @param {import("./defaults.js").LaunchPrefs} base
+ * @param {Partial<import("./defaults.js").LaunchPrefs>} partial
+ * @returns {import("./defaults.js").LaunchPrefs}
+ */
+function mergePartialOver(base, partial) {
+  const {
+    KNOWN_CLI_IDS,
+    STATUS_POSITIONS,
+    KEYBIND_PRESETS,
+  } = require("./defaults.js");
+
+  const cli = partial.cli || {};
+  const preferred = KNOWN_CLI_IDS.includes(cli.preferred)
+    ? cli.preferred
+    : base.cli.preferred;
+  const fallbackOrder = Array.isArray(cli.fallbackOrder)
+    ? cli.fallbackOrder.filter((id) => KNOWN_CLI_IDS.includes(id))
+    : base.cli.fallbackOrder;
+
+  const tmux = partial.tmux || {};
+  const tmuxEnabled =
+    typeof tmux.enabled === "boolean" ? tmux.enabled : base.tmux.enabled;
+  const statusPosition = STATUS_POSITIONS.includes(tmux.statusPosition)
+    ? tmux.statusPosition
+    : base.tmux.statusPosition;
+
+  const keybinds = partial.keybinds || {};
+  const preset = KEYBIND_PRESETS.includes(keybinds.preset)
+    ? keybinds.preset
+    : base.keybinds.preset;
+
+  const aliases = partial.aliases || {};
+  const afEnabled =
+    aliases.af && typeof aliases.af.enabled === "boolean"
+      ? aliases.af.enabled
+      : base.aliases.af.enabled;
+
+  const pinned = Array.isArray(partial.pinned)
+    ? partial.pinned.filter((s) => typeof s === "string")
+    : base.pinned;
+
+  // Same invariant as the global loader: preferred must be in fallbackOrder.
+  // Project-level override could break it (e.g., partial only sets
+  // cli.preferred and inherits a fallbackOrder that doesn't include it).
+  let resolvedFallback = fallbackOrder.length
+    ? fallbackOrder
+    : base.cli.fallbackOrder;
+  if (!resolvedFallback.includes(preferred)) {
+    resolvedFallback = [preferred, ...resolvedFallback];
+  }
+
+  return {
+    version: /** @type {1} */ (1),
+    cli: { preferred, fallbackOrder: resolvedFallback },
+    tmux: { enabled: tmuxEnabled, statusPosition },
+    keybinds: { preset },
+    aliases: { af: { enabled: afEnabled } },
+    pinned,
+  };
+}
+
+/**
+ * Load prefs with the full cascade. The returned `sources` array records
+ * which files contributed (in increasing precedence), so the `launch
+ * where` subcommand can show the user exactly what's being layered.
+ *
+ * @param {{
+ *   home?: string,
+ *   cwd?: string,
+ *   loadGlobalPrefs?: typeof loadPrefs,
+ *   findProjectFile?: typeof findProjectPrefsFile,
+ *   readProjectFile?: typeof readProjectPrefs,
+ * }} [opts]
+ * @returns {Promise<{
+ *   prefs: import("./defaults.js").LaunchPrefs,
+ *   sources: Array<{ layer: 'defaults' | 'global' | 'project', path?: string }>,
+ * }>}
+ */
+async function loadCascadedPrefs(opts = {}) {
+  const loadGlobal = opts.loadGlobalPrefs || loadPrefs;
+  const findProject = opts.findProjectFile || findProjectPrefsFile;
+  const readProject = opts.readProjectFile || readProjectPrefs;
+  const cwd = opts.cwd || process.cwd();
+
+  /** @type {Array<{ layer: 'defaults' | 'global' | 'project', path?: string }>} */
+  const sources = [{ layer: "defaults" }];
+
+  const globalLoaded = await loadGlobal(opts.home);
+  if (globalLoaded.source === "file") {
+    sources.push({ layer: "global", path: globalLoaded.path });
+  }
+
+  const projectFile = findProject(cwd);
+  if (!projectFile) {
+    return { prefs: globalLoaded.prefs, sources };
+  }
+  const projectPartial = readProject(projectFile);
+  if (!projectPartial) {
+    // File present but unreadable / malformed — already logged by
+    // readProjectPrefs. Treat as absent so launch keeps working.
+    return { prefs: globalLoaded.prefs, sources };
+  }
+
+  const merged = mergePartialOver(globalLoaded.prefs, projectPartial);
+  sources.push({ layer: "project", path: projectFile });
+  return { prefs: merged, sources };
+}
+
+module.exports = {
+  PROJECT_DIR,
+  PROJECT_FILENAME,
+  findProjectPrefsFile,
+  readProjectPrefs,
+  mergePartialOver,
+  loadCascadedPrefs,
+};