memarium 0.13.1

package/dist/src/git-ops.js

@@ -0,0 +1,359 @@
+import { simpleGit } from "simple-git";
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+/**
+ * Expand a leading `~` to the user's home dir. (Shell expansion doesn't
+ * happen for prompt input — `~/edge` would be taken literally otherwise.)
+ */
+export function expandHome(p) {
+    if (p === "~")
+        return homedir();
+    if (p.startsWith("~/"))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+/**
+ * Clone with stdio inherited so git's terminal-based credential prompts
+ * (HTTPS username/password, SSH passphrase) actually reach the user instead
+ * of hanging forever on a piped FD that no one writes to. Also sets
+ * GIT_TERMINAL_PROMPT=0 when stdin isn't a TTY so the call fails fast in CI
+ * instead of hanging.
+ */
+function cloneWithProgress(repoUrl, dest) {
+    return new Promise((resolve, reject) => {
+        const env = { ...process.env };
+        if (!process.stdin.isTTY)
+            env.GIT_TERMINAL_PROMPT = "0";
+        const p = spawn("git", ["clone", "--progress", repoUrl, dest], {
+            stdio: "inherit",
+            env,
+        });
+        p.on("error", reject);
+        p.on("close", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`git clone exited with code ${code}. If this is an HTTPS URL needing auth, prefer SSH (git@github.com:...) or store a PAT via 'git config credential.helper'.`));
+        });
+    });
+}
+/**
+ * Make sure `localPath` contains the repo at `repoUrl`.
+ *
+ * - If `localPath` doesn't exist OR exists-and-empty → `git clone repoUrl
+ *   localPath`. Returns kind:"cloned".
+ * - If `localPath` exists and contains `.git` → reuse. Returns kind:"existing"
+ *   with `existingRemote` so the wizard can warn on URL mismatch. Does NOT
+ *   change the existing remote.
+ * - If `localPath` exists, non-empty, no `.git` → throw with a friendly
+ *   message; refuse to scribble inside an unrelated dir.
+ */
+export async function materializeRepoAtPath(localPath, repoUrl) {
+    const path = resolve(expandHome(localPath));
+    if (!existsSync(path)) {
+        mkdirSync(path, { recursive: true });
+        await cloneWithProgress(repoUrl, path);
+        return { kind: "cloned" };
+    }
+    const entries = readdirSync(path);
+    if (entries.length === 0) {
+        await cloneWithProgress(repoUrl, path);
+        return { kind: "cloned" };
+    }
+    if (entries.includes(".git")) {
+        const git = simpleGit(path);
+        let remote = "";
+        try {
+            remote = (await git.getConfig("remote.origin.url")).value ?? "";
+        }
+        catch { /* no remote configured */ }
+        return { kind: "existing", existingRemote: remote };
+    }
+    throw new Error(`${path} is not empty and is not a git repo. Pick another path or empty this one first.`);
+}
+/**
+ * Adopt a non-git directory full of memarium-plugin output into a fresh git
+ * repo bound to `repoUrl`. Use case: user installed memarium-plugin first,
+ * which wrote `book/` and `raw_sessions/` under `~/.memarium/session-repo/`
+ * but never `git init`'d. Then the user installs the npm CLI and runs
+ * `memarium init` — the dir is non-empty but not git, so the strict
+ * materialize path refuses.
+ *
+ * Safety:
+ * - All existing files are preserved on disk; this never deletes or moves.
+ * - The fetch is "info-only" — we don't checkout any remote ref, so user
+ *   files can't be overwritten by `main`.
+ * - The user lands on a brand-new branch `<deviceBranch>` with their
+ *   existing files as the first commit. Next `memarium sync` will append
+ *   normally; first push creates the branch upstream.
+ *
+ * The caller (init wizard) is responsible for prompting the user before
+ * calling this — adopting silently would surprise users.
+ */
+export async function adoptPluginDir(localPath, repoUrl, deviceBranch) {
+    const path = resolve(expandHome(localPath));
+    if (!existsSync(path)) {
+        throw new Error(`adoptPluginDir: ${path} does not exist`);
+    }
+    if (existsSync(join(path, ".git"))) {
+        throw new Error(`adoptPluginDir: ${path} already has a .git dir; use materializeRepoAtPath instead`);
+    }
+    const git = simpleGit(path);
+    await git.init();
+    await git.addRemote("origin", repoUrl);
+    try {
+        // Fetch refs so the user has a reference to `origin/main` for merge
+        // later, but don't checkout anything — the working tree is exactly
+        // what the user (well, the plugin) put there, and we want to preserve
+        // it as the first commit on a fresh device branch.
+        await git.fetch("origin");
+    }
+    catch {
+        // Offline or bad URL — adopt continues; user can fetch later.
+    }
+    await git.checkoutLocalBranch(deviceBranch);
+    return { kind: "adopted" };
+}
+export async function ensureRepo(localPath, repoUrl) {
+    await materializeRepoAtPath(localPath, repoUrl);
+    const git = simpleGit(localPath);
+    if (!existsSync(join(localPath, ".git"))) {
+        await git.init();
+        await git.addRemote("origin", repoUrl).catch(() => { });
+    }
+    return git;
+}
+/**
+ * Make sure the working tree is on `branch`.
+ * Priority:
+ *   1. Local branch exists → checkout.
+ *   2. Remote `origin/<branch>` exists → checkout tracking branch.
+ *   3. Neither → create as orphan (empty history, no parent).
+ */
+export async function ensureDeviceBranch(git, branch) {
+    const local = await git.branchLocal();
+    if (local.all.includes(branch)) {
+        if (local.current !== branch)
+            await git.checkout(branch);
+        return;
+    }
+    let remoteHas = false;
+    try {
+        const remote = await git.branch(["-r"]);
+        remoteHas = remote.all.includes(`origin/${branch}`);
+    }
+    catch { /* no remotes fetched yet */ }
+    if (remoteHas) {
+        await git.checkout(["-b", branch, "--track", `origin/${branch}`]);
+        return;
+    }
+    await git.checkout(["--orphan", branch]);
+    await git.raw(["rm", "-rf", "--cached", "--ignore-unmatch", "."]);
+}
+const SECRET_BLOCK_RE = /GH013|push protection|secret-scanning/i;
+function pushWithProgress(cwd, branch) {
+    return new Promise((resolve) => {
+        const errBuf = [];
+        let bufLen = 0;
+        const p = spawn("git", ["push", "--progress", "--set-upstream", "origin", branch], { cwd, stdio: ["ignore", "inherit", "pipe"] });
+        p.stderr.on("data", (chunk) => {
+            // Tee to both terminal (so live progress still shows) AND buffer (so we
+            // can scan for GitHub push-protection markers after exit).
+            process.stderr.write(chunk);
+            const s = chunk.toString();
+            errBuf.push(s);
+            bufLen += s.length;
+            if (bufLen > 8192) {
+                const drop = errBuf.shift();
+                if (drop)
+                    bufLen -= drop.length;
+            }
+        });
+        p.on("error", () => resolve({ ok: false, secretBlocked: false, stderrTail: errBuf.join("") }));
+        p.on("close", (code) => {
+            const tail = errBuf.join("");
+            resolve({
+                ok: code === 0,
+                secretBlocked: code !== 0 && SECRET_BLOCK_RE.test(tail),
+                stderrTail: tail.slice(-4096),
+            });
+        });
+    });
+}
+export async function commitAndPush(git, message, paths, branch, onProgress) {
+    if (paths.length === 0)
+        return { committed: false, pushed: false };
+    onProgress?.(`git add (${paths.length} paths)...`);
+    await git.add(paths);
+    const status = await git.status();
+    if (status.staged.length === 0)
+        return { committed: false, pushed: false };
+    onProgress?.(`git commit (${status.staged.length} staged)...`);
+    await git.commit(message);
+    onProgress?.(`git push origin ${branch} (live progress below):`);
+    const cwd = await git.revparse(["--show-toplevel"]).then((s) => s.trim());
+    const r = await pushWithProgress(cwd, branch);
+    return { committed: true, pushed: r.ok, pushResult: r };
+}
+/**
+ * Run `writeFiles()` on a temporary side-checkout of `main` (or create main
+ * as an orphan if it doesn't exist remotely), commit + push, then restore
+ * the caller's current branch. Used by `memarium workflow init` so CI
+ * workflow files land on main (where GitHub Actions actually reads them)
+ * without disturbing the user's device branch or working tree.
+ *
+ * Strategy: use `git worktree add` to materialize main into a temp dir.
+ * This avoids switching the user's primary working tree at all — their
+ * uncommitted changes, current HEAD, and checked-out branch are untouched.
+ *
+ * The provided `writeFiles(worktreePath)` callback receives the absolute
+ * path of the temp worktree and is responsible for writing the files there.
+ *
+ * On success returns `{ committed: true, pushed: true }`. On no-op (files
+ * already up to date) returns `{ committed: false, pushed: false }`. The
+ * temp worktree is always cleaned up.
+ */
+export async function commitToMainViaWorktree(git, repoPath, writeFiles, commitMessage, onProgress) {
+    const { mkdtempSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    // Fetch so we know whether origin/main exists.
+    try {
+        await git.fetch();
+    }
+    catch { /* offline */ }
+    const remoteMainExists = (await git.branch(["-r"]))
+        .all.some((b) => b === "origin/main");
+    const worktreePath = mkdtempSync(join(tmpdir(), "memarium-main-"));
+    // Use a unique temp branch name (not "main") to avoid the worktree conflict
+    // git raises if the user's primary working tree is currently on `main`:
+    //   fatal: 'main' is already used by worktree at <repoPath>
+    // We push to origin/main via `HEAD:main` refspec instead of relying on a
+    // locally-named branch.
+    const tempBranch = `memarium-tmp-main-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // simple-git doesn't expose worktree directly; use raw.
+    try {
+        if (remoteMainExists) {
+            onProgress?.(`creating temp worktree on main (via ${tempBranch})...`);
+            // -b <tempBranch> at origin/main: create the new branch in the worktree.
+            // This new branch ref lives in the primary repo (not the worktree only),
+            // so we delete it in finally.
+            await git.raw(["worktree", "add", "-b", tempBranch, worktreePath, "origin/main"]);
+        }
+        else {
+            // Brand-new repo with no main yet. Create an orphan branch (not named main).
+            onProgress?.(`creating orphan temp branch ${tempBranch} (no remote main yet)...`);
+            await git.raw(["worktree", "add", "--detach", worktreePath]);
+            const { simpleGit } = await import("simple-git");
+            const wgit = simpleGit(worktreePath);
+            await wgit.raw(["checkout", "--orphan", tempBranch]);
+            // Clear any inherited files from the parent ref.
+            await wgit.raw(["rm", "-rf", "."]).catch(() => undefined);
+        }
+        onProgress?.(`writing files into temp worktree...`);
+        const relPaths = await writeFiles(worktreePath);
+        const { simpleGit } = await import("simple-git");
+        const wgit = simpleGit(worktreePath);
+        await wgit.add(relPaths);
+        const status = await wgit.status();
+        if (status.staged.length === 0) {
+            onProgress?.(`nothing changed on main`);
+            return { committed: false, pushed: false };
+        }
+        onProgress?.(`git commit on ${tempBranch} (${status.staged.length} staged)...`);
+        await wgit.commit(commitMessage);
+        onProgress?.(`git push origin HEAD:main...`);
+        // Push the temp branch's HEAD to the remote `main` ref. This works
+        // whether or not we have a local `main` branch — we explicitly use
+        // a refspec.
+        try {
+            await wgit.raw(["push", "origin", `HEAD:main`]);
+        }
+        catch (err) {
+            throw new Error(`push origin HEAD:main failed: ${err.message}`);
+        }
+        return { committed: true, pushed: true };
+    }
+    finally {
+        // Always clean up the worktree AND the temp branch, even on failure.
+        // `git worktree remove` tolerates a missing dir; we follow it with a
+        // filesystem rm just in case. Then delete the temp branch ref so it
+        // doesn't leak into the user's repo.
+        try {
+            await git.raw(["worktree", "remove", "--force", worktreePath]);
+        }
+        catch { /* ignore */ }
+        try {
+            rmSync(worktreePath, { recursive: true, force: true });
+        }
+        catch { /* ignore */ }
+        try {
+            await git.branch(["-D", tempBranch]);
+        }
+        catch { /* ignore — never created */ }
+    }
+}
+/**
+ * Bring the local device branch in sync with origin before we try to push,
+ * so the GitHub Action's auto-commits don't cause non-fast-forward push
+ * failures on the next `memarium sync` / `digest` run.
+ *
+ * Sequence:
+ *   1. fetch origin
+ *   2. if no remote tracking ref exists → skip (fresh branch, nothing to pull)
+ *   3. try `pull --rebase --autostash` — handles both fast-forward and
+ *      diverged-history cases, and auto-stashes any unstaged digest output
+ *      sitting in the working tree
+ *   4. on rebase conflict: abort cleanly and throw a friendly error pointing
+ *      the user at the repo path. We deliberately do NOT try to auto-resolve
+ *      (digest output + rebased remote changes are too risky to merge blindly)
+ *
+ * Caller is expected to handle the thrown error — surface the path to the
+ * user and skip push for this run.
+ */
+export async function fastForwardBranch(git, branch, onProgress) {
+    let hasRemote = false;
+    try {
+        const remotes = await git.getRemotes(false);
+        hasRemote = remotes.some((r) => r.name === "origin");
+    }
+    catch { /* ignore */ }
+    if (!hasRemote)
+        return { pulled: false, reason: "no-remote" };
+    onProgress?.(`git fetch origin...`);
+    try {
+        await git.fetch("origin", branch);
+    }
+    catch { /* upstream branch may not exist yet */ }
+    // Check whether origin/<branch> ref exists locally after the fetch.
+    let hasUpstream = false;
+    try {
+        const refs = await git.branch(["-r"]);
+        hasUpstream = refs.all.includes(`origin/${branch}`);
+    }
+    catch { /* ignore */ }
+    if (!hasUpstream)
+        return { pulled: false, reason: "no-tracking" };
+    onProgress?.(`git pull --rebase --autostash origin ${branch}...`);
+    try {
+        await git.raw(["pull", "--rebase", "--autostash", "origin", branch]);
+        return { pulled: true };
+    }
+    catch (err) {
+        // Rebase conflict (or autostash-pop conflict). Clean up so we leave the
+        // working tree in a sane state, then throw with actionable guidance.
+        try {
+            await git.raw(["rebase", "--abort"]);
+        }
+        catch { /* not in rebase */ }
+        try {
+            await git.raw(["stash", "pop"]);
+        }
+        catch { /* nothing to pop */ }
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not fast-forward / rebase '${branch}' onto origin/${branch}. ` +
+            `Resolve manually in the repo, then re-run. Original error:\n${msg}`);
+    }
+}

package/dist/src/index-store.js

@@ -0,0 +1,35 @@
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { INDEX_REL, dataDirAbs } from "./repo-data-dir.js";
+export function loadIndex(repoRoot) {
+    const p = join(repoRoot, INDEX_REL);
+    if (!existsSync(p))
+        return { version: 1, entries: {} };
+    const parsed = JSON.parse(readFileSync(p, "utf8"));
+    if (parsed.version !== 1)
+        throw new Error(`unsupported index version: ${parsed.version}`);
+    return parsed;
+}
+export function saveIndex(repoRoot, idx) {
+    const p = join(repoRoot, INDEX_REL);
+    mkdirSync(dataDirAbs(repoRoot), { recursive: true });
+    writeFileSync(p, JSON.stringify(idx, null, 2) + "\n");
+}
+export function keyFor(tool, sessionId) {
+    return `${tool}:${sessionId}`;
+}
+export function upsertEntry(idx, entry) {
+    idx.entries[keyFor(entry.tool, entry.sessionId)] = entry;
+}
+export function hasUnchanged(idx, tool, sessionId, mtimeMs, sha256, repoRoot) {
+    const e = idx.entries[keyFor(tool, sessionId)];
+    if (!e || e.sourceMtimeMs !== mtimeMs || e.sourceSha256 !== sha256)
+        return false;
+    // The index can survive branch switches that leave raw_sessions/ incomplete
+    // — if the indexed file is missing from the working tree, treat it as stale
+    // so the entry gets re-extracted. Otherwise the new branch would never
+    // collect the file it's missing.
+    if (!existsSync(join(repoRoot, e.relativePath)))
+        return false;
+    return true;
+}

package/dist/src/migrate.js

@@ -0,0 +1,72 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { simpleGit } from "simple-git";
+import { LEGACY_REPO_DATA_DIRS, REPO_DATA_DIR } from "./repo-data-dir.js";
+/**
+ * One-shot migration for repos created before per-device-branches existed.
+ *
+ * If the local repo has a `main` branch but no `<device>` branch, rename
+ * main → <device> (preserving history) so the device branch becomes the
+ * new write target. `main` is left unborn on purpose — it will be re-created
+ * later (manually or by a future merge-to-main command) as the aggregate view.
+ *
+ * No-op when:
+ *   - the device branch already exists (migration was already done, or a
+ *     fresh clone is already on the right branch)
+ *   - there is no `main` branch to rename
+ */
+export async function migrateLegacyMainToDevice(repoPath, deviceBranch) {
+    const git = simpleGit(repoPath);
+    const local = await git.branchLocal();
+    if (local.all.includes(deviceBranch))
+        return { migrated: false };
+    if (!local.all.includes("main"))
+        return { migrated: false };
+    if (local.current !== "main")
+        await git.checkout("main");
+    await git.branch(["-m", "main", deviceBranch]);
+    return { migrated: true };
+}
+/**
+ * One-shot migration: rename an in-repo legacy data dir → `.memarium/`.
+ *
+ * The project was renamed memvc → vibebook → memarium. Any sync/digest run
+ * that finds a legacy dir (`.vibebook/`, else `.memvc/`) and no `.memarium/`
+ * moves it via `git mv` (so history follows) and stages it for the next
+ * commit. Returns the legacy dir it migrated from (for logging).
+ *
+ * No-op when:
+ *   - the repo has no legacy dir (fresh repo, or migration already done)
+ *   - the repo already has `.memarium/` (migration already done)
+ *   - the repo isn't a git repo (we still do a non-git rename so non-pushing
+ *     local-only mode works)
+ */
+export async function migrateLegacyDataDir(repoPath) {
+    const target = join(repoPath, REPO_DATA_DIR);
+    if (existsSync(target))
+        return { migrated: false, viaGit: false };
+    const from = LEGACY_REPO_DATA_DIRS.find((d) => existsSync(join(repoPath, d)));
+    if (!from)
+        return { migrated: false, viaGit: false };
+    const isGitRepo = existsSync(join(repoPath, ".git"));
+    if (isGitRepo) {
+        const git = simpleGit(repoPath);
+        // git mv preserves history. Use the directory form; git stages every file
+        // under it. The result is staged but not committed — runSync's commit
+        // bundles it with the rest of the sync's paths.
+        await git.raw(["mv", from, REPO_DATA_DIR]);
+        return { migrated: true, viaGit: true, from };
+    }
+    // Non-git fallback: plain rename. Used by local-only mode + tests that
+    // never init a git repo.
+    const { renameSync } = await import("node:fs");
+    renameSync(join(repoPath, from), target);
+    return { migrated: true, viaGit: false, from };
+}
+/** Returns the list of repo-rooted paths a successful data-dir migration produces, suitable for `git add`. */
+export function migratedDataDirPaths(repoPath) {
+    const dir = join(repoPath, REPO_DATA_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).map((f) => `${REPO_DATA_DIR}/${f}`);
+}

package/dist/src/project-identity.js

@@ -0,0 +1,139 @@
+import { simpleGit } from "simple-git";
+import { spawnSync } from "node:child_process";
+import { projectSlugFromPath } from "./slug.js";
+/**
+ * Canonical, path-INDEPENDENT project identity (P0a).
+ *
+ * Project memory must aggregate + recall correctly across devices, but the
+ * same repo can live at a different filesystem path per machine
+ * (`~/edge/memvc` vs `~/work/memvc` vs `~/projects/memvc`). The legacy slug =
+ * `projectSlugFromPath` (last two path segments) splits those into different
+ * projects, so raw_sessions folders / memory ids / book all diverge and never
+ * aggregate. Coding projects are git-maintained, and a repo's `origin` remote
+ * is identical on every clone — so the remote is the stable identity.
+ *
+ * `canonicalProjectId` collapses every remote URL form to one `host/path` id;
+ * `resolveProjectId` turns a cwd into a filesystem/index-safe slug, preferring
+ * the remote and falling back to the path slug when there's no git remote.
+ */
+/**
+ * Normalize any git remote URL to a canonical `host/path` id, collapsing SSH
+ * SCP (`git@host:org/repo.git`), `https://`, `ssh://`, `git://`, and
+ * credentialed forms to the same value. Host is lowercased (clones don't drift
+ * in host case); path case is preserved (org/repo can be case-significant).
+ * Returns null for unparseable / local (no-host) remotes → caller falls back.
+ *
+ *   git@github.com:june9593/memvc.git           -> github.com/june9593/memvc
+ *   https://github.com/june9593/memvc(.git)(/)  -> github.com/june9593/memvc
+ *   https://x-token:abc@github.com/o/r.git      -> github.com/o/r
+ *   ssh://git@gitlab.corp:22/grp/sub/proj.git   -> gitlab.corp/grp/sub/proj
+ */
+export function canonicalProjectId(remoteUrl) {
+    const s0 = (remoteUrl ?? "").trim();
+    if (!s0)
+        return null;
+    let host;
+    let path;
+    if (/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(s0)) {
+        // scheme://[user[:pass]@]host[:port]/path
+        let rest = s0.replace(/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//, "");
+        rest = rest.replace(/^[^@/]+@/, ""); // strip credentials
+        const slash = rest.indexOf("/");
+        if (slash < 0)
+            return null;
+        host = rest.slice(0, slash);
+        path = rest.slice(slash + 1);
+    }
+    else {
+        // SCP-like: [user@]host:path  (reject host:port/... which isn't SCP)
+        const m = s0.match(/^(?:[^@/]+@)?([^/:]+):(.+)$/);
+        if (!m)
+            return null; // local path / junk → fallback
+        if (/^\d+$/.test(m[2].split("/")[0]))
+            return null; // host:port/path, not SCP
+        host = m[1];
+        path = m[2];
+    }
+    host = host.replace(/:\d+$/, "").toLowerCase(); // strip port, lowercase host
+    path = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/i, "");
+    if (!host || !path)
+        return null;
+    return `${host}/${path}`;
+}
+/** Filesystem/index-safe slug from a remote URL, or null if not parseable.
+ *  `github.com/june9593/memvc` -> `github.com-june9593-memvc`. */
+export function projectSlugFromRemote(remoteUrl) {
+    const id = canonicalProjectId(remoteUrl);
+    if (!id)
+        return null;
+    return id.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+/**
+ * Resolve a cwd / repo-root to its stable project slug. Prefers the git
+ * `origin` remote (path-independent → aggregates across devices); falls back to
+ * the legacy `projectSlugFromPath` when there's no remote / not a git repo
+ * (a non-git project has no cross-device identity anyway). `getRemote` is
+ * injectable so the pure logic is testable without a real repo.
+ */
+export async function resolveProjectId(cwdOrRoot, getRemote = defaultGetRemote) {
+    let remote = null;
+    try {
+        remote = await getRemote(cwdOrRoot);
+    }
+    catch {
+        remote = null;
+    }
+    const slug = projectSlugFromRemote(remote);
+    if (slug)
+        return { slug, source: "remote", canonical: canonicalProjectId(remote) };
+    return { slug: projectSlugFromPath(cwdOrRoot), source: "path", canonical: null };
+}
+/** Read `remote.origin.url` at `dir` (or any ancestor git repo). Null if none. */
+async function defaultGetRemote(dir) {
+    try {
+        const v = (await simpleGit(dir).getConfig("remote.origin.url")).value;
+        return v && v.trim() ? v.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Synchronous remote read via `git config` — for sync call sites (the read
+ *  chokepoint) where an async ripple isn't worth it. A short-timeout
+ *  `spawnSync` shelling out to a CLI, the same pattern doctor.ts uses for its
+ *  `--version` probes. */
+function defaultGetRemoteSync(dir) {
+    const r = spawnSync("git", ["-C", dir, "config", "--get", "remote.origin.url"], {
+        encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 3000,
+    });
+    if (r.status !== 0)
+        return null;
+    const v = (r.stdout ?? "").trim();
+    return v ? v : null;
+}
+/** Sync sibling of `resolveProjectId` — same remote-first, path-fallback logic. */
+export function resolveProjectIdSync(cwdOrRoot, getRemote = defaultGetRemoteSync) {
+    let remote = null;
+    try {
+        remote = getRemote(cwdOrRoot);
+    }
+    catch {
+        remote = null;
+    }
+    const slug = projectSlugFromRemote(remote);
+    if (slug)
+        return { slug, source: "remote", canonical: canonicalProjectId(remote) };
+    return { slug: projectSlugFromPath(cwdOrRoot), source: "path", canonical: null };
+}
+const _slugCache = new Map();
+/** `resolveProjectIdSync(dir).slug`, memoized per dir for one process. A sync
+ *  run resolves the same project roots repeatedly (per session / per tool-use
+ *  path); without this each call re-spawns `git config`. */
+export function cachedProjectSlug(dir) {
+    const hit = _slugCache.get(dir);
+    if (hit !== undefined)
+        return hit;
+    const slug = resolveProjectIdSync(dir).slug;
+    _slugCache.set(dir, slug);
+    return slug;
+}

package/dist/src/project-resolve.js

@@ -0,0 +1,42 @@
+import { loadIndex } from "./index-store.js";
+import { projectSlugFromPath } from "./slug.js";
+import { resolveProjectIdSync } from "./project-identity.js";
+/**
+ * Reverse-lookup a project slug from an absolute cwd.
+ *
+ *   1. Resolve the stable project identity (git remote → slug; path slug when
+ *      no remote — `resolveProjectIdSync`) and check the index has a session
+ *      for it. The sync adapters compute the project the same way, so this is
+ *      authoritative.
+ *   2. Also try the legacy path slug, so a repo whose data was written before
+ *      the remote-identity switch (or a non-git project) still resolves.
+ *   3. Fall back to scanning index entries for one whose `projectRaw` === cwd.
+ *
+ * Returns null if none match — caller decides how to error.
+ */
+export function resolveProjectFromCwd(cwd, repoPath) {
+    const indexFile = loadIndex(repoPath);
+    return resolveProjectFromCwdWithIndex(cwd, indexFile.entries);
+}
+/** Variant for when the caller already has the index loaded (avoid double-read). */
+export function resolveProjectFromCwdWithIndex(cwd, entries) {
+    // Prefer the stable (remote-based) slug; fall back to the legacy path slug so
+    // un-migrated / non-git projects still resolve during the transition.
+    const candidates = [];
+    const remoteSlug = resolveProjectIdSync(cwd).slug;
+    candidates.push(remoteSlug);
+    const pathSlug = projectSlugFromPath(cwd);
+    if (pathSlug !== remoteSlug)
+        candidates.push(pathSlug);
+    for (const cand of candidates) {
+        for (const e of Object.values(entries)) {
+            if (e.project === cand)
+                return cand;
+        }
+    }
+    for (const e of Object.values(entries)) {
+        if (e.projectRaw === cwd)
+            return e.project;
+    }
+    return null;
+}