@north-light/api 0.3.580 → 0.3.588

package/dist/core/graph/repo-sync/mirror.js

@@ -0,0 +1,170 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { gitAsync } from '../../git.js';
+import { crtrHome } from '../../canvas/paths.js';
+const NETWORK_TIMEOUT_MS = 60_000;
+export const FIRST_FETCH_MARKER = 'first-fetch-done';
+const ENV = {
+    ...process.env,
+    GIT_TERMINAL_PROMPT: '0',
+    GIT_AUTHOR_NAME: 'crtr',
+    GIT_AUTHOR_EMAIL: 'crtr@localhost',
+    GIT_COMMITTER_NAME: 'crtr',
+    GIT_COMMITTER_EMAIL: 'crtr@localhost',
+};
+function git(m, args, input, opts = {}) {
+    return gitAsync(['--git-dir', m.dir, ...args], undefined, input, { env: opts.env ?? ENV, timeoutMs: opts.timeoutMs });
+}
+function fail(what, r) {
+    return new Error(`git ${what} failed (${r.timedOut ? 'timed out' : `exit ${r.status}`}): ${r.stderr.trim()}`);
+}
+function reason(r) {
+    return r.timedOut ? 'timed out' : (r.stderr.trim() || `exit ${r.status}`);
+}
+export async function openMirror(repoObjectId) {
+    const dir = join(crtrHome(), 'repo-sync', repoObjectId);
+    const m = { dir };
+    if (!existsSync(join(dir, 'HEAD'))) {
+        await mkdir(dir, { recursive: true });
+        const r = await gitAsync(['init', '--bare', '--quiet', dir], undefined, undefined, { env: ENV });
+        if (r.status !== 0)
+            throw fail('init', r);
+    }
+    return m;
+}
+export async function resolveRef(m, ref) {
+    const r = await git(m, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]);
+    if (r.status === 0)
+        return r.stdout.trim();
+    if (r.status === 1 && !r.executionFailed)
+        return null;
+    throw fail('rev-parse', r);
+}
+/** Reads blob bytes exactly: `cat-file --batch` sizes are byte counts. */
+function catFileBatch(m, shas) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', ['--git-dir', m.dir, 'cat-file', '--batch'], { env: { ...ENV, GIT_OPTIONAL_LOCKS: '0' } });
+        const chunks = [];
+        let stderr = '';
+        child.stdout.on('data', (d) => chunks.push(d));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('error', reject);
+        child.on('close', (status) => {
+            if (status !== 0)
+                return reject(new Error(`git cat-file failed (exit ${status}): ${stderr.trim()}`));
+            const out = Buffer.concat(chunks);
+            const blobs = [];
+            let pos = 0;
+            for (const sha of shas) {
+                const nl = out.indexOf(0x0a, pos);
+                const header = out.subarray(pos, nl).toString();
+                const [got, type, size] = header.split(' ');
+                if (got !== sha || type !== 'blob')
+                    return reject(new Error(`git cat-file: unexpected header "${header}" for ${sha}`));
+                const start = nl + 1;
+                const end = start + Number(size);
+                blobs.push(out.subarray(start, end));
+                pos = end + 1;
+            }
+            resolve(blobs);
+        });
+        child.stdin.end(shas.map((s) => `${s}\n`).join(''));
+    });
+}
+export async function readTree(m, ref) {
+    const sha = await resolveRef(m, ref);
+    if (sha === null)
+        return null;
+    const r = await git(m, ['ls-tree', '-r', '-z', sha]);
+    if (r.status !== 0)
+        throw fail('ls-tree', r);
+    const entries = r.stdout.split('\0').filter(Boolean).map((line) => {
+        const tab = line.indexOf('\t');
+        const [, type, blob] = line.slice(0, tab).split(' ');
+        if (type !== 'blob')
+            throw new Error(`repo-sync mirror: ${line.slice(tab + 1)} is a ${type}, not a file`);
+        return { path: line.slice(tab + 1), blob: blob };
+    });
+    const bodies = entries.length === 0 ? [] : await catFileBatch(m, entries.map((e) => e.blob));
+    return new Map(entries.map((e, i) => [e.path, bodies[i].toString('utf8')]));
+}
+export async function commitTree(m, files, parents, message) {
+    const scratch = await mkdtemp(join(m.dir, 'commit-'));
+    try {
+        const paths = [...files.keys()].sort();
+        const blobFiles = paths.map((_, i) => join(scratch, `blob-${i}`));
+        await Promise.all(paths.map((p, i) => writeFile(blobFiles[i], files.get(p), 'utf8')));
+        let shas = [];
+        if (paths.length > 0) {
+            const h = await git(m, ['hash-object', '-w', '--stdin-paths'], blobFiles.map((f) => `${f}\n`).join(''));
+            if (h.status !== 0)
+                throw fail('hash-object', h);
+            shas = h.stdout.trim().split('\n');
+        }
+        const indexEnv = { ...ENV, GIT_INDEX_FILE: join(scratch, 'index') };
+        const info = paths.map((p, i) => `100644 ${shas[i]}\t${p}\0`).join('');
+        const u = await git(m, ['update-index', '-z', '--index-info'], info, { env: indexEnv });
+        if (u.status !== 0)
+            throw fail('update-index', u);
+        const w = await git(m, ['write-tree'], undefined, { env: indexEnv });
+        if (w.status !== 0)
+            throw fail('write-tree', w);
+        const c = await git(m, ['commit-tree', w.stdout.trim(), ...parents.flatMap((p) => ['-p', p]), '-m', message]);
+        if (c.status !== 0)
+            throw fail('commit-tree', c);
+        return c.stdout.trim();
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+/** `expectOld` null requires the ref to not exist yet. */
+export async function setRef(m, ref, sha, expectOld) {
+    const r = await git(m, ['update-ref', ref, sha, expectOld ?? '0'.repeat(40)]);
+    if (r.status !== 0)
+        throw fail('update-ref', r);
+}
+export async function mergeBase(m, a, b) {
+    const r = await git(m, ['merge-base', a, b]);
+    if (r.status === 0)
+        return r.stdout.trim();
+    if (r.status === 1 && !r.executionFailed)
+        return null;
+    throw fail('merge-base', r);
+}
+export async function isAncestor(m, a, b) {
+    const r = await git(m, ['merge-base', '--is-ancestor', a, b]);
+    if (r.status === 0)
+        return true;
+    if (r.status === 1 && !r.executionFailed)
+        return false;
+    throw fail('merge-base --is-ancestor', r);
+}
+export async function remoteDocsTip(m, url) {
+    const r = await git(m, ['ls-remote', url, 'refs/crtr/docs'], undefined, { timeoutMs: NETWORK_TIMEOUT_MS });
+    if (r.status !== 0)
+        return { ok: false, reason: reason(r) };
+    const line = r.stdout.split('\n').find((l) => l.endsWith('\trefs/crtr/docs'));
+    return { ok: true, value: line ? line.split('\t')[0] : null };
+}
+export async function fetchDocs(m, url) {
+    const r = await git(m, ['fetch', '--no-tags', '--quiet', url, '+refs/crtr/docs:refs/crtr/remote-docs'], undefined, { timeoutMs: NETWORK_TIMEOUT_MS });
+    if (r.status !== 0)
+        return { ok: false, reason: reason(r) };
+    const sha = await resolveRef(m, 'refs/crtr/remote-docs');
+    if (sha === null)
+        return { ok: false, reason: 'fetch succeeded but refs/crtr/remote-docs is missing' };
+    await writeFile(join(m.dir, FIRST_FETCH_MARKER), `${new Date().toISOString()}\n`);
+    return { ok: true, value: sha };
+}
+/** Never forced; `--no-verify` so no user hook runs. A non-fast-forward answers `rejected`. */
+export async function pushDocs(m, url, sha) {
+    const r = await git(m, ['push', '--no-verify', '--porcelain', url, `${sha}:refs/crtr/docs`], undefined, { timeoutMs: NETWORK_TIMEOUT_MS });
+    if (r.status === 0)
+        return { ok: true, value: 'pushed' };
+    if (/\[rejected\]|non-fast-forward|fetch first/.test(r.stdout + r.stderr))
+        return { ok: false, reason: 'rejected' };
+    return { ok: false, reason: reason(r) };
+}

package/dist/core/graph/repo-sync/ref-format.d.ts

@@ -0,0 +1,80 @@
+import type { RuleOn } from '../types.js';
+export interface RefRule {
+    position: number;
+    on: RuleOn;
+    match: unknown;
+    match_frontmatter: unknown;
+    if: unknown;
+    deliver: 'name' | 'preview' | 'content';
+}
+export interface RefRevision {
+    rev_id: string;
+    number: number;
+    parents: string[];
+    body: string;
+    body_hash: string;
+    /** Object id of the author on the runtime that wrote it; null when unknown. */
+    author: string | null;
+    rationale: string | null;
+    created_at: string;
+    links: Array<{
+        written_as: string;
+        dst: string;
+    }>;
+}
+export interface RefDocument {
+    id: string;
+    name: string;
+    kind: string;
+    privacy: 'public';
+    preview: string;
+    summary: string | null;
+    why_it_exists: string | null;
+    unlisted: boolean;
+    lint_ignore: unknown;
+    extensions: unknown;
+    created_at: string;
+    deleted_at: string | null;
+    rules: RefRule[];
+    revisions: RefRevision[];
+}
+export declare const docPath: (id: string) => string;
+/** Every field merged three-way: all but id, created_at and revisions. */
+export declare const RECORD_FIELDS: readonly ["name", "kind", "privacy", "preview", "summary", "why_it_exists", "unlisted", "lint_ignore", "extensions", "deleted_at", "rules"];
+export declare function serializeDoc(doc: RefDocument): string;
+/** Parse one ref file. Refuses anything not public, a body whose hash disagrees, or an id that is not the file name.
+ *  Each body is checked against the hash it arrived with, then held as `canonical` makes it (NUL → U+FFFD, hash of that text), so every consumer of a
+ *  parsed file — prior export, import, merge — sees the one representation the database stores. */
+export declare function parseDoc(path: string, text: string): {
+    ok: true;
+    doc: RefDocument;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Two sides name one revision id with different content: a revision-id collision, never merged or overwritten. */
+export declare class RevisionConflict extends Error {
+}
+/**
+ * Merge one document. Revisions: union by rev_id (first copy kept verbatim; the same id with another body hash or parents throws `RevisionConflict`). Fields: three-way
+ * against base, remote wins when both changed — except that clearing `deleted_at` (a restoration) beats a tombstone. A side missing the file while base had it deleted
+ * it: the result is marked deleted (at `now`) and keeps every revision.
+ */
+export declare function mergeDoc(base: RefDocument | null, local: RefDocument | null, remote: RefDocument | null, now?: string): RefDocument | null;
+/**
+ * Merge three trees (path → file text). Per path mergeDoc; then two live documents with one name:
+ * the one already on the remote under that name keeps it, the other becomes `<name>-<id first 8>`.
+ * A file that fails to parse is refused; it stays in the tree verbatim (the local side's text, else the remote's).
+ */
+export declare function mergeTrees(base: Map<string, string>, local: Map<string, string>, remote: Map<string, string>, now?: string): {
+    tree: Map<string, string>;
+    renamed: Array<{
+        id: string;
+        from: string;
+        to: string;
+    }>;
+    refused: Array<{
+        path: string;
+        reason: string;
+    }>;
+};

package/dist/core/graph/repo-sync/ref-format.js

@@ -0,0 +1,215 @@
+// The `refs/crtr/docs` tree format: one JSON file per repo-owned document holding its record,
+// its delivery rules and every revision, plus crtr's own merge of two such trees. Pure: no git,
+// no database. A merge never drops a revision; record fields merge three-way, remote wins a conflict.
+import { canonical, hashOf as sha256 } from '../bodies.js';
+export const docPath = (id) => `docs/${id}.json`;
+/** Every field merged three-way: all but id, created_at and revisions. */
+export const RECORD_FIELDS = [
+    'name', 'kind', 'privacy', 'preview', 'summary', 'why_it_exists', 'unlisted',
+    'lint_ignore', 'extensions', 'deleted_at', 'rules',
+];
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const k of Object.keys(value).sort())
+            out[k] = sortKeys(value[k]);
+        return out;
+    }
+    return value;
+}
+const stable = (v) => JSON.stringify(sortKeys(v ?? null));
+function byRevision(a, b) {
+    return a.number - b.number || (a.rev_id < b.rev_id ? -1 : a.rev_id > b.rev_id ? 1 : 0);
+}
+export function serializeDoc(doc) {
+    const normalized = {
+        ...doc,
+        rules: [...doc.rules].sort((a, b) => a.position - b.position),
+        revisions: [...doc.revisions].map((r) => ({ ...r, parents: [...r.parents].sort() })).sort(byRevision),
+    };
+    return `${JSON.stringify(sortKeys(normalized), null, 2)}\n`;
+}
+const RULE_ONS = new Set(['boot', 'workspace-open', 'file-read', 'document-read', 'command', 'pre-command', 'slash-command']);
+const DELIVERS = new Set(['name', 'preview', 'content']);
+const isStr = (v) => typeof v === 'string';
+const isStrOrNull = (v) => v === null || typeof v === 'string';
+/** Parse one ref file. Refuses anything not public, a body whose hash disagrees, or an id that is not the file name.
+ *  Each body is checked against the hash it arrived with, then held as `canonical` makes it (NUL → U+FFFD, hash of that text), so every consumer of a
+ *  parsed file — prior export, import, merge — sees the one representation the database stores. */
+export function parseDoc(path, text) {
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch (err) {
+        return { ok: false, reason: `not JSON: ${err.message}` };
+    }
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return { ok: false, reason: 'not an object' };
+    const d = raw;
+    if (d.privacy !== 'public')
+        return { ok: false, reason: `privacy is ${String(d.privacy)}; a repo holds only public documents` };
+    if (!isStr(d.id) || docPath(d.id) !== path)
+        return { ok: false, reason: `id ${String(d.id)} does not match file ${path}` };
+    for (const k of ['name', 'kind', 'preview', 'created_at'])
+        if (!isStr(d[k]))
+            return { ok: false, reason: `${k} is not a string` };
+    for (const k of ['summary', 'why_it_exists', 'deleted_at'])
+        if (!isStrOrNull(d[k]))
+            return { ok: false, reason: `${k} is not a string or null` };
+    if (typeof d.unlisted !== 'boolean')
+        return { ok: false, reason: 'unlisted is not a boolean' };
+    if (!Array.isArray(d.rules))
+        return { ok: false, reason: 'rules is not an array' };
+    for (const r of d.rules) {
+        if (!r || typeof r.position !== 'number' || !RULE_ONS.has(r.on) || !DELIVERS.has(r.deliver)) {
+            return { ok: false, reason: 'malformed rule' };
+        }
+    }
+    if (!Array.isArray(d.revisions) || d.revisions.length === 0)
+        return { ok: false, reason: 'no revisions' };
+    const seen = new Set();
+    for (const r of d.revisions) {
+        if (!r || !isStr(r.rev_id) || typeof r.number !== 'number' || !isStr(r.body) || !isStr(r.body_hash)
+            || !isStr(r.created_at) || !isStrOrNull(r.author) || !isStrOrNull(r.rationale)
+            || !Array.isArray(r.parents) || !r.parents.every(isStr) || !Array.isArray(r.links)) {
+            return { ok: false, reason: 'malformed revision' };
+        }
+        if (seen.has(r.rev_id))
+            return { ok: false, reason: `revision ${r.rev_id} appears twice` };
+        seen.add(r.rev_id);
+        if (sha256(r.body) !== r.body_hash)
+            return { ok: false, reason: `revision ${r.rev_id} body does not match body_hash` };
+    }
+    const revisions = d.revisions.map((r) => {
+        const { text, hash } = canonical(r.body, r.body_hash);
+        return text === r.body ? r : { ...r, body: text, body_hash: hash };
+    });
+    return { ok: true, doc: { ...d, revisions } };
+}
+/** Two sides name one revision id with different content: a revision-id collision, never merged or overwritten. */
+export class RevisionConflict extends Error {
+}
+const parentsKey = (r) => [...r.parents].sort().join(',');
+function unionRevisions(...sides) {
+    const byId = new Map();
+    for (const side of sides)
+        for (const r of side?.revisions ?? []) {
+            const held = byId.get(r.rev_id);
+            if (!held)
+                byId.set(r.rev_id, r);
+            else if (held.body_hash !== r.body_hash || parentsKey(held) !== parentsKey(r)) {
+                throw new RevisionConflict(`revision ${r.rev_id} is named with different content (body hash or parents) on two sides`);
+            }
+        }
+    return [...byId.values()].sort(byRevision);
+}
+/**
+ * Merge one document. Revisions: union by rev_id (first copy kept verbatim; the same id with another body hash or parents throws `RevisionConflict`). Fields: three-way
+ * against base, remote wins when both changed — except that clearing `deleted_at` (a restoration) beats a tombstone. A side missing the file while base had it deleted
+ * it: the result is marked deleted (at `now`) and keeps every revision.
+ */
+export function mergeDoc(base, local, remote, now = new Date().toISOString()) {
+    if (!local && !remote)
+        return null;
+    if (!local || !remote) {
+        const present = (local ?? remote);
+        if (!base)
+            return present;
+        return { ...present, deleted_at: present.deleted_at ?? now, revisions: unionRevisions(remote, local, base) };
+    }
+    const merged = { ...remote, revisions: unionRevisions(remote, local, base) };
+    for (const field of RECORD_FIELDS) {
+        const l = stable(local[field]);
+        const r = stable(remote[field]);
+        if (l === r)
+            continue;
+        const b = base ? stable(base[field]) : undefined;
+        // A restoration (tombstone cleared) outranks a tombstone on the other side, whether that side
+        // left it as the base had it or re-stamped it with a new `deleted_at`: a deletion is
+        // re-stamped by any runtime that merely re-exports it, a restoration is deliberate.
+        if (field === 'deleted_at' && base?.deleted_at != null && (local.deleted_at === null) !== (remote.deleted_at === null)) {
+            merged.deleted_at = null;
+            // Deletion dropped the tombstone side's delivery rules; the restoring side's are the document's.
+            merged.rules = (local.deleted_at === null ? local : remote).rules;
+            continue;
+        }
+        if (b === r)
+            merged[field] = local[field];
+    }
+    return merged;
+}
+/**
+ * Merge three trees (path → file text). Per path mergeDoc; then two live documents with one name:
+ * the one already on the remote under that name keeps it, the other becomes `<name>-<id first 8>`.
+ * A file that fails to parse is refused; it stays in the tree verbatim (the local side's text, else the remote's).
+ */
+export function mergeTrees(base, local, remote, now = new Date().toISOString()) {
+    const tree = new Map();
+    const refused = [];
+    const merged = new Map();
+    const paths = [...new Set([...base.keys(), ...local.keys(), ...remote.keys()])].sort();
+    for (const path of paths) {
+        const parsed = [];
+        let bad = null;
+        for (const side of [base, local, remote]) {
+            const text = side.get(path);
+            if (text === undefined) {
+                parsed.push(null);
+                continue;
+            }
+            const p = parseDoc(path, text);
+            if (!p.ok) {
+                bad ??= p.reason;
+                parsed.push(null);
+            }
+            else
+                parsed.push(p.doc);
+        }
+        if (bad !== null) {
+            refused.push({ path, reason: bad });
+            // Keep a file we cannot read rather than drop it from the merged tree (a drop is a deletion).
+            const kept = local.get(path) ?? remote.get(path);
+            if (kept !== undefined)
+                tree.set(path, kept);
+            continue;
+        }
+        // An identity collision cannot be represented by one file. Abort the merge rather than publish either side alone
+        // with both commits as parents: that would acknowledge and drop the other side's independent revisions.
+        const doc = mergeDoc(parsed[0], parsed[1], parsed[2], now);
+        if (doc)
+            merged.set(path, doc);
+    }
+    const remoteNameOf = (path) => {
+        const text = remote.get(path);
+        if (text === undefined)
+            return null;
+        const p = parseDoc(path, text);
+        return p.ok && p.doc.deleted_at === null ? p.doc.name : null;
+    };
+    const byName = new Map();
+    for (const [path, doc] of merged) {
+        if (doc.deleted_at !== null)
+            continue;
+        byName.set(doc.name, [...(byName.get(doc.name) ?? []), path]);
+    }
+    const renamed = [];
+    for (const [name, group] of byName) {
+        if (group.length < 2)
+            continue;
+        const keeper = group.find((p) => remoteNameOf(p) === name) ?? [...group].sort((a, b) => merged.get(a).id.localeCompare(merged.get(b).id))[0];
+        for (const path of group) {
+            if (path === keeper)
+                continue;
+            const doc = merged.get(path);
+            const to = `${name}-${doc.id.slice(0, 8)}`;
+            merged.set(path, { ...doc, name: to });
+            renamed.push({ id: doc.id, from: name, to });
+        }
+    }
+    for (const [path, doc] of merged)
+        tree.set(path, serializeDoc(doc));
+    return { tree: new Map([...tree].sort(([a], [b]) => a.localeCompare(b))), renamed, refused };
+}

package/dist/core/graph/repo-sync/repos.d.ts

@@ -0,0 +1,21 @@
+import type { Checkout, ObjectRow } from '../types.js';
+import { handleHint } from './identity.js';
+import type { CanvasDb } from '../../canvas/db.js';
+export { handleHint };
+export interface RepoIdentity {
+    scheme: 'git' | 'local-path';
+    externalId: string;
+    handleHint: string;
+}
+/** The repo object for an identity, created on first sight. A handle already
+ *  held by another repo gets `-2`, `-3`, … appended. */
+export declare function ensureRepo(db: CanvasDb, id: RepoIdentity, handle?: string): Promise<ObjectRow>;
+/** Repos enclosing `cwd`, nearest first: every enclosing git checkout (created
+ *  on first sight) and every existing local-path repo whose path is `cwd` or
+ *  an ancestor of it. A non-git folder is never created here. */
+export declare function reposForCwd(db: CanvasDb, cwd: string): Promise<ObjectRow[]>;
+/** Run the git lookups for `cwd`'s checkouts now, so a later `checkoutsForCwd` inside a canvas write hits the identity
+ *  cache instead of spawning git while every other db caller waits on the write lock. */
+export declare function warmCheckoutIdentities(cwd: string): Promise<void>;
+/** `reposForCwd` with the directory each repo is checked out at. */
+export declare function checkoutsForCwd(db: CanvasDb, cwd: string): Promise<Checkout[]>;

package/dist/core/graph/repo-sync/repos.js

@@ -0,0 +1,57 @@
+/** Repo objects on the canvas: one per repo identity, handle chosen once. */
+import { resolve, sep } from 'node:path';
+import { CrtrError } from '../../errors.js';
+import { realpathOrSelf } from '../../fs-utils.js';
+import { ExitCode } from '../../../types.js';
+import { ensureOwner } from '../objects.js';
+import { checkoutChain, handleHint } from './identity.js';
+export { handleHint };
+async function existingRepo(db, scheme, externalId) {
+    const row = await db.prepare(`SELECT o.* FROM identities i JOIN objects o ON o.id = i.object
+    WHERE o.type = 'repo' AND i.scheme = ? AND i.external_id = ?`).get(scheme, externalId);
+    return row ?? null;
+}
+/** The repo object for an identity, created on first sight. A handle already
+ *  held by another repo gets `-2`, `-3`, … appended. */
+export async function ensureRepo(db, id, handle) {
+    const found = await existingRepo(db, id.scheme, id.externalId);
+    if (found)
+        return found;
+    const wanted = handle ?? id.handleHint;
+    const taken = db.prepare(`SELECT 1 FROM objects WHERE name = ? AND type = 'repo' AND home_machine IS NULL`);
+    let free = wanted;
+    for (let n = 2; await taken.get(free); n++)
+        free = `${wanted}-${n}`;
+    return await ensureOwner(db, 'repo', id.scheme, id.externalId, free);
+}
+/** Repos enclosing `cwd`, nearest first: every enclosing git checkout (created
+ *  on first sight) and every existing local-path repo whose path is `cwd` or
+ *  an ancestor of it. A non-git folder is never created here. */
+export async function reposForCwd(db, cwd) {
+    return (await checkoutsForCwd(db, cwd)).map((c) => c.repo);
+}
+/** Run the git lookups for `cwd`'s checkouts now, so a later `checkoutsForCwd` inside a canvas write hits the identity
+ *  cache instead of spawning git while every other db caller waits on the write lock. */
+export async function warmCheckoutIdentities(cwd) {
+    await checkoutChain(realpathOrSelf(resolve(cwd)));
+}
+/** `reposForCwd` with the directory each repo is checked out at. */
+export async function checkoutsForCwd(db, cwd) {
+    const dir = realpathOrSelf(resolve(cwd));
+    const found = [];
+    for (const id of await checkoutChain(dir)) {
+        if (!id.ok) {
+            throw new CrtrError('git-lookup-failed', `cannot identify the repo at ${id.dir}: ${id.reason}`, ExitCode.GENERAL, { dir: id.dir });
+        }
+        found.push({ root: id.root, repo: await ensureRepo(db, id) });
+    }
+    const paths = await db.prepare(`SELECT o.*, i.external_id AS path FROM identities i JOIN objects o ON o.id = i.object
+    WHERE o.type = 'repo' AND i.scheme = 'local-path'`).all();
+    for (const { path, ...repo } of paths) {
+        if (dir === path || dir.startsWith(path.endsWith(sep) ? path : path + sep))
+            found.push({ root: path, repo });
+    }
+    found.sort((a, b) => b.root.length - a.root.length);
+    const seen = new Set();
+    return found.filter(({ repo }) => !seen.has(repo.id) && (seen.add(repo.id), true));
+}

package/dist/core/graph/repo-sync/sync.d.ts

@@ -0,0 +1,40 @@
+import type { DetachedWorkLifecycle } from '../../../daemon/reconcilers/broker-supervision.js';
+import type { ObjectRow } from '../types.js';
+import { type ImportResult } from './exchange.js';
+import { type CanvasDb } from '../../canvas/db.js';
+export declare const FIRST_FETCH_WAIT_MS = 20000;
+export type SyncStep = 'export' | 'fetch' | 'merge' | 'import' | 'push';
+export type SyncOutcome = {
+    ok: true;
+    pushed: boolean;
+    imported: ImportResult;
+} | {
+    ok: false;
+    step: SyncStep;
+    reason: string;
+};
+/** Called once by crtrd. Until then triggers are refused loudly. */
+export declare function startRepoSync(lifecycle: DetachedWorkLifecycle, db: () => Promise<CanvasDb>): Promise<void>;
+/**
+ * A node starts working in `cwd`, enclosed by `repos`. For each syncing repo: when no fetch has
+ * ever succeeded on this machine and none was attempted in this daemon's lifetime, wait for its
+ * sync, at most FIRST_FETCH_WAIT_MS; otherwise schedule it and return at once.
+ */
+export declare function noteNodeWorking(repos: ObjectRow[], cwd: string): Promise<void>;
+/**
+ * A node's boot delivery is about to render: it starts working in the repos enclosing its cwd.
+ * Sync them first (the first on this machine waits for the first fetch, bounded), so what the
+ * repo's collaborators wrote is on the canvas before its bearings. Never throws: a failed sync
+ * never fails a boot, and every failure is an event.
+ */
+export declare function noteNodeBooting(nodeId: string): Promise<void>;
+/** A repo-owned document changed (write, edit, move at either end, delete). `dirs`, the caller's
+ *  cwd and the checkouts it reaches, record the fetch URL of any that is a checkout of the repo; the
+ *  sync itself never depends on where the writer runs. */
+export declare function noteRepoDocumentsChanged(repo: ObjectRow, dirs?: readonly string[]): Promise<void>;
+/**
+ * One sync: export canvas.db to a local commit, fetch the remote ref, fast-forward or merge,
+ * import the merged tree into canvas.db, push (never forced). A rejected push fetches again,
+ * at most PUSH_ATTEMPTS times.
+ */
+export declare function syncRepo(repo: ObjectRow): Promise<SyncOutcome>;