@gr8ful/spf 0.1.0

package/dist/core/git_helper.js

@@ -0,0 +1,115 @@
+/**
+ * Low-level git operations for code phases. All low-level logic lives in core/.
+ *
+ * Two discovery functions (`isRepoAt`, `findRepoRoot`) take an explicit `cwd`
+ * because they are how a repo root gets established in the first place —
+ * nothing has one yet to bind to. Everything else is repo-root-bound: call
+ * `makeGit(repoRoot)` once you have that root, and every operation it returns
+ * runs there, never against `process.cwd()`. This is deliberate — the ADW
+ * process's cwd and the repo it is operating on are two different things,
+ * and conflating them is exactly the anchor bug this factory exists to close.
+ */
+import { spawnSync } from "node:child_process";
+import path from "node:path";
+function git(args, cwd) {
+    const result = spawnSync("git", args, { cwd, encoding: "utf-8" });
+    if (result.status !== 0) {
+        throw new Error(`git ${args.join(" ")} failed: ${(result.stderr || "").trim()}`);
+    }
+    return result.stdout.trim();
+}
+/** True when `cwd` is inside a git working tree. Never throws — this is a question. */
+export function isRepoAt(cwd) {
+    const result = spawnSync("git", ["rev-parse", "--git-dir"], { cwd, encoding: "utf-8" });
+    return result.status === 0;
+}
+/**
+ * Absolute root of the git repo containing `cwd`, or `cwd` itself if it is
+ * not inside one — ADWs run fine in a non-git dir; only a commit phase
+ * requires a repo. Always absolute, so it is safe to hand to a subprocess
+ * regardless of where the ADW was launched from.
+ */
+export function findRepoRoot(cwd) {
+    if (isRepoAt(cwd)) {
+        return path.resolve(git(["rev-parse", "--show-toplevel"], cwd));
+    }
+    return path.resolve(cwd);
+}
+/** Every operation this returns is bound to `repoRoot` — never `process.cwd()`. */
+export function makeGit(repoRoot) {
+    const run = (args) => git(args, repoRoot);
+    return {
+        currentBranch: () => run(["rev-parse", "--abbrev-ref", "HEAD"]),
+        createBranch: (name) => {
+            run(["checkout", "-b", name]);
+            return name;
+        },
+        isRepo: () => isRepoAt(repoRoot),
+        commitAll: (message) => {
+            if (!isRepoAt(repoRoot)) {
+                throw new Error("not a git repository — a commit phase needs one. Run `git init` in the " +
+                    "repo root (and make a first commit) before running an ADW that commits.");
+            }
+            run(["add", "-A"]);
+            if (!run(["status", "--porcelain"])) {
+                throw new Error("nothing to commit — the preceding phases changed no files");
+            }
+            run(["commit", "-m", message]);
+            return run(["rev-parse", "--short", "HEAD"]);
+        },
+        changedFiles: () => {
+            const out = run(["status", "--porcelain"]);
+            return out.split("\n").filter(Boolean).map((line) => line.slice(3));
+        },
+        refExists: (ref) => {
+            const result = spawnSync("git", ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`], {
+                cwd: repoRoot,
+                encoding: "utf-8",
+            });
+            return result.status === 0;
+        },
+        rev: (ref = "HEAD") => run(["rev-parse", ref]),
+        shortSha: (ref = "HEAD") => run(["rev-parse", "--short", ref]),
+        mergeBase: (ref, other = "HEAD") => run(["merge-base", ref, other]),
+        isDirty: () => Boolean(run(["status", "--porcelain"])),
+        untrackedFiles: () => {
+            const out = run(["ls-files", "--others", "--exclude-standard"]);
+            return out.split("\n").filter(Boolean);
+        },
+        diffFiles: (base) => {
+            const out = run(["diff", "--name-only", base]);
+            return out.split("\n").filter(Boolean);
+        },
+        diffStat: (base) => run(["diff", "--stat", base]),
+        diffCounts: (base) => {
+            let insertions = 0;
+            let deletions = 0;
+            for (const line of run(["diff", "--numstat", base]).split("\n")) {
+                if (!line)
+                    continue;
+                const [added, removed] = line.split("\t");
+                if (/^\d+$/.test(added))
+                    insertions += parseInt(added, 10);
+                if (/^\d+$/.test(removed))
+                    deletions += parseInt(removed, 10);
+            }
+            return [insertions, deletions];
+        },
+        diffText: (base) => run(["diff", base]),
+        fetch: (remote, ref) => {
+            run(["fetch", remote, ref]);
+        },
+        worktreeAdd: (worktreePath, branch, startPoint) => {
+            run(["worktree", "add", worktreePath, "-b", branch, startPoint]);
+        },
+        worktreeRemove: (worktreePath) => {
+            spawnSync("git", ["worktree", "remove", worktreePath, "--force"], { cwd: repoRoot, encoding: "utf-8" });
+        },
+        deleteLocalBranch: (name) => {
+            spawnSync("git", ["branch", "-D", name], { cwd: repoRoot, encoding: "utf-8" });
+        },
+        push: (remote, branch) => {
+            run(["push", "-u", remote, branch]);
+        },
+    };
+}

package/dist/core/issues/github_provider.d.ts

@@ -0,0 +1,52 @@
+/**
+ * GitHub REST implementation of `IssueProvider`, via Node 22's native
+ * `fetch()` — deliberately not `octokit`: the full `octokit` meta-package
+ * resolves to ~82MB of installed dependencies (`@octokit/app`,
+ * `oauth-app`, `webhooks`, ...) for what `spf watch` actually needs, which
+ * is six REST calls. `spf`'s own package stays dependency-free either way.
+ *
+ * Auth is a classic PAT via `GITHUB_TOKEN` (`repo` scope), read once at
+ * construction — matching the reference implementation's pattern and this
+ * project's existing env-var-for-credentials philosophy. No pagination
+ * beyond one page of 100: fine for the label-scoped queries a lean v1
+ * makes (a repo with >100 open `<prefix>:ready` issues at once is not this
+ * version's problem to solve).
+ */
+import type { EnsureLabelsResult, Issue, IssueProvider, PrRef, PrStatus, WatchMarker, WatchState } from "./provider.ts";
+export declare class GitHubProvider implements IssueProvider {
+    private readonly repo;
+    private readonly labelPrefix;
+    private readonly token;
+    constructor(repo: string, // "owner/name"
+    labelPrefix: string, token: string);
+    private gh;
+    private label;
+    /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
+    private getLabel;
+    /**
+     * Idempotent by inspection, not by "create and catch a 422": GET each
+     * label first, then create/update/leave alone depending on what's
+     * actually there. One fewer request in the common "already correct"
+     * case, and no brittle matching against GitHub's error-message text.
+     */
+    ensureLabels(): Promise<EnsureLabelsResult>;
+    private toIssue;
+    private listByLabel;
+    listEligible(): Promise<Issue[]>;
+    listInState(state: WatchState, opts?: {
+        includeAll?: boolean;
+    }): Promise<Issue[]>;
+    claim(issue: Issue): Promise<boolean>;
+    transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    comment(issue: Issue, body: string): Promise<void>;
+    openPr(issue: Issue, opts: {
+        branch: string;
+        title: string;
+        body: string;
+        base: string;
+    }): Promise<PrRef>;
+    prStatus(pr: PrRef): Promise<PrStatus>;
+    private findMarkerComment;
+    readMarker(issue: Issue): Promise<WatchMarker | null>;
+    writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
+}

package/dist/core/issues/github_provider.js

@@ -0,0 +1,211 @@
+const API = "https://api.github.com";
+const STATES = ["ready", "working", "review", "done", "blocked"];
+const MARKER_RE = /<!--\s*spf-watch:\s*(\{.*?\})\s*-->/s;
+// GitHub label colors are 6 hex digits, no leading '#'.
+const LABEL_META = {
+    ready: { color: "0e8a16", description: "spf watch will claim this issue on its next poll" },
+    working: { color: "fbca04", description: "spf watch has claimed this issue and is running a chain against it" },
+    review: { color: "1d76db", description: "spf watch opened a PR for this issue — awaiting merge" },
+    done: { color: "5319e7", description: "spf watch's PR for this issue merged" },
+    blocked: { color: "d93f0b", description: "spf watch gave up — needs a human" },
+};
+export class GitHubProvider {
+    repo;
+    labelPrefix;
+    token;
+    constructor(repo, // "owner/name"
+    labelPrefix, token) {
+        this.repo = repo;
+        this.labelPrefix = labelPrefix;
+        this.token = token;
+    }
+    async gh(path, init) {
+        const response = await fetch(`${API}${path}`, {
+            ...init,
+            headers: {
+                Authorization: `Bearer ${this.token}`,
+                Accept: "application/vnd.github+json",
+                "X-GitHub-Api-Version": "2022-11-28",
+                ...(init?.body ? { "Content-Type": "application/json" } : {}),
+                ...init?.headers,
+            },
+        });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`GitHub ${init?.method ?? "GET"} ${path} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        if (response.status === 204)
+            return undefined;
+        return (await response.json());
+    }
+    label(state) {
+        return `${this.labelPrefix}:${state}`;
+    }
+    /** `null` on a real 404 (label doesn't exist yet) — any other non-2xx still throws, same as `gh()`. */
+    async getLabel(name) {
+        const response = await fetch(`${API}/repos/${this.repo}/labels/${encodeURIComponent(name)}`, {
+            headers: { Authorization: `Bearer ${this.token}`, Accept: "application/vnd.github+json", "X-GitHub-Api-Version": "2022-11-28" },
+        });
+        if (response.status === 404)
+            return null;
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            throw new Error(`GitHub GET /repos/${this.repo}/labels/${name} -> ${response.status}: ${detail.slice(0, 500)}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Idempotent by inspection, not by "create and catch a 422": GET each
+     * label first, then create/update/leave alone depending on what's
+     * actually there. One fewer request in the common "already correct"
+     * case, and no brittle matching against GitHub's error-message text.
+     */
+    async ensureLabels() {
+        const created = [];
+        const updated = [];
+        const unchanged = [];
+        for (const state of STATES) {
+            const name = this.label(state);
+            const { color, description } = LABEL_META[state];
+            const existing = await this.getLabel(name);
+            if (!existing) {
+                await this.gh(`/repos/${this.repo}/labels`, { method: "POST", body: JSON.stringify({ name, color, description }) });
+                created.push(name);
+            }
+            else if (existing.color !== color || (existing.description ?? "") !== description) {
+                await this.gh(`/repos/${this.repo}/labels/${encodeURIComponent(name)}`, {
+                    method: "PATCH",
+                    body: JSON.stringify({ color, description }),
+                });
+                updated.push(name);
+            }
+            else {
+                unchanged.push(name);
+            }
+        }
+        return { created, updated, unchanged };
+    }
+    toIssue(raw) {
+        return {
+            number: raw.number,
+            title: raw.title,
+            body: raw.body ?? "",
+            labels: raw.labels.map((l) => (typeof l === "string" ? l : l.name)),
+        };
+    }
+    async listByLabel(label, state) {
+        const raw = await this.gh(`/repos/${this.repo}/issues?labels=${encodeURIComponent(label)}&state=${state}&per_page=100`);
+        return raw.filter((i) => !i.pull_request).map((i) => this.toIssue(i));
+    }
+    async listEligible() {
+        return this.listByLabel(this.label("ready"), "open");
+    }
+    async listInState(state, opts) {
+        return this.listByLabel(this.label(state), opts?.includeAll ? "all" : "open");
+    }
+    async claim(issue) {
+        await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels/${encodeURIComponent(this.label("ready"))}`, {
+            method: "DELETE",
+        }).catch(() => undefined); // already gone is fine
+        await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels`, {
+            method: "POST",
+            body: JSON.stringify({ labels: [this.label("working")] }),
+        });
+        const fresh = await this.gh(`/repos/${this.repo}/issues/${issue.number}`);
+        const labels = this.toIssue(fresh).labels;
+        const claimed = labels.includes(this.label("working")) && !labels.includes(this.label("ready"));
+        if (!claimed) {
+            // Lost the race (or something else relabeled it) — put ready back so it's not stuck.
+            await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels`, {
+                method: "POST",
+                body: JSON.stringify({ labels: [this.label("ready")] }),
+            }).catch(() => undefined);
+        }
+        return claimed;
+    }
+    async transition(issue, to, detail) {
+        for (const state of STATES) {
+            const label = this.label(state);
+            if (issue.labels.includes(label)) {
+                await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels/${encodeURIComponent(label)}`, { method: "DELETE" }).catch(() => undefined);
+            }
+        }
+        await this.gh(`/repos/${this.repo}/issues/${issue.number}/labels`, {
+            method: "POST",
+            body: JSON.stringify({ labels: [this.label(to)] }),
+        });
+        if (detail)
+            await this.comment(issue, detail);
+    }
+    async comment(issue, body) {
+        await this.gh(`/repos/${this.repo}/issues/${issue.number}/comments`, {
+            method: "POST",
+            body: JSON.stringify({ body }),
+        });
+    }
+    async openPr(issue, opts) {
+        // Belt-and-suspenders: ensure the PR body closes the issue even if the
+        // caller's body forgot to say so — this is how `finishReviews`-style
+        // merge polling knows an issue's work landed at all.
+        const closesTag = `Closes #${issue.number}`;
+        const body = opts.body.includes(closesTag) ? opts.body : `${opts.body}\n\n${closesTag}`;
+        const pr = await this.gh(`/repos/${this.repo}/pulls`, {
+            method: "POST",
+            body: JSON.stringify({ title: opts.title, body, head: opts.branch, base: opts.base }),
+        });
+        return { number: pr.number, branch: opts.branch, url: pr.html_url };
+    }
+    async prStatus(pr) {
+        const detail = await this.gh(`/repos/${this.repo}/pulls/${pr.number}`);
+        let ciStatus = "pending";
+        try {
+            const checks = await this.gh(`/repos/${this.repo}/commits/${detail.head.sha}/check-runs?per_page=100`);
+            if (checks.check_runs.length === 0) {
+                ciStatus = "pending"; // no checks configured — never blocks a lean v1's own polling
+            }
+            else if (checks.check_runs.some((c) => c.status !== "completed")) {
+                ciStatus = "pending";
+            }
+            else if (checks.check_runs.some((c) => ["failure", "timed_out", "cancelled", "action_required"].includes(c.conclusion ?? ""))) {
+                ciStatus = "failure";
+            }
+            else {
+                ciStatus = "success";
+            }
+        }
+        catch {
+            ciStatus = "pending"; // check-runs lookup failing shouldn't block merge/close detection
+        }
+        return { merged: detail.merged, state: detail.state, ciStatus };
+    }
+    async findMarkerComment(issueNumber) {
+        const comments = await this.gh(`/repos/${this.repo}/issues/${issueNumber}/comments?per_page=100`);
+        let found = null;
+        for (const c of comments) {
+            const match = MARKER_RE.exec(c.body || "");
+            if (!match)
+                continue;
+            try {
+                found = { id: c.id, marker: JSON.parse(match[1]) };
+            }
+            catch {
+                // malformed marker JSON — tolerate it and keep looking, like the reference implementation does
+            }
+        }
+        return found;
+    }
+    async readMarker(issue) {
+        const found = await this.findMarkerComment(issue.number);
+        return found?.marker ?? null;
+    }
+    async writeMarker(issue, marker) {
+        const body = `<!-- spf-watch: ${JSON.stringify(marker)} -->`;
+        const existing = await this.findMarkerComment(issue.number);
+        if (existing) {
+            await this.gh(`/repos/${this.repo}/issues/comments/${existing.id}`, { method: "PATCH", body: JSON.stringify({ body }) });
+        }
+        else {
+            await this.gh(`/repos/${this.repo}/issues/${issue.number}/comments`, { method: "POST", body: JSON.stringify({ body }) });
+        }
+    }
+}

package/dist/core/issues/provider.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The issue-tracker seam `spf watch` drives — the abstraction the user's own
+ * reference implementation (a GitHub-issues SDLC poller) never had: its
+ * GitHub client is a concrete class referenced by type everywhere, so
+ * adding a second tracker would mean reworking the poll loop itself. Here,
+ * nothing outside `github_provider.ts` (or a future `jira_provider.ts`)
+ * knows it's talking to GitHub.
+ *
+ * The label-as-state-machine design is deliberate, copied from that same
+ * reference: `transition()` is the ONE mutator, so every state change is
+ * traceable to one call site, and a provider can layer notifications
+ * (Slack, a webhook, whatever) on top of it without the poll loop caring.
+ */
+export type WatchState = "ready" | "working" | "review" | "done" | "blocked";
+export interface Issue {
+    number: number;
+    title: string;
+    body: string;
+    labels: string[];
+}
+export interface PrRef {
+    number: number;
+    branch: string;
+    url: string;
+}
+export interface PrStatus {
+    merged: boolean;
+    state: "open" | "closed";
+    ciStatus: "pending" | "success" | "failure";
+}
+/**
+ * The durable scratch state for one issue, stored as a hidden HTML comment
+ * on the issue itself — zero infrastructure, survives a daemon crash,
+ * human-readable. `attempt` bounds orphan-retry (see `watch.ts`); `ciFixes`
+ * is reserved for a future fix-loop, unused by the lean v1 poll logic.
+ */
+export interface WatchMarker {
+    worktree?: string;
+    branch?: string;
+    pr?: number;
+    attempt?: number;
+}
+/** What `ensureLabels()` actually did, per label — for `spf watch init`'s report. */
+export interface EnsureLabelsResult {
+    created: string[];
+    updated: string[];
+    unchanged: string[];
+}
+export interface IssueProvider {
+    /**
+     * Idempotently seed whatever this tracker needs for the state machine to
+     * work at all — GitHub: the five `<prefix>:*` labels, with a color and
+     * description, created if missing and corrected if drifted. A tracker
+     * with no such concept (a future one might model state entirely as a
+     * workflow field) can make this a no-op — `spf watch init` just reports
+     * whatever comes back, empty results included.
+     */
+    ensureLabels(): Promise<EnsureLabelsResult>;
+    /** Issues currently labeled `<prefix>:ready`. */
+    listEligible(): Promise<Issue[]>;
+    /**
+     * Issues currently in `state`. `includeAll` queries closed issues too —
+     * required for `review`, since GitHub (or any tracker with a `Closes #n`
+     * convention) can auto-close an issue the instant its PR merges, often
+     * before the next poll tick runs; an open-only query would let it vanish
+     * from tracking forever.
+     */
+    listInState(state: WatchState, opts?: {
+        includeAll?: boolean;
+    }): Promise<Issue[]>;
+    /**
+     * Move `ready` -> `working`, with a read-back verify (like the reference
+     * implementation's `claimIssue`) — not a true atomic claim, but enough to
+     * catch the common case; the real safety net against two daemons racing
+     * the same issue is `spf watch`'s own single-instance lockfile.
+     */
+    claim(issue: Issue): Promise<boolean>;
+    /** The one state-mutating call. `detail`, if given, is also posted as a comment. */
+    transition(issue: Issue, to: WatchState, detail?: string): Promise<void>;
+    comment(issue: Issue, body: string): Promise<void>;
+    openPr(issue: Issue, opts: {
+        branch: string;
+        title: string;
+        body: string;
+        base: string;
+    }): Promise<PrRef>;
+    prStatus(pr: PrRef): Promise<PrStatus>;
+    readMarker(issue: Issue): Promise<WatchMarker | null>;
+    writeMarker(issue: Issue, marker: WatchMarker): Promise<void>;
+}

package/dist/core/issues/provider.js

@@ -0,0 +1,14 @@
+/**
+ * The issue-tracker seam `spf watch` drives — the abstraction the user's own
+ * reference implementation (a GitHub-issues SDLC poller) never had: its
+ * GitHub client is a concrete class referenced by type everywhere, so
+ * adding a second tracker would mean reworking the poll loop itself. Here,
+ * nothing outside `github_provider.ts` (or a future `jira_provider.ts`)
+ * knows it's talking to GitHub.
+ *
+ * The label-as-state-machine design is deliberate, copied from that same
+ * reference: `transition()` is the ONE mutator, so every state change is
+ * traceable to one call site, and a provider can layer notifications
+ * (Slack, a webhook, whatever) on top of it without the poll loop caring.
+ */
+export {};

package/dist/core/paths.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The workspace anchor: the one place `process.cwd()` is read, and the one
+ * place that decides what "the repo" means for a run.
+ *
+ * Everything downstream — session dirs, the trace db, gate checks, git
+ * operations — is anchored to `repo_root`, an absolute path, never to
+ * whatever directory the process happened to be started from. Before this
+ * module existed, those two were silently assumed to be the same directory;
+ * a chain launched from a subdirectory (or, later, by a globally-installed
+ * CLI run from an arbitrary cwd) would resolve config/prompts/gates against
+ * one anchor and git/agent-subprocess work against another.
+ *
+ * This is also where the packaged built-in defaults live, relative to this
+ * module's own location — `PACKAGE_ROOT` is two directories up from
+ * `dist/core/paths.js` (or `src/core/paths.ts` run directly; both are two
+ * levels below the package root, so the same relative path resolves either
+ * way), with `assets/` a direct child of it.
+ */
+export declare const PACKAGE_ROOT: string;
+export declare const ASSETS_DIR: string;
+/** The prebuilt SPA — a sibling of dist/ and assets/, built once at publish time (see app/). */
+export declare const WEB_DIR: string;
+export declare const BUILTIN_CONFIG_PATH: string;
+export declare const BUILTIN_PROMPTS_DIR: string;
+export interface RepoAnchor {
+    /** The invocation cwd this anchor was resolved from (already absolute). */
+    cwd: string;
+    /** Git toplevel containing `cwd`, or `cwd` itself if it's not a repo. Always absolute. */
+    repo_root: string;
+    /** Nearest `.spf/` directory walking up from `cwd`, capped at `repo_root`. `null` if none exists. */
+    spf_dir: string | null;
+}
+/** Resolve the repo anchor. `cwd` defaults to `process.cwd()` — read here, once. */
+export declare function resolveAnchor(cwd?: string): RepoAnchor;
+export interface ConfigResolution {
+    /** In load order — later paths override earlier ones (agents.loadConfig). */
+    paths: string[];
+    source: "explicit" | "spf-dir" | "built-in-only";
+}
+/**
+ * Where the config is, given an optional explicit `--config`.
+ *
+ * An explicit path is used STANDALONE — no merge with the built-in defaults,
+ * because naming a file is "use exactly this." Otherwise the built-in
+ * packaged config always loads first, and a discovered `.spf/spf.config.yaml`
+ * merges on top of it if one exists — this is the "override one field"
+ * path, via agents.loadConfig's merge.
+ */
+export declare function resolveConfigPaths(anchor: RepoAnchor, explicit?: string): ConfigResolution;
+export interface DataPaths {
+    /** Absolute — for every fs call. */
+    data_dir: string;
+    /** Repo-root-relative, forward-slash — for matching against git's own path output. */
+    data_dir_rel: string;
+    /** Absolute. */
+    db_path: string;
+    /** Absolute. ALWAYS a sibling of `db_path` — relocating `data_dir` must never break this. */
+    sessions_dir: string;
+}
+/**
+ * Anchor a config's own `data_dir`/`observability.db` (as loaded — relative
+ * or absolute, whichever the YAML says) to `repo_root`.
+ *
+ * Deliberately does NOT touch the config object itself: `permissions.
+ * alwaysWritable()` matches `cfg.defaults.data_dir` against repo-relative git
+ * output, so that field stays exactly as configured. This produces a
+ * parallel, absolute set of paths for filesystem use instead of mutating it.
+ */
+export declare function resolveDataPaths(anchor: RepoAnchor, rawDataDir: string, rawDbPath: string): DataPaths;
+/**
+ * Resolve a prompt ref (a `prompt_engineering.system`/`.user` value from
+ * config) to an absolute path, trying every root a ref could sensibly be
+ * written against. An absolute ref passes through unchanged. Throws naming
+ * every path it tried on a total miss — closing the historical "no fallback
+ * if a prompt file is missing" gap, where a bad ref just threw ENOENT deep
+ * inside readFileSync with no context.
+ */
+export declare function resolvePromptRef(anchor: Pick<RepoAnchor, "repo_root" | "spf_dir">, ref: string): string;

package/dist/core/paths.js

@@ -0,0 +1,108 @@
+/**
+ * The workspace anchor: the one place `process.cwd()` is read, and the one
+ * place that decides what "the repo" means for a run.
+ *
+ * Everything downstream — session dirs, the trace db, gate checks, git
+ * operations — is anchored to `repo_root`, an absolute path, never to
+ * whatever directory the process happened to be started from. Before this
+ * module existed, those two were silently assumed to be the same directory;
+ * a chain launched from a subdirectory (or, later, by a globally-installed
+ * CLI run from an arbitrary cwd) would resolve config/prompts/gates against
+ * one anchor and git/agent-subprocess work against another.
+ *
+ * This is also where the packaged built-in defaults live, relative to this
+ * module's own location — `PACKAGE_ROOT` is two directories up from
+ * `dist/core/paths.js` (or `src/core/paths.ts` run directly; both are two
+ * levels below the package root, so the same relative path resolves either
+ * way), with `assets/` a direct child of it.
+ */
+import { existsSync, statSync } from "node:fs";
+import path from "node:path";
+import { findRepoRoot } from "./git_helper.js";
+export const PACKAGE_ROOT = path.resolve(import.meta.dirname, "..", "..");
+export const ASSETS_DIR = path.join(PACKAGE_ROOT, "assets");
+/** The prebuilt SPA — a sibling of dist/ and assets/, built once at publish time (see app/). */
+export const WEB_DIR = path.join(PACKAGE_ROOT, "web");
+export const BUILTIN_CONFIG_PATH = path.join(ASSETS_DIR, "defaults", "spf.config.yaml");
+export const BUILTIN_PROMPTS_DIR = path.join(ASSETS_DIR, "prompts");
+/** Walk up from `cwd` to (and including) `repoRoot` looking for a `.spf/` directory. */
+function findSfDir(cwd, repoRoot) {
+    let dir = cwd;
+    while (true) {
+        const candidate = path.join(dir, ".spf");
+        if (existsSync(candidate) && statSync(candidate).isDirectory())
+            return candidate;
+        if (dir === repoRoot)
+            return null;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null; // filesystem root — stop
+        dir = parent;
+    }
+}
+/** Resolve the repo anchor. `cwd` defaults to `process.cwd()` — read here, once. */
+export function resolveAnchor(cwd) {
+    const resolvedCwd = path.resolve(cwd ?? process.cwd());
+    const repo_root = findRepoRoot(resolvedCwd);
+    return { cwd: resolvedCwd, repo_root, spf_dir: findSfDir(resolvedCwd, repo_root) };
+}
+/**
+ * Where the config is, given an optional explicit `--config`.
+ *
+ * An explicit path is used STANDALONE — no merge with the built-in defaults,
+ * because naming a file is "use exactly this." Otherwise the built-in
+ * packaged config always loads first, and a discovered `.spf/spf.config.yaml`
+ * merges on top of it if one exists — this is the "override one field"
+ * path, via agents.loadConfig's merge.
+ */
+export function resolveConfigPaths(anchor, explicit) {
+    if (explicit)
+        return { paths: [path.resolve(anchor.cwd, explicit)], source: "explicit" };
+    if (anchor.spf_dir) {
+        const override = path.join(anchor.spf_dir, "spf.config.yaml");
+        if (existsSync(override))
+            return { paths: [BUILTIN_CONFIG_PATH, override], source: "spf-dir" };
+    }
+    return { paths: [BUILTIN_CONFIG_PATH], source: "built-in-only" };
+}
+/**
+ * Anchor a config's own `data_dir`/`observability.db` (as loaded — relative
+ * or absolute, whichever the YAML says) to `repo_root`.
+ *
+ * Deliberately does NOT touch the config object itself: `permissions.
+ * alwaysWritable()` matches `cfg.defaults.data_dir` against repo-relative git
+ * output, so that field stays exactly as configured. This produces a
+ * parallel, absolute set of paths for filesystem use instead of mutating it.
+ */
+export function resolveDataPaths(anchor, rawDataDir, rawDbPath) {
+    const data_dir = path.resolve(anchor.repo_root, rawDataDir);
+    const data_dir_rel = path.relative(anchor.repo_root, data_dir).split(path.sep).join("/");
+    const db_path = path.resolve(anchor.repo_root, rawDbPath);
+    const sessions_dir = path.resolve(path.dirname(db_path), "sessions");
+    return { data_dir, data_dir_rel, db_path, sessions_dir };
+}
+/**
+ * Resolve a prompt ref (a `prompt_engineering.system`/`.user` value from
+ * config) to an absolute path, trying every root a ref could sensibly be
+ * written against. An absolute ref passes through unchanged. Throws naming
+ * every path it tried on a total miss — closing the historical "no fallback
+ * if a prompt file is missing" gap, where a bad ref just threw ENOENT deep
+ * inside readFileSync with no context.
+ */
+export function resolvePromptRef(anchor, ref) {
+    if (path.isAbsolute(ref)) {
+        if (existsSync(ref))
+            return ref;
+        throw new Error(`prompt ref not found: ${ref}`);
+    }
+    const candidates = [path.join(anchor.repo_root, ref)];
+    if (anchor.spf_dir) {
+        candidates.push(path.join(anchor.spf_dir, ref), path.join(anchor.spf_dir, "prompt_engineering", ref));
+    }
+    candidates.push(path.join(ASSETS_DIR, ref), path.join(BUILTIN_PROMPTS_DIR, ref));
+    for (const candidate of candidates) {
+        if (existsSync(candidate) && statSync(candidate).isFile())
+            return candidate;
+    }
+    throw new Error(`prompt ref ${JSON.stringify(ref)} not found — tried:\n  ${candidates.join("\n  ")}`);
+}