@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,422 @@
+/** The canvas side of repo sync: export a repo space's public documents to `refs/crtr/docs`
+ *  tree files, and import a changed tree back into canvas.db. Export only reads; import only
+ *  adds revisions (never drops one) and publishes `created`, `edited` and `deleted` with a
+ *  null actor, since the act happened on another runtime. */
+import { getMany as getBodies, hashOf, put as putBody } from '../bodies.js';
+import { setLinks, setUnresolved } from '../edges.js';
+import { collectUnlinked, deleteDocument, documentRecord, heads, importDocument, insertImportedRevisions, moveDocument, restoreDocument, setDocumentRecord, } from '../documents.js';
+import { CrtrError } from '../../errors.js';
+import { publish } from '../events.js';
+import { getById, setObjectKind } from '../objects.js';
+import { rulesOf } from '../rules.js';
+import { docPath, mergeDoc, parseDoc, RevisionConflict, serializeDoc } from './ref-format.js';
+import { withCanvasWrite } from '../../canvas/db.js';
+import { mapAsync } from '../../async-array.js';
+function assertRepoRefSpace(repo) {
+    if (repo.owner !== null || repo.type !== 'repo') {
+        throw new Error(`${repo.type} ${repo.id} is not a space that syncs through a repo ref`);
+    }
+}
+function parseMap(tree) {
+    const out = new Map();
+    for (const [path, text] of tree ?? []) {
+        const p = parseDoc(path, text);
+        if (p.ok)
+            out.set(p.doc.id, p.doc);
+    }
+    return out;
+}
+/**
+ * The tree (path → file text) of every public document the repo space owns, deleted ones
+ * included. A revision already in `previous` is copied verbatim, so a remote author and the
+ * links it was written with survive; a revision made here carries its author's object id, and
+ * a head carries the document's current `links-to` edges. `carry` names paths of `previous` that
+ * are copied through untouched (files whose import was refused and is still pending).
+ */
+export async function exportRepo(db, repo, previous, imported = null) {
+    assertRepoRefSpace(repo);
+    const prior = parseMap(previous);
+    const docs = await db.prepare(`SELECT * FROM objects WHERE type = 'document' AND owner = ? AND privacy = 'public' ORDER BY seq`)
+        .all(repo.id);
+    const revisionsOf = db.prepare('SELECT rev_id, number, body_hash, author, rationale, created_at FROM revisions WHERE document = ? ORDER BY number, rev_id');
+    const parentsOf = db.prepare('SELECT p.rev_id FROM revision_parents rp JOIN revisions p ON p.rev_id = rp.parent WHERE rp.child = ?');
+    const linksOf = db.prepare(`SELECT e.written_as, o.id FROM edges e JOIN objects o ON o.id = e.dst
+    WHERE e.type = 'links-to' AND e.src = ? ORDER BY e.written_as, o.id`);
+    const tree = new Map();
+    for (const doc of docs) {
+        const record = await documentRecord(db, doc);
+        const known = new Map((prior.get(doc.id)?.revisions ?? []).map((r) => [r.rev_id, r]));
+        const headIds = new Set((await heads(db, doc)).map((h) => h.rev_id));
+        const links = (await linksOf.all(doc.id))
+            .map((l) => ({ written_as: l.written_as ?? '', dst: l.id }));
+        const raws = await revisionsOf.all(doc.id);
+        // A known revision whose body/hash disagrees with the database pair is refreshed from the database; its remote metadata and links stay.
+        const verbatim = (raw) => {
+            const k = known.get(raw.rev_id);
+            return k !== undefined && k.body_hash === raw.body_hash ? k : undefined;
+        };
+        const texts = await getBodies(db, raws.filter((raw) => verbatim(raw) === undefined).map((raw) => raw.body_hash));
+        const revisions = (await mapAsync(raws, async (raw) => {
+            const kept = verbatim(raw);
+            if (kept !== undefined)
+                return kept;
+            const body = texts.get(raw.body_hash);
+            if (hashOf(body) !== raw.body_hash)
+                throw new Error(`body ${raw.body_hash} of revision ${raw.rev_id} does not hash to its key; refusing to export it`);
+            const refresh = known.get(raw.rev_id);
+            if (refresh !== undefined)
+                return { ...refresh, body, body_hash: raw.body_hash };
+            return {
+                rev_id: raw.rev_id, number: raw.number,
+                parents: (await parentsOf.all(raw.rev_id)).map((p) => p.rev_id),
+                body, body_hash: raw.body_hash,
+                author: raw.author,
+                rationale: raw.rationale, created_at: raw.created_at,
+                links: headIds.has(raw.rev_id) ? links : [],
+            };
+        }));
+        if (revisions.length === 0)
+            continue;
+        const rules = (await rulesOf(db, doc)).map((r) => ({
+            position: r.position, on: r.on, match: r.match ?? null, match_frontmatter: r.matchFrontmatter ?? null,
+            if: r.if ?? null, deliver: r.deliver,
+        }));
+        const ref = {
+            id: doc.id, name: doc.name, kind: doc.kind ?? 'document', privacy: 'public', preview: doc.preview,
+            summary: record.summary, why_it_exists: record.why_it_exists, unlisted: record.unlisted,
+            lint_ignore: record.lint_ignore, extensions: record.extensions, created_at: doc.created_at,
+            deleted_at: doc.deleted_at, rules, revisions,
+        };
+        tree.set(docPath(doc.id), serializeDoc(ref));
+    }
+    // A file in `previous` that differs from `imported` has not landed in canvas.db (its import
+    // was refused). canvas.db cannot describe it, so an export that omitted it would publish a
+    // deletion. Carry it forward verbatim; when canvas.db holds the document too, merge the two
+    // (revisions unioned, the ref's fields winning) so neither side's content is dropped.
+    for (const path of pendingPaths(previous, imported)) {
+        const text = previous.get(path);
+        const mine = tree.get(path);
+        if (mine === undefined) {
+            tree.set(path, text);
+            continue;
+        }
+        const theirs = parseDoc(path, text);
+        const ours = parseDoc(path, mine);
+        // A refused file that cannot be read stays as the remote wrote it: canvas.db's own copy must
+        // not replace it, and what it holds is not ours to rewrite.
+        if (!theirs.ok) {
+            tree.set(path, text);
+            continue;
+        }
+        if (!ours.ok)
+            continue;
+        const base = imported?.has(path) ? parseDoc(path, imported.get(path)) : null;
+        let merged;
+        try {
+            merged = mergeDoc(base?.ok ? base.doc : null, ours.doc, theirs.doc);
+        }
+        catch (error) {
+            // The two name one revision id with different content: carried as the remote wrote it, so the import refuses it and it is never overwritten.
+            if (!(error instanceof RevisionConflict))
+                throw error;
+            tree.set(path, text);
+            continue;
+        }
+        if (merged)
+            tree.set(path, serializeDoc(merged));
+    }
+    return tree;
+}
+/** Paths of `tree` whose text differs from the baseline last imported: files that arrived but
+ *  have not landed in canvas.db. */
+export function pendingPaths(tree, imported) {
+    return [...(tree ?? [])].filter(([path, text]) => imported?.get(path) !== text).map(([path]) => path);
+}
+function toRuleSpecs(rules) {
+    return [...rules].sort((a, b) => a.position - b.position).map((r) => ({
+        on: r.on, deliver: r.deliver,
+        ...(r.match !== null && r.match !== undefined ? { match: r.match } : {}),
+        ...(r.match_frontmatter !== null && r.match_frontmatter !== undefined ? { matchFrontmatter: r.match_frontmatter } : {}),
+        ...(r.if !== null && r.if !== undefined ? { if: r.if } : {}),
+    }));
+}
+const same = (a, b) => JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
+/** Record fields of `after` that differ from `before` (all of them when there is no before). */
+function changedFields(before, after) {
+    const f = {};
+    const differs = (k) => !before || !same(before[k], after[k]);
+    if (differs('preview'))
+        f.preview = after.preview;
+    if (differs('summary'))
+        f.summary = after.summary;
+    if (differs('why_it_exists'))
+        f.whyItExists = after.why_it_exists;
+    if (differs('unlisted'))
+        f.unlisted = after.unlisted;
+    if (differs('lint_ignore'))
+        f.lintIgnore = after.lint_ignore;
+    if (differs('extensions'))
+        f.extensions = after.extensions;
+    if (differs('rules'))
+        f.rules = toRuleSpecs(after.rules);
+    return f;
+}
+/**
+ * Apply the difference between two trees (the one last imported and the new one) to the
+ * repo's documents, in one transaction. Per changed file: a file that does not parse, is not
+ * public, or names an id held by an object outside this repo is refused and reported; a new
+ * document is created with its id; arriving revisions are added (author NULL); changed record
+ * fields and a rename are applied; a tombstone or a removed file deletes. Each document
+ * publishes once: `created`, `edited` (with `heads` and `needs_merge`) or `deleted`. A
+ * document that fails is rolled back alone and reported in `refused`.
+ */
+export async function importTree(db, repo, before, after, reposFn) {
+    assertRepoRefSpace(repo);
+    const result = { created: 0, revisions: 0, deleted: 0, needsMerge: [], refused: [] };
+    const work = [];
+    for (const [path, text] of after) {
+        if (before.get(path) === text)
+            continue;
+        const parsed = parseDoc(path, text);
+        if (!parsed.ok) {
+            result.refused.push({ path, reason: parsed.reason });
+            continue;
+        }
+        const prior = before.has(path) ? parseDoc(path, before.get(path)) : null;
+        work.push({ path, prior: prior?.ok ? prior.doc : null, doc: parsed.doc });
+    }
+    for (const [path, text] of before) {
+        if (after.has(path))
+            continue;
+        const prior = parseDoc(path, text);
+        if (prior.ok)
+            work.push({ path, prior: prior.doc, doc: null, priorId: prior.doc.id });
+    }
+    // Paths come sorted, so an incoming document can be met before the existing document that
+    // holds its name has been renamed or deleted by another item of the same batch. A name
+    // conflict is therefore not a refusal yet: defer the item and retry it once the rest of the
+    // pass has freed names, until a pass makes no progress. What is still in conflict then holds
+    // a name that nothing in this batch frees (a live document outside the tree, or a cycle); it
+    // is refused, never clobbered, and stays pending for the next sync.
+    const arrived = [];
+    await withCanvasWrite(async () => {
+        // The text goes in with the revisions that name it, in this transaction.
+        for (const w of work)
+            for (const r of w.doc?.revisions ?? [])
+                await putBody(db, r.body, r.body_hash);
+        let pending = work;
+        for (;;) {
+            const deferred = [];
+            for (const w of pending) {
+                const attempt = { created: 0, revisions: 0, deleted: 0, needsMerge: [], refused: [] };
+                try {
+                    const born = [];
+                    await withCanvasWrite(async () => await importOne(db, repo, w.prior, w.doc, w.priorId ?? w.doc.id, attempt, reposFn, born), { savepoint: true });
+                    arrived.push(...born);
+                    result.created += attempt.created;
+                    result.revisions += attempt.revisions;
+                    result.deleted += attempt.deleted;
+                    result.needsMerge.push(...attempt.needsMerge);
+                }
+                catch (error) {
+                    if (isNameConflict(error))
+                        deferred.push({ w, error: error });
+                    else
+                        result.refused.push({ path: w.path, reason: error.message });
+                }
+            }
+            if (deferred.length === 0)
+                break;
+            if (deferred.length === pending.length) {
+                for (const d of deferred)
+                    result.refused.push({ path: d.w.path, reason: d.error.message });
+                break;
+            }
+            pending = deferred.map((d) => d.w);
+        }
+        // Links point at ids, and a target can arrive after the document that links to it (paths come
+        // sorted, or the target landed in a later sync). Now that the batch's documents exist, add the
+        // edges that could not be resolved the first time.
+        await completeLinks(db, after, new Set(arrived), new Set(work.map((w) => w.path)));
+    }, { savepoint: true });
+    return result;
+}
+/**
+ * Add the head links that name an object that has just arrived. Candidates are the documents of
+ * `after` that were part of this batch or that link to something that arrived in it. Only adds:
+ * an edge already there is kept, so a link the document no longer has (it would be a new
+ * revision, exported before any import) is never resurrected by this and none is dropped.
+ */
+async function completeLinks(db, after, arrived, touched) {
+    if (arrived.size === 0)
+        return;
+    const insert = db.prepare(`INSERT INTO edges (type, src, dst, written_as, created_at) VALUES ('links-to', ?, ?, ?, ?) ON CONFLICT DO NOTHING`);
+    const now = new Date().toISOString();
+    // The destination ids a file names are read off its text in one pass (`"dst": "<id>"`, the
+    // serializer's only spelling of a link target) and probed against the arrived set by lookup, so
+    // an untouched file is never parsed unless it links to something that arrived and the cost is
+    // linear in the repo, not in files times arrivals.
+    for (const [path, text] of after) {
+        if (!touched.has(path) && !namesArrived(text, arrived))
+            continue;
+        const parsed = parseDoc(path, text);
+        if (!parsed.ok || parsed.doc.deleted_at)
+            continue;
+        const src = await getById(db, parsed.doc.id);
+        if (!src || src.type !== 'document' || src.deleted_at)
+            continue;
+        const top = (await heads(db, src))[0];
+        const links = parsed.doc.revisions.find((r) => r.rev_id === top?.rev_id)?.links ?? [];
+        for (const l of links) {
+            const dst = await getById(db, l.dst);
+            if (dst && dst.id !== src.id)
+                await insert.run(src.id, dst.id, l.written_as, now);
+        }
+    }
+}
+const DST = /"dst":\s*"((?:[^"\\]|\\.)*)"/g;
+/** Whether any link target in a serialized ref file is one of `arrived`. */
+export function namesArrived(text, arrived) {
+    for (const m of text.matchAll(DST))
+        if (arrived.has(decodeJsonString(m[1])))
+            return true;
+    return false;
+}
+/** The value of the JSON string literal whose contents are `escaped` (the captured text between the quotes). */
+function decodeJsonString(escaped) {
+    if (!escaped.includes('\\'))
+        return escaped;
+    try {
+        return JSON.parse(`"${escaped}"`);
+    }
+    catch {
+        return escaped;
+    }
+}
+function isNameConflict(error) {
+    return error instanceof CrtrError && error.code === 'conflict' && error.details?.['holder'] !== undefined;
+}
+async function importOne(db, repo, prior, doc, id, result, reposFn, arrived) {
+    const existing = await getById(db, id);
+    if (existing && (existing.type !== 'document' || existing.owner !== repo.id)) {
+        throw new Error(`id ${id} is held by ${existing.type} ${existing.name} outside ${repo.name}`);
+    }
+    if (!doc) {
+        // The file left the tree (moved out of the repo on the other runtime): a deletion here.
+        if (existing && !existing.deleted_at) {
+            await deleteDocument(db, null, existing, reposFn);
+            result.deleted++;
+        }
+        return;
+    }
+    const countOf = db.prepare('SELECT count(*) AS n FROM revisions WHERE document = ?');
+    let object;
+    let isNew = false;
+    let restored = false;
+    let fromRevision = 0;
+    let added = 0;
+    if (!existing) {
+        const roots = doc.revisions.filter((r) => r.parents.length === 0).sort((a, b) => a.number - b.number || a.rev_id.localeCompare(b.rev_id));
+        const root = roots[0];
+        if (!root)
+            throw new Error(`${doc.name}: no root revision`);
+        object = await importDocument(db, {
+            id: doc.id, owner: repo, name: doc.name, kind: doc.kind, preview: doc.preview, privacy: 'public', ...changedFields(null, doc),
+            revisions: [{ rev_id: root.rev_id, body_hash: root.body_hash, author: null, rationale: root.rationale, created_at: root.created_at }],
+        }, reposFn);
+        // importDocument dates the document by its first revision; the ref carries the document's own
+        // time, and exporting a different one would push a correction for every document where they differ.
+        if (object.created_at !== doc.created_at) {
+            await db.prepare('UPDATE objects SET created_at = ? WHERE id = ?').run(doc.created_at, object.id);
+            object = (await getById(db, object.id));
+        }
+        isNew = true;
+        arrived?.push(object.id);
+        added = 1;
+    }
+    else {
+        object = existing;
+        fromRevision = (await documentRecord(db, object)).revision;
+        // The ref's document time wins, as for a new document: keeping ours would export it back over a correction.
+        if (object.created_at !== doc.created_at) {
+            await db.prepare('UPDATE objects SET created_at = ? WHERE id = ?').run(doc.created_at, object.id);
+            object = (await getById(db, object.id));
+        }
+        const kind = doc.kind;
+        if (prior ? prior.kind !== kind : object.kind !== kind)
+            await setObjectKind(db, object, kind);
+        // A live file arrives for a document this runtime holds deleted, and the last imported ref
+        // either had it tombstoned or did not have it at all (an omission deleted it here): a
+        // restoration. Bring back its name, record fields and delivery rules from the ref (deletion
+        // dropped the rules); watches ended by the deletion are not recoverable. A prior live file
+        // means this runtime deleted it itself, and that deletion stands.
+        restored = !!object.deleted_at && doc.deleted_at === null && (prior === null || prior.deleted_at != null);
+        let fields = changedFields(restored ? null : prior, doc);
+        // A tombstone carries no delivery rules.
+        if (doc.deleted_at && object.deleted_at) {
+            const { rules: _rules, ...rest } = fields;
+            fields = rest;
+        }
+        if (restored) {
+            object = await restoreDocument(db, object, doc.name, reposFn);
+            arrived?.push(object.id);
+        }
+        if (Object.keys(fields).length > 0)
+            object = await setDocumentRecord(db, null, object, fields);
+        if (doc.name !== object.name && !object.deleted_at)
+            object = await moveDocument(db, null, object, { name: doc.name }, reposFn);
+    }
+    const beforeCount = (await countOf.get(object.id)).n;
+    const { headCount } = await insertImportedRevisions(db, object, doc.revisions.map((r) => ({
+        rev_id: r.rev_id, parents: r.parents, body_hash: r.body_hash, rationale: r.rationale, created_at: r.created_at,
+    })));
+    added += (await countOf.get(object.id)).n - beforeCount;
+    result.revisions += added;
+    const current = await heads(db, object);
+    const top = current[0];
+    const byId = new Map(doc.revisions.map((r) => [r.rev_id, r]));
+    if (added > 0 || restored) {
+        // Links of the highest head, to the objects this runtime has; others stay text.
+        const links = (await mapAsync((byId.get(top.rev_id)?.links ?? []), async (l) => ({ written_as: l.written_as, dst: await getById(db, l.dst) })))
+            .filter((l) => l.dst !== null);
+        await collectUnlinked(db, await setLinks(db, object, links), reposFn);
+        // The unresolved names remembered for an earlier head no longer describe this one.
+        await setUnresolved(db, object, []);
+    }
+    if (headCount > 1)
+        result.needsMerge.push(object.id);
+    if (doc.deleted_at && !object.deleted_at) {
+        // Keep the ref's own tombstone time: a fresh one would differ and be re-exported as a change.
+        await deleteDocument(db, null, object, reposFn, doc.deleted_at);
+        result.deleted++;
+        return;
+    }
+    if (doc.deleted_at && object.deleted_at && object.deleted_at !== doc.deleted_at) {
+        // Already deleted here, at another time: adopt the ref's. Keeping our own would export a
+        // different tombstone than the one just imported, and two runtimes would trade them forever.
+        // Not a new deletion: nothing is published and no rule is dropped again.
+        await db.prepare('UPDATE objects SET deleted_at = ? WHERE id = ?').run(doc.deleted_at, object.id);
+    }
+    if (isNew) {
+        result.created++;
+        await publish(db, { event: 'created', object, actor: null, attrs: { revision: top.number }, pointer: top.rev_id }, reposFn);
+        return;
+    }
+    if (restored) {
+        result.created++;
+        await publish(db, { event: 'created', object, actor: null, attrs: { revision: top.number }, pointer: top.rev_id }, reposFn);
+        return;
+    }
+    if (added === 0)
+        return;
+    const arriving = doc.revisions.filter((r) => !prior?.revisions.some((p) => p.rev_id === r.rev_id))
+        .sort((a, b) => b.number - a.number || b.created_at.localeCompare(a.created_at));
+    const newest = arriving[0] ?? byId.get(top.rev_id);
+    await publish(db, {
+        event: 'edited', object, actor: null, pointer: top.rev_id,
+        attrs: {
+            revision: top.number, from_revision: fromRevision, rationale: newest?.rationale ?? null,
+            author: newest?.author ?? null, heads: headCount, needs_merge: headCount > 1,
+        },
+    }, reposFn);
+}

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

@@ -0,0 +1,32 @@
+export type CheckoutIdentity = {
+    ok: true;
+    scheme: 'git';
+    externalId: string;
+    remoteUrl: string;
+    root: string;
+    commonDir: string;
+    handleHint: string;
+} | {
+    ok: true;
+    scheme: 'local-path';
+    externalId: string;
+    root: string;
+    handleHint: string;
+} | {
+    ok: false;
+    code: 'not-a-repo' | 'git-lookup-failed';
+    dir: string;
+    reason: string;
+};
+/** `https://User@GitHub.com:443/Org/Repo.git/` and `git@github.com:org/repo`
+ *  both give `github.com/org/repo`. A local remote (absolute path or
+ *  `file://`) gives `file:<realpath>`, resolved against `base` when relative. */
+export declare function normalizeRemoteUrl(url: string, base?: string): string;
+/** Owner handle a new repo object takes: the last segment of its external id (the normalized remote path, or the folder of a local-path repo), without `.git`. */
+export declare function handleHint(externalId: string): string;
+export declare function identifyCheckout(dir: string): CheckoutIdentity;
+/** `identifyCheckout` without blocking the event loop: the same parsing and cache, git run through `gitAsync`. */
+export declare function identifyCheckoutAsync(dir: string): Promise<CheckoutIdentity>;
+/** Checkouts enclosing `dir`, innermost first; stops at the first directory
+ *  that is not in a repo. A failed lookup ends the chain and is returned last. */
+export declare function checkoutChain(dir: string): Promise<CheckoutIdentity[]>;

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

@@ -0,0 +1,147 @@
+/** Repo identity of a checkout: offline, credential-free, deterministic.
+ *  A git checkout with an `origin` remote is identified by its normalized
+ *  origin URL (scheme `git`); a git checkout without `origin` by the realpath
+ *  of its main worktree root (scheme `local-path`, does not sync).
+ *  Imported by migrations, so it imports only `node:*`, git.ts and fs-utils.ts. */
+import { existsSync } from 'node:fs';
+import { basename, dirname, isAbsolute, resolve } from 'node:path';
+import { gitAsync, gitSync } from '../../git.js';
+import { realpathOrSelf } from '../../fs-utils.js';
+const LOOKUP_TIMEOUT_MS = 5000;
+const CACHE_MS = 60_000;
+// Also holds `not-a-repo`: every checkout chain ends by probing the directory above
+// its outermost root, so an uncached miss spawned git on every lookup.
+const cache = new Map();
+/** `https://User@GitHub.com:443/Org/Repo.git/` and `git@github.com:org/repo`
+ *  both give `github.com/org/repo`. A local remote (absolute path or
+ *  `file://`) gives `file:<realpath>`, resolved against `base` when relative. */
+export function normalizeRemoteUrl(url, base) {
+    const u = url.trim();
+    let host;
+    let path;
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(u);
+    if (scheme) {
+        if (scheme[1].toLowerCase() === 'file')
+            return `file:${localPath(decodeURIComponent(u.slice('file://'.length)), base)}`;
+        const rest = u.slice(scheme[0].length);
+        const slash = rest.indexOf('/');
+        const authority = slash < 0 ? rest : rest.slice(0, slash);
+        path = slash < 0 ? '' : rest.slice(slash);
+        host = authority.replace(/^.*@/, '').replace(/:\d*$/, '');
+    }
+    else {
+        const scp = /^(?:[^@/]+@)?([^:/]+):(.*)$/.exec(u);
+        if (!scp)
+            return `file:${localPath(u, base)}`;
+        host = scp[1];
+        path = scp[2];
+    }
+    path = path.replace(/^\/*~?/, '').replace(/\/+$/, '').replace(/\.git$/i, '').replace(/\/+$/, '');
+    return `${host}/${path}`.toLowerCase();
+}
+function localPath(p, base) {
+    const abs = isAbsolute(p) ? p : resolve(base ?? process.cwd(), p);
+    return realpathOrSelf(abs).replace(/\/+$/, '') || '/';
+}
+/** Owner handle a new repo object takes: the last segment of its external id (the normalized remote path, or the folder of a local-path repo), without `.git`. */
+export function handleHint(externalId) {
+    const path = externalId.startsWith('file:') ? externalId.slice('file:'.length) : externalId;
+    return basename(path).replace(/\.git$/i, '') || 'repo';
+}
+const REV_PARSE = ['rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir'];
+const REMOTE_URL = ['remote', 'get-url', 'origin'];
+function cached(abs) {
+    const hit = cache.get(abs);
+    return hit && Date.now() - hit.at < CACHE_MS ? hit.id : undefined;
+}
+// A deleted directory (a removed worktree, a stale node cwd) is in no repo; git cannot even start there.
+function missingDir(abs) {
+    return existsSync(abs) ? undefined : { ok: false, code: 'not-a-repo', dir: abs, reason: 'directory does not exist' };
+}
+/** Reads `rev-parse` output: the finished identity when it already decides one, else the checkout's roots. */
+function parseRevParse(rev, abs) {
+    if (rev.timedOut)
+        return { done: { ok: false, code: 'git-lookup-failed', dir: abs, reason: `git lookup timed out after ${LOOKUP_TIMEOUT_MS}ms` } };
+    if (rev.status !== 0) {
+        if (/not a git repository/i.test(rev.stderr)) {
+            const miss = { ok: false, code: 'not-a-repo', dir: abs, reason: rev.stderr.trim() };
+            cache.set(abs, { at: Date.now(), id: miss });
+            return { done: miss };
+        }
+        return { done: { ok: false, code: 'git-lookup-failed', dir: abs, reason: rev.stderr.trim() || rev.processError || `git rev-parse exited ${rev.status}` } };
+    }
+    const [rootLine, commonLine] = rev.stdout.split(/\r?\n/).map((l) => l.trim());
+    if (!rootLine || !commonLine) {
+        return { done: { ok: false, code: 'git-lookup-failed', dir: abs, reason: 'git rev-parse returned no work tree (bare repository?)' } };
+    }
+    return { root: realpathOrSelf(rootLine), commonDir: realpathOrSelf(commonLine) };
+}
+/** Reads `remote get-url origin` output into the checkout's identity, and caches it when it is one. */
+function parseOrigin(origin, abs, root, commonDir) {
+    if (origin.timedOut)
+        return { ok: false, code: 'git-lookup-failed', dir: abs, reason: `git remote lookup timed out after ${LOOKUP_TIMEOUT_MS}ms` };
+    let id;
+    const remoteUrl = origin.stdout.trim();
+    if (origin.status === 0 && remoteUrl !== '') {
+        const externalId = normalizeRemoteUrl(remoteUrl, root);
+        id = { ok: true, scheme: 'git', externalId, remoteUrl, root, commonDir, handleHint: handleHint(externalId) };
+    }
+    else if (/no such remote/i.test(origin.stderr)) {
+        const mainRoot = basename(commonDir) === '.git' ? dirname(commonDir) : commonDir;
+        id = { ok: true, scheme: 'local-path', externalId: mainRoot, root, handleHint: handleHint(mainRoot) };
+    }
+    else {
+        return { ok: false, code: 'git-lookup-failed', dir: abs, reason: origin.stderr.trim() || `git remote get-url exited ${origin.status}` };
+    }
+    cache.set(abs, { at: Date.now(), id });
+    return id;
+}
+export function identifyCheckout(dir) {
+    const abs = realpathOrSelf(resolve(dir));
+    const early = cached(abs) ?? missingDir(abs);
+    if (early)
+        return early;
+    const rev = parseRevParse(gitSync(REV_PARSE, abs, undefined, { timeoutMs: LOOKUP_TIMEOUT_MS }), abs);
+    if ('done' in rev)
+        return rev.done;
+    return parseOrigin(gitSync(REMOTE_URL, rev.root, undefined, { timeoutMs: LOOKUP_TIMEOUT_MS }), abs, rev.root, rev.commonDir);
+}
+// Concurrent lookups of one directory share a single in-flight pair of git processes.
+const inflight = new Map();
+/** `identifyCheckout` without blocking the event loop: the same parsing and cache, git run through `gitAsync`. */
+export async function identifyCheckoutAsync(dir) {
+    const abs = realpathOrSelf(resolve(dir));
+    const early = cached(abs) ?? missingDir(abs);
+    if (early)
+        return early;
+    const running = inflight.get(abs);
+    if (running)
+        return await running;
+    const lookup = (async () => {
+        const rev = parseRevParse(await gitAsync(REV_PARSE, abs, undefined, { timeoutMs: LOOKUP_TIMEOUT_MS }), abs);
+        if ('done' in rev)
+            return rev.done;
+        return parseOrigin(await gitAsync(REMOTE_URL, rev.root, undefined, { timeoutMs: LOOKUP_TIMEOUT_MS }), abs, rev.root, rev.commonDir);
+    })().finally(() => inflight.delete(abs));
+    inflight.set(abs, lookup);
+    return await lookup;
+}
+/** Checkouts enclosing `dir`, innermost first; stops at the first directory
+ *  that is not in a repo. A failed lookup ends the chain and is returned last. */
+export async function checkoutChain(dir) {
+    const chain = [];
+    let at = dir;
+    for (;;) {
+        const id = await identifyCheckoutAsync(at);
+        if (!id.ok) {
+            if (id.code === 'git-lookup-failed')
+                chain.push(id);
+            return chain;
+        }
+        chain.push(id);
+        const parent = dirname(id.root);
+        if (parent === id.root)
+            return chain;
+        at = parent;
+    }
+}

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

@@ -0,0 +1,4 @@
+/** The import surface of repo sync for other domains. */
+export { startRepoSync, noteNodeWorking, noteNodeBooting, noteRepoDocumentsChanged, syncRepo, FIRST_FETCH_WAIT_MS } from './sync.js';
+export type { SyncOutcome, SyncStep } from './sync.js';
+export type { ImportResult } from './exchange.js';

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

@@ -0,0 +1,2 @@
+/** The import surface of repo sync for other domains. */
+export { startRepoSync, noteNodeWorking, noteNodeBooting, noteRepoDocumentsChanged, syncRepo, FIRST_FETCH_WAIT_MS } from './sync.js';

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

@@ -0,0 +1,30 @@
+/** crtr's own bare git repo holding one repo object's `refs/crtr/docs`. Nothing
+ *  here touches a user's checkout: fetch and push address the remote URL directly.
+ *  Local refs: `refs/crtr/docs` (local tip), `refs/crtr/remote-docs` (last fetched),
+ *  `refs/crtr/imported` (tree last imported into canvas.db). */
+export interface Mirror {
+    dir: string;
+}
+export type RemoteResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare const FIRST_FETCH_MARKER = "first-fetch-done";
+export declare function openMirror(repoObjectId: string): Promise<Mirror>;
+export declare function resolveRef(m: Mirror, ref: string): Promise<string | null>;
+export declare function readTree(m: Mirror, ref: string): Promise<Map<string, string> | null>;
+export declare function commitTree(m: Mirror, files: Map<string, string>, parents: string[], message: string): Promise<string>;
+/** `expectOld` null requires the ref to not exist yet. */
+export declare function setRef(m: Mirror, ref: string, sha: string, expectOld: string | null): Promise<void>;
+export declare function mergeBase(m: Mirror, a: string, b: string): Promise<string | null>;
+export declare function isAncestor(m: Mirror, a: string, b: string): Promise<boolean>;
+export declare function remoteDocsTip(m: Mirror, url: string): Promise<RemoteResult<string | null>>;
+export declare function fetchDocs(m: Mirror, url: string): Promise<RemoteResult<string>>;
+/** Never forced; `--no-verify` so no user hook runs. A non-fast-forward answers `rejected`. */
+export declare function pushDocs(m: Mirror, url: string, sha: string): Promise<RemoteResult<'pushed'> | {
+    ok: false;
+    reason: 'rejected';
+}>;