moflo 4.12.12 → 4.13.1

package/dist/src/cli/services/worktree-provision.js

@@ -0,0 +1,400 @@
+/**
+ * Worktree provisioning (#1481).
+ *
+ * `/flo -wt` and `flo worktree add` create a git worktree; on its own that is a
+ * valid checkout and an unrunnable workspace — no `node_modules`, none of the
+ * gitignored `.env` files, and no notion that a second worktree's dev servers
+ * will collide with the first on fixed ports. This service closes that gap,
+ * driven by the optional `worktree:` block in `moflo.yaml`.
+ *
+ * Every platform-sensitive decision lives here rather than in the command, so
+ * the Windows-vs-POSIX branches are reachable from a unit test (Rule #1):
+ *   - paths built with `path.*`, never separator concatenation
+ *   - directory links are junctions on Windows (no admin/developer mode needed,
+ *     and the target must be absolute), plain symlinks on POSIX
+ *   - copies via `fs.cpSync`; no `cp`/`ln -s`/`mkdir -p`/`find` shell-outs
+ *   - `setup` runs through a shell on both platforms (it is a user-authored
+ *     command string, not an argv array) — see `runSetup`
+ *   - containment checks realpath BOTH sides before comparing (#1145: macOS
+ *     `/var/folders` vs `/private/var/folders` otherwise false-positives)
+ */
+import { spawnSync } from 'node:child_process';
+import { cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, symlinkSync, } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFileSync } from '../shared/utils/atomic-file-write.js';
+import { globToRegExp } from '../guidance/retriever.js';
+/** Relative path of the per-worktree state file, from the worktree root. */
+export const WORKTREE_STATE_FILE = path.join('.moflo', 'worktree.json');
+/**
+ * The same path in git's spelling. `git status --porcelain` reports forward
+ * slashes on every platform, so a caller comparing against porcelain output
+ * needs this form rather than the host-separator one above.
+ */
+export const WORKTREE_STATE_FILE_POSIX = '.moflo/worktree.json';
+/**
+ * Turn a branch name into a single flat directory name. Both separators are
+ * replaced: a branch is always `/`-delimited, but a caller may hand us a
+ * Windows-style string, and `\` is invalid in an NTFS directory name anyway.
+ */
+export function slugifyBranch(branch) {
+    return branch.replace(/[\\/]/g, '-');
+}
+/**
+ * Resolve where a worktree for `branch` belongs.
+ *
+ * Default: `<repo-parent>/<repo-basename>-worktrees/<slugged-branch>` — a
+ * sibling of the checkout, so it is never inside the repo (and so never picked
+ * up by the repo's own tooling). `configuredDir` overrides the parent directory
+ * and is resolved relative to `repoRoot` when relative.
+ */
+export function computeWorktreePath(repoRoot, branch, configuredDir) {
+    const parent = configuredDir
+        ? path.resolve(repoRoot, configuredDir)
+        : path.join(path.dirname(repoRoot), `${path.basename(repoRoot)}-worktrees`);
+    return path.join(parent, slugifyBranch(branch));
+}
+/**
+ * Smallest non-negative integer not already taken. Reusing a freed slot (rather
+ * than incrementing a counter) keeps the index small and stable, which matters
+ * because consumers offset fixed ports from it — an unbounded counter would
+ * eventually push a derived port out of range.
+ */
+export function allocateIndex(existing) {
+    const taken = new Set(existing.filter(n => Number.isInteger(n) && n >= 0));
+    let candidate = 0;
+    while (taken.has(candidate))
+        candidate++;
+    return candidate;
+}
+/**
+ * Resolve a path as far as it exists. `realpathSync` throws on a missing path,
+ * but a containment check must still work for a destination that has not been
+ * created yet — so walk up to the nearest existing ancestor, resolve that, and
+ * re-append the remainder.
+ */
+function realpathBestEffort(target) {
+    let current = path.resolve(target);
+    const trailing = [];
+    // Bounded by the path depth: each iteration removes one segment, and
+    // `path.dirname` is a fixed point at the filesystem root.
+    for (;;) {
+        if (existsSync(current))
+            return path.join(realpathSync(current), ...trailing.reverse());
+        const parent = path.dirname(current);
+        if (parent === current)
+            return path.resolve(target);
+        trailing.push(path.basename(current));
+        current = parent;
+    }
+}
+/**
+ * A canonical key for path identity: realpath'd, and case-folded on the two
+ * platforms whose filesystems are case-insensitive by default.
+ *
+ * Exported so a caller scanning a list resolves its needle ONCE and compares
+ * keys, rather than realpathing both sides on every iteration. Case-folding is
+ * what makes plain string equality safe here — `C:\Repo` and `C:\repo` are the
+ * same directory on Windows, and `/Users/x/Repo` and `/Users/x/repo` are the
+ * same directory on stock APFS.
+ */
+export function resolveForCompare(target) {
+    const resolved = realpathBestEffort(target);
+    return process.platform === 'win32' || process.platform === 'darwin'
+        ? resolved.toLowerCase()
+        : resolved;
+}
+/**
+ * Is `candidate` inside `root`? Both sides go through
+ * {@link resolveForCompare} first — the #1145 shape, where an unresolved
+ * `/var/folders/...` compared against a resolved `/private/var/folders/...` on
+ * macOS made two identical paths look different.
+ */
+export function isInside(root, candidate) {
+    const resolvedRoot = resolveForCompare(root);
+    const resolvedCandidate = resolveForCompare(candidate);
+    if (resolvedCandidate === resolvedRoot)
+        return true;
+    const rel = path.relative(resolvedRoot, resolvedCandidate);
+    // No `rel.length > 0` guard: `path.relative` returns '' for two spellings of
+    // the SAME directory that the equality check above missed, and treating that
+    // as "not inside" would break every identity test built on this.
+    return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+/**
+ * Expand one `copy:` entry against the primary checkout.
+ *
+ * Glob support is deliberately narrow — a single `*` in the final segment, so
+ * `.env.*` works — because the alternative is either a shell-out (`find` does
+ * not exist on Windows) or a full tree walk on a pattern the user thought was
+ * cheap. A pattern needing more than this returns nothing rather than silently
+ * matching a subset; the caller reports it as skipped.
+ */
+function expandCopyEntry(primaryRoot, entry) {
+    const normalized = entry.split(/[\\/]/).filter(Boolean);
+    if (normalized.length === 0)
+        return [];
+    const last = normalized[normalized.length - 1];
+    if (!last.includes('*')) {
+        const full = path.join(primaryRoot, ...normalized);
+        return existsSync(full) ? [full] : [];
+    }
+    const dir = path.join(primaryRoot, ...normalized.slice(0, -1));
+    if (!existsSync(dir))
+        return [];
+    // Reuse the guidance retriever's translator rather than hand-rolling one: it
+    // is anchored, escapes every metacharacter, and was already hardened for the
+    // `docs/*.md` matching `docsXmd` bug. Its `*` becomes `[^/]*`, which is exact
+    // here because these patterns match bare readdir NAMES, never a path.
+    const pattern = globToRegExp(last);
+    return readdirSync(dir)
+        .filter(name => pattern.test(name))
+        .sort()
+        .map(name => path.join(dir, name));
+}
+/**
+ * Does a config entry escape `root` before any symlink resolution?
+ *
+ * Deliberately LEXICAL, unlike {@link isInside}. "Did the user write a path that
+ * climbs out of the tree" is a property of the string they wrote, and resolving
+ * it first gets the answer wrong in the normal case: on a re-add, the worktree's
+ * `node_modules` is already a symlink into the primary checkout, so realpathing
+ * the destination reports it as outside the worktree and rejects a link that is
+ * exactly the one provisioning just made. A primary checkout whose own
+ * `node_modules` is a symlink (pnpm, a shared store) fails the same way.
+ */
+function escapesRoot(root, entry) {
+    const rel = path.relative(root, path.resolve(root, entry));
+    return rel.startsWith('..') || path.isAbsolute(rel);
+}
+/**
+ * Copy the configured gitignored material into the new worktree.
+ *
+ * Sources are guarded on both ends: each must resolve inside the primary
+ * checkout (so `../secrets` is rejected), and the destination is always the
+ * worktree we just created. A missing source is skipped rather than fatal —
+ * `.env.local` legitimately does not exist on every machine.
+ */
+function runCopy(primaryRoot, worktreePath, entries) {
+    const steps = [];
+    for (const entry of entries) {
+        if (!isInside(primaryRoot, path.resolve(primaryRoot, entry))) {
+            steps.push({
+                kind: 'copy',
+                target: entry,
+                status: 'failed',
+                detail: 'resolves outside the primary checkout',
+            });
+            continue;
+        }
+        const matches = expandCopyEntry(primaryRoot, entry);
+        if (matches.length === 0) {
+            steps.push({ kind: 'copy', target: entry, status: 'skipped', detail: 'no match' });
+            continue;
+        }
+        for (const source of matches) {
+            const dest = path.join(worktreePath, path.relative(primaryRoot, source));
+            try {
+                mkdirSync(path.dirname(dest), { recursive: true });
+                cpSync(source, dest, { recursive: true });
+                steps.push({ kind: 'copy', target: path.relative(primaryRoot, source), status: 'done' });
+            }
+            catch (error) {
+                steps.push({
+                    kind: 'copy',
+                    target: path.relative(primaryRoot, source),
+                    status: 'failed',
+                    detail: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    return steps;
+}
+/**
+ * The `fs.symlinkSync` type argument for a directory link on this platform.
+ *
+ * Windows gets a junction: unlike a `'dir'` symlink it needs no admin rights or
+ * developer mode. Exported and pure so the Windows branch is assertable from a
+ * unit test on any host — the alternative, spying on an ESM `fs` export, is not
+ * possible, and gating the assertion on a Windows runner would leave the branch
+ * unverified on the two CI legs that run most often.
+ */
+export function linkTypeForPlatform(platform) {
+    return platform === 'win32' ? 'junction' : undefined;
+}
+/**
+ * Link the configured paths from the primary checkout into the new worktree.
+ * The target is resolved to an ABSOLUTE path before the call on every platform:
+ * a relative target silently produces a broken junction on Windows.
+ */
+function runLink(primaryRoot, worktreePath, entries) {
+    const steps = [];
+    const linkType = linkTypeForPlatform(process.platform);
+    for (const entry of entries) {
+        const source = path.resolve(primaryRoot, entry);
+        const dest = path.resolve(worktreePath, entry);
+        // Guard BOTH ends against an escaping entry: `link: ["../x"]` would
+        // otherwise source from outside the checkout and write the link outside the
+        // worktree. Lexical on purpose — see escapesRoot().
+        if (escapesRoot(primaryRoot, entry) || escapesRoot(worktreePath, entry)) {
+            steps.push({
+                kind: 'link',
+                target: entry,
+                status: 'failed',
+                detail: 'resolves outside the primary checkout or the worktree',
+            });
+            continue;
+        }
+        if (!existsSync(source)) {
+            steps.push({ kind: 'link', target: entry, status: 'skipped', detail: 'no such path' });
+            continue;
+        }
+        // lstat, not existsSync: a broken symlink left by an earlier run still
+        // occupies the name, and clobbering it is not ours to decide.
+        let occupied = false;
+        try {
+            lstatSync(dest);
+            occupied = true;
+        }
+        catch {
+            occupied = false;
+        }
+        if (occupied) {
+            steps.push({ kind: 'link', target: entry, status: 'skipped', detail: 'already exists' });
+            continue;
+        }
+        try {
+            mkdirSync(path.dirname(dest), { recursive: true });
+            symlinkSync(source, dest, linkType);
+            steps.push({ kind: 'link', target: entry, status: 'done' });
+        }
+        catch (error) {
+            steps.push({
+                kind: 'link',
+                target: entry,
+                status: 'failed',
+                detail: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return steps;
+}
+/**
+ * Run the configured `setup` command inside the new worktree.
+ *
+ * `shell: true` on BOTH platforms, unlike the daemon-spawning code this repo
+ * models elsewhere. That rule ("shell on Windows, detached on POSIX") is about
+ * spawning a known binary with an argv array; `setup` is a user-authored shell
+ * command *string* from `moflo.yaml` — `npm ci && npm run build` is a legitimate
+ * value, and it needs `cmd.exe` or `/bin/sh` to mean anything. Running it
+ * without a shell would exec a file literally named `npm ci && npm run build`.
+ * On Windows a shell is required regardless, since `npm` there is `npm.cmd`.
+ * Trust boundary: the same as a `package.json` script — the project's own config.
+ *
+ * `jsonMode` sends the child's stdout to our stderr so a `--json` caller still
+ * gets parseable JSON on stdout.
+ */
+function runSetup(worktreePath, command, index, jsonMode) {
+    const result = spawnSync(command, {
+        cwd: worktreePath,
+        shell: true,
+        stdio: jsonMode ? ['ignore', 2, 2] : 'inherit',
+        env: { ...process.env, MOFLO_WORKTREE_INDEX: String(index) },
+    });
+    if (result.error) {
+        return { kind: 'setup', target: command, status: 'failed', detail: result.error.message };
+    }
+    if (result.status !== 0) {
+        return {
+            kind: 'setup',
+            target: command,
+            status: 'failed',
+            detail: `exited with code ${result.status ?? 'null'}`,
+        };
+    }
+    return { kind: 'setup', target: command, status: 'done' };
+}
+/**
+ * Provision a freshly created worktree: copy, then link, then setup.
+ *
+ * Order matters — `setup` (typically `npm ci`) may depend on the `.env` files
+ * `copy` brings in, and must not race the `link` that would otherwise supply
+ * `node_modules`. A failed step never unwinds the worktree: it is a valid
+ * checkout either way, and deleting a tree the user may have started working in
+ * is far worse than leaving it under-provisioned.
+ */
+export function provisionWorktree(opts) {
+    const { primaryRoot, worktreePath, branch, index, config, jsonMode = false } = opts;
+    const steps = [];
+    if (config?.copy?.length)
+        steps.push(...runCopy(primaryRoot, worktreePath, config.copy));
+    if (config?.link?.length)
+        steps.push(...runLink(primaryRoot, worktreePath, config.link));
+    if (config?.setup)
+        steps.push(runSetup(worktreePath, config.setup, index, jsonMode));
+    const provisioned = steps.every(step => step.status !== 'failed');
+    writeWorktreeState(worktreePath, { branch, index, primaryRoot, provisioned });
+    return { provisioned, steps };
+}
+/**
+ * Did `copy:`/`link:` put this worktree-relative path there?
+ *
+ * Lives here, next to {@link provisionWorktree}, because answering it needs the
+ * same glob translation provisioning used: a raw config entry is not a filename.
+ * Comparing `.env.*` literally against the `.env.local` git reports never
+ * matches, which would blame provisioning's own files on the user.
+ *
+ * Every ancestor prefix is tested, so a directory entry (glob or literal) also
+ * claims the files inside it — `git status -uall` reports those individually.
+ *
+ * @param target a path in git's spelling (forward slashes), relative to the worktree
+ */
+export function isProvisionedPath(target, config) {
+    const entries = [...(config?.copy ?? []), ...(config?.link ?? [])]
+        .map(entry => entry.split(/[\\/]/).filter(Boolean).join('/'))
+        .filter(Boolean);
+    if (entries.length === 0)
+        return false;
+    const segments = target.split('/').filter(Boolean);
+    for (const entry of entries) {
+        const matcher = entry.includes('*') ? globToRegExp(entry) : null;
+        for (let depth = 1; depth <= segments.length; depth++) {
+            const prefix = segments.slice(0, depth).join('/');
+            if (matcher ? matcher.test(prefix) : prefix === entry)
+                return true;
+        }
+    }
+    return false;
+}
+/** Write `.moflo/worktree.json` into a worktree. Atomic — the daemon may read it. */
+export function writeWorktreeState(worktreePath, state) {
+    const statePath = path.join(worktreePath, WORKTREE_STATE_FILE);
+    mkdirSync(path.dirname(statePath), { recursive: true });
+    atomicWriteFileSync(statePath, `${JSON.stringify(state, null, 2)}\n`);
+}
+/**
+ * Read a worktree's moflo state. `null` means moflo did not create this tree —
+ * which is exactly how `flo worktree list` reports an externally-created
+ * worktree as unprovisioned, so a malformed file is treated the same as a
+ * missing one rather than failing the listing.
+ */
+export function readWorktreeState(worktreePath) {
+    const statePath = path.join(worktreePath, WORKTREE_STATE_FILE);
+    if (!existsSync(statePath))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(statePath, 'utf8'));
+        if (typeof parsed.branch !== 'string' || !Number.isInteger(parsed.index))
+            return null;
+        return {
+            branch: parsed.branch,
+            index: parsed.index,
+            primaryRoot: typeof parsed.primaryRoot === 'string' ? parsed.primaryRoot : '',
+            provisioned: parsed.provisioned === true,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=worktree-provision.js.map

package/dist/src/cli/version.js

@@ -2,5 +2,5 @@
  * Auto-generated by build. Do not edit manually.
  * Source of truth: root package.json → scripts/sync-version.mjs
  */
-export const VERSION = '4.12.12';
+export const VERSION = '4.13.1';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "moflo",
-  "version": "4.12.12",
+  "version": "4.13.1",
   "description": "MoFlo — AI agent orchestration for Claude Code. A standalone, opinionated toolkit with semantic memory, learned routing, gates, spells, and the /flo issue-execution skill.",
   "main": "dist/src/cli/index.js",
   "type": "module",
@@ -99,7 +99,7 @@
     "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.8.0",
     "glob": "^11.1.0",
-    "moflo": "^4.12.11",
+    "moflo": "^4.13.0",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0"