@volter/twin-github 0.1.2 → 2.0.1

package/dist/src/github-git-plane.js

@@ -0,0 +1,407 @@
+// GITHUB GIT PLANE — the pack half of the kernel's git library (the engine slot,
+// docs/contributing/architecture.md#the-engine-slot). Every repository's git objects live in ONE content-addressed
+// object store per world over the blob seam (R11) — a fork copies refs, never objects; a deleted
+// repository drops its refs — and every repository's refs live in the world store, carried by a
+// snapshot like any other world state. Trees, commits and tags go through the library's codecs;
+// ancestry, merge base and file diffs through its history. No `git` binary anywhere in this module.
+//
+// The names and semantics are the ones the twin's REST plumbing has always called; the calls are
+// async now, because the store is.
+import { join } from 'node:path';
+import { getActiveBlobStore, getActiveWorldStore, git, worldPaths } from '@volter/world-core';
+const { GitObjectStore, GitRefs, decodeCommit, decodeTag, decodeTree, diffFiles, encodeCommit, encodeTag, encodeTree, isAncestor, mergeBase, mergeText } = git;
+const SEGMENT_RE = /^[A-Za-z0-9_.-]+$/;
+const SHA_RE = /^[0-9a-f]{40}$/i;
+/** The git plane root for a twin instance: `<state>/github/git`. */
+export function githubGitPlaneDir(root) {
+    return join(worldPaths('github', root).dir, 'git');
+}
+/** A repository's ref prefix in the world store — `<plane>/<owner>/<name>.git` — after validating the name. */
+export function bareRepoDir(repo, root) {
+    const [owner, name, extra] = repo.split('/');
+    if (!owner || !name || extra !== undefined || !SEGMENT_RE.test(owner) || !SEGMENT_RE.test(name) || owner === '..' || name === '..' || owner === '.' || name === '.') {
+        throw new Error(`github twin git plane: invalid repository name ${JSON.stringify(repo)}`);
+    }
+    return join(githubGitPlaneDir(root), owner, `${name}.git`);
+}
+/** ONE object store per world: content-addressed, shared by every repository of the world. */
+function objectStore(root) {
+    return new GitObjectStore(getActiveBlobStore(), join(githubGitPlaneDir(root), 'objects'));
+}
+function refsOf(repo, root) {
+    return new GitRefs(getActiveWorldStore(), bareRepoDir(repo, root));
+}
+export function hasBareRepo(repo, root) {
+    return getActiveWorldStore().exists(join(bareRepoDir(repo, root), 'HEAD'));
+}
+/** Create the repository's refs (HEAD → the default branch) when absent; answers its prefix. */
+export function ensureBareRepo(repo, root, defaultBranch = 'main') {
+    const dir = bareRepoDir(repo, root);
+    if (!hasBareRepo(repo, root))
+        refsOf(repo, root).setHead(`refs/heads/${defaultBranch}`);
+    return dir;
+}
+export async function objectExistsInPlane(repo, sha, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return false;
+    return objectStore(root).has(sha.toLowerCase());
+}
+export async function objectTypeInPlane(repo, sha, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return null;
+    const obj = await objectStore(root).read(sha.toLowerCase());
+    return obj?.type ?? null;
+}
+export async function writeGitBlobToPlane(repo, contentB64, root) {
+    ensureBareRepo(repo, root);
+    return objectStore(root).write('blob', new Uint8Array(Buffer.from(contentB64, 'base64')));
+}
+export async function readGitBlobFromPlane(repo, sha, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return null;
+    const obj = await objectStore(root).read(sha.toLowerCase());
+    if (!obj || obj.type !== 'blob')
+        return null;
+    return { content_b64: Buffer.from(obj.payload).toString('base64'), size: obj.payload.length };
+}
+const isTreeMode = (mode) => mode.replace(/^0+(?=\d)/, '') === '40000';
+const modeOut = (mode) => (isTreeMode(mode) ? '040000' : mode);
+const typeOfMode = (mode) => (isTreeMode(mode) ? 'tree' : mode.replace(/^0+/, '') === '160000' ? 'commit' : 'blob');
+/** `ls-tree -r`: every blob under `sha`, keyed by its full path. */
+async function lsTreeRecursive(store, sha, prefix = '') {
+    const out = new Map();
+    const obj = await store.read(sha);
+    if (!obj || obj.type !== 'tree')
+        return out;
+    for (const e of decodeTree(obj.payload)) {
+        const path = prefix ? `${prefix}/${e.name}` : e.name;
+        if (isTreeMode(e.mode)) {
+            for (const [p, v] of await lsTreeRecursive(store, e.sha, path))
+                out.set(p, v);
+        }
+        else
+            out.set(path, { mode: e.mode, type: typeOfMode(e.mode), sha: e.sha });
+    }
+    return out;
+}
+/** `mktree`, level by level, from a flat path → entry map. */
+async function buildTreeFromFlat(store, flat) {
+    const rootNode = { entries: new Map(), children: new Map() };
+    for (const [path, e] of flat) {
+        const parts = path.split('/');
+        let node = rootNode;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const seg = parts[i];
+            if (!node.children.has(seg))
+                node.children.set(seg, { entries: new Map(), children: new Map() });
+            node = node.children.get(seg);
+        }
+        node.entries.set(parts[parts.length - 1], { mode: e.mode, sha: e.sha });
+    }
+    const write = async (node) => {
+        const level = [];
+        for (const [name, child] of node.children)
+            level.push({ name, mode: '40000', sha: await write(child) });
+        for (const [name, e] of node.entries)
+            level.push({ name, mode: e.mode.replace(/^0+(?=\d)/, ''), sha: e.sha });
+        return store.write('tree', encodeTree(level));
+    };
+    return write(rootNode);
+}
+/** A tree from `entries` over `baseTreeSha` (an entry with no sha deletes its path). */
+export async function writeGitTreeToPlane(repo, entries, baseTreeSha, root) {
+    ensureBareRepo(repo, root);
+    const store = objectStore(root);
+    const flat = baseTreeSha && (await objectTypeInPlane(repo, baseTreeSha, root)) === 'tree'
+        ? await lsTreeRecursive(store, baseTreeSha.toLowerCase())
+        : new Map();
+    for (const e of entries) {
+        if (!e.sha) {
+            flat.delete(e.path);
+            continue;
+        }
+        flat.set(e.path, { mode: e.mode, type: e.type, sha: e.sha });
+    }
+    return buildTreeFromFlat(store, flat);
+}
+/** `ls-tree -l`: one level, blob sizes measured. */
+export async function readGitTreeFromPlane(repo, sha, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return null;
+    const store = objectStore(root);
+    const obj = await store.read(sha.toLowerCase());
+    if (!obj || obj.type !== 'tree')
+        return null;
+    const out = [];
+    for (const e of decodeTree(obj.payload)) {
+        const entry = { path: e.name, mode: modeOut(e.mode), type: typeOfMode(e.mode), sha: e.sha };
+        if (entry.type === 'blob') {
+            const b = await store.read(e.sha);
+            if (b)
+                entry.size = b.payload.length;
+        }
+        out.push(entry);
+    }
+    return out;
+}
+const TWIN_IDENT = { name: 'github-twin', email: 'github-twin@localhost' };
+const identOf = (ident, occurredAt) => {
+    const who = ident ?? TWIN_IDENT;
+    return { name: who.name, email: who.email, time: Math.floor((Date.parse(who.date ?? occurredAt) || 0) / 1000), tz: '+0000' };
+};
+export async function writeGitCommitToPlane(repo, commit, root) {
+    ensureBareRepo(repo, root);
+    const c = { tree: commit.treeSha, parents: commit.parents, author: identOf(commit.author, commit.occurredAt), committer: identOf(commit.committer ?? commit.author, commit.occurredAt), message: commit.message };
+    return objectStore(root).write('commit', encodeCommit(c));
+}
+export async function readGitCommitFromPlane(repo, sha, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return null;
+    const obj = await objectStore(root).read(sha.toLowerCase());
+    if (!obj || obj.type !== 'commit')
+        return null;
+    const c = decodeCommit(obj.payload);
+    return { sha: sha.toLowerCase(), message: c.message.replace(/\n$/, ''), tree_sha: c.tree, parents: c.parents, author_name: c.author.name, author_email: c.author.email, created_at: new Date(c.author.time * 1000).toISOString() };
+}
+export async function writeGitTagToPlane(repo, tag, root) {
+    ensureBareRepo(repo, root);
+    return objectStore(root).write('tag', encodeTag({ object: tag.objectSha, type: tag.objectType, tag: tag.tag, tagger: identOf(tag.tagger, tag.occurredAt), message: tag.message }));
+}
+export async function readGitTagFromPlane(repo, sha, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return null;
+    const obj = await objectStore(root).read(sha.toLowerCase());
+    return !obj || obj.type !== 'tag' ? null : annotatedTag(sha, obj.payload);
+}
+/** An annotated tag object's fields. */
+function annotatedTag(sha, payload) {
+    const t = decodeTag(payload);
+    const out = { sha: sha.toLowerCase(), tag: t.tag, message: t.message.replace(/\n$/, ''), object_sha: t.object, object_type: t.type };
+    if (t.tagger) {
+        out.tagger_name = t.tagger.name;
+        out.created_at = new Date(t.tagger.time * 1000).toISOString();
+    }
+    return out;
+}
+// Objects are immutable, so a chain once found whole stays whole while its objects are kept: the walk stops at
+// an object an earlier walk proved (still present), as git's connectivity check stops at what it already has.
+// Without it every ref update re-read the repository's whole history.
+const provenWhole = new WeakMap();
+/** Every object `sha` reaches (commits through parents and trees, trees through entries) is present. */
+async function chainComplete(store, sha, root, limit = 20000) {
+    const blobs = getActiveBlobStore();
+    const planes = provenWhole.get(blobs) ?? provenWhole.set(blobs, new Map()).get(blobs);
+    const plane = githubGitPlaneDir(root);
+    const proven = planes.get(plane) ?? planes.set(plane, new Set()).get(plane);
+    const seen = new Set();
+    const stack = [sha];
+    while (stack.length) {
+        const s = stack.pop();
+        if (seen.has(s))
+            continue;
+        seen.add(s);
+        if (seen.size > limit)
+            return true; // bounded: a huge history is not a dangling one
+        if (proven.has(s)) {
+            if (await store.has(s))
+                continue;
+            proven.clear();
+            return false;
+        }
+        const obj = await store.read(s);
+        if (!obj)
+            return false;
+        if (obj.type === 'commit') {
+            const c = decodeCommit(obj.payload);
+            stack.push(c.tree, ...c.parents);
+        }
+        else if (obj.type === 'tree') {
+            for (const e of decodeTree(obj.payload))
+                if (!/^160000$/.test(e.mode.replace(/^0+/, '')))
+                    stack.push(e.sha);
+        }
+        else if (obj.type === 'tag')
+            stack.push(decodeTag(obj.payload).object);
+    }
+    for (const s of seen)
+        proven.add(s);
+    return true;
+}
+/** Point `ref` at `sha` — only at an object the plane holds whole (a dangling chain is not clonable). */
+export async function updateGitRefInPlane(repo, ref, sha, root, expected) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(sha))
+        return false;
+    const store = objectStore(root);
+    if (!(await store.has(sha.toLowerCase())) || !(await chainComplete(store, sha.toLowerCase(), root)))
+        return false;
+    const refs = refsOf(repo, root);
+    return refs.withLock(() => {
+        if (expected !== undefined && refs.get(ref) !== expected)
+            return false;
+        refs.set(ref, sha.toLowerCase());
+        return true;
+    });
+}
+export async function deleteGitRefInPlane(repo, ref, root) {
+    if (!hasBareRepo(repo, root))
+        return;
+    refsOf(repo, root).delete(ref);
+}
+export function setBareRepoHead(repo, branch, root) {
+    if (!hasBareRepo(repo, root))
+        return;
+    refsOf(repo, root).setHead(`refs/heads/${branch}`);
+}
+/** Drop the repository's refs; its objects stay in the world's store (content-addressed, shared). */
+export function deleteBareRepo(repo, root) {
+    if (!hasBareRepo(repo, root))
+        return;
+    const refs = refsOf(repo, root);
+    for (const r of refs.list())
+        refs.delete(r.name);
+    getActiveWorldStore().remove(join(bareRepoDir(repo, root), 'HEAD'));
+}
+/** A fork shares the world's object store: copy the refs and HEAD, nothing else. */
+export function forkBareRepo(parentRepo, forkRepo, root, defaultBranch = 'main') {
+    bareRepoDir(forkRepo, root); // validates the fork name before any copy
+    if (hasBareRepo(forkRepo, root))
+        return;
+    if (!hasBareRepo(parentRepo, root)) {
+        ensureBareRepo(forkRepo, root, defaultBranch);
+        return;
+    }
+    const from = refsOf(parentRepo, root);
+    const to = refsOf(forkRepo, root);
+    to.setHead(from.head());
+    for (const r of from.list())
+        to.set(r.name, r.sha);
+}
+export async function isAncestorInPlane(repo, ancestor, descendant, root) {
+    if (!hasBareRepo(repo, root) || !SHA_RE.test(ancestor) || !SHA_RE.test(descendant))
+        return false;
+    return isAncestor(objectStore(root), ancestor.toLowerCase(), descendant.toLowerCase());
+}
+export async function mergeBaseInPlane(repo, a, b, root) {
+    if (!(await objectExistsInPlane(repo, a, root)) || !(await objectExistsInPlane(repo, b, root)))
+        return null;
+    return mergeBase(objectStore(root), a.toLowerCase(), b.toLowerCase());
+}
+/** GitHub's compare: merge-base(base, head)..head, as the library's `diffFiles` computes it. */
+export async function diffFilesInPlane(repo, baseSha, headSha, root, opts = {}) {
+    if (!(await objectExistsInPlane(repo, baseSha, root)) || !(await objectExistsInPlane(repo, headSha, root)))
+        return null;
+    const files = await diffFiles(objectStore(root), baseSha.toLowerCase(), headSha.toLowerCase(), opts);
+    return files === null ? null : files.map((f) => ({ filename: f.filename, status: f.status, additions: f.additions, deletions: f.deletions, ...(f.sha !== undefined ? { sha: f.sha } : {}), ...(f.patch !== undefined ? { patch: f.patch } : {}) }));
+}
+export function isValidBranchName(name) {
+    if (!name || name.length > 250)
+        return false;
+    if (/[\s~^:?*[\\\x00-\x1f\x7f]/.test(name))
+        return false;
+    if (name.includes('..') || name.includes('@{') || name.includes('//'))
+        return false;
+    if (name.startsWith('/') || name.endsWith('/') || name.startsWith('.') || name.endsWith('.') || name.endsWith('.lock'))
+        return false;
+    return true;
+}
+/** `for-each-ref`: every ref with its object's sha and type. */
+export async function listGitPlaneRefs(repo, root) {
+    if (!hasBareRepo(repo, root))
+        return [];
+    const store = objectStore(root);
+    const out = [];
+    for (const r of refsOf(repo, root).list()) {
+        const obj = await store.read(r.sha);
+        out.push({ ref: r.name, object_sha: r.sha, object_type: obj?.type ?? 'commit' });
+    }
+    return out;
+}
+/** The library's view of a repository, for smart HTTP. */
+export function planeRepo(repo, root) {
+    return { store: objectStore(root), refs: refsOf(repo, root) };
+}
+/** A file both sides of a merge changed: its three texts merged into one blob, or nothing when they conflict (a side
+ *  that is not a text blob, modes that disagree, or edits that overlap). */
+async function mergeBothSides(store, original, ours, theirs) {
+    if (!ours || !theirs || !original || ours.type !== 'blob' || theirs.type !== 'blob' || original.type !== 'blob')
+        return null;
+    const mode = ours.mode === theirs.mode ? ours.mode : ours.mode === original.mode ? theirs.mode : theirs.mode === original.mode ? ours.mode : null;
+    if (!mode || !mode.startsWith('100'))
+        return null;
+    const objects = await Promise.all([original, ours, theirs].map(entry => store.read(entry.sha)));
+    if (objects.some(obj => !obj || obj.type !== 'blob' || obj.payload.includes(0)))
+        return null;
+    let contents;
+    try {
+        contents = objects.map(obj => new TextDecoder('utf-8', { fatal: true }).decode(obj.payload));
+    }
+    catch {
+        return null;
+    }
+    const content = mergeText(contents[0], contents[1], contents[2]);
+    return content === null ? null : { mode, type: 'blob', sha: await store.write('blob', new TextEncoder().encode(content)) };
+}
+/** Merge three trees, publishing the resulting ref only if its original tip still holds.
+ * Text edits merge against the common ancestor; no conflicted tree is published. A dry run answers
+ * the merged tree without writing a commit or moving the branch (a pull request's mergeability). */
+export async function mergeIntoBranchInPlane(repo, baseBranch, headSha, message, method, occurredAt, root, merger, dryRun = false) {
+    if (!hasBareRepo(repo, root))
+        return null;
+    const refs = refsOf(repo, root);
+    const ref = `refs/heads/${baseBranch}`;
+    const baseSha = refs.get(ref);
+    if (!baseSha)
+        return null;
+    const store = objectStore(root);
+    const base = await readGitCommitFromPlane(repo, baseSha, root);
+    const head = await readGitCommitFromPlane(repo, headSha, root);
+    if (!base || !head)
+        return { conflict: 'missing commit' };
+    if (await isAncestor(store, headSha, baseSha))
+        return { sha: baseSha };
+    const ancestorSha = await mergeBase(store, baseSha, headSha);
+    if (!ancestorSha)
+        return { conflict: 'unrelated histories' };
+    const ancestor = ancestorSha ? await readGitCommitFromPlane(repo, ancestorSha, root) : null;
+    const before = ancestor ? await lsTreeRecursive(store, ancestor.tree_sha) : new Map();
+    const left = await lsTreeRecursive(store, base.tree_sha);
+    const right = await lsTreeRecursive(store, head.tree_sha);
+    const merged = new Map(left);
+    const same = (a, b) => a?.mode === b?.mode && a?.sha === b?.sha;
+    for (const path of new Set([...before.keys(), ...left.keys(), ...right.keys()])) {
+        const original = before.get(path), ours = left.get(path), theirs = right.get(path);
+        if (same(ours, theirs) || same(theirs, original))
+            continue;
+        // both sides changed the file: its texts merge against the ancestor's, or the merge conflicts
+        if (!same(ours, original)) {
+            const both = await mergeBothSides(store, original, ours, theirs);
+            if (!both)
+                return { conflict: path };
+            merged.set(path, both);
+            continue;
+        }
+        if (theirs)
+            merged.set(path, theirs);
+        else
+            merged.delete(path);
+    }
+    // A file/directory collision must not produce a tree containing both names.
+    for (const path of merged.keys()) {
+        const parts = path.split('/');
+        for (let i = 1; i < parts.length; i++)
+            if (merged.has(parts.slice(0, i).join('/')))
+                return { conflict: path };
+    }
+    const treeSha = await buildTreeFromFlat(store, merged);
+    if (dryRun)
+        return { sha: treeSha };
+    // GitHub authors a merge made through the API or the web as the person who merged, committed by GitHub itself.
+    const sha = await writeGitCommitToPlane(repo, { message, treeSha, parents: method === 'merge' ? [baseSha, headSha] : [baseSha], occurredAt,
+        ...(merger ? { author: merger, committer: { name: 'GitHub', email: 'noreply@github.com' } } : {}) }, root);
+    return refs.withLock(() => {
+        if (refs.get(ref) !== baseSha)
+            return { conflict: 'base moved' };
+        refs.set(ref, sha);
+        return { sha };
+    });
+}

package/dist/src/github-mirror-state.d.ts

@@ -0,0 +1,2 @@
+/** The `mirror` store: the whole console payload, projected from the twin's github world. */
+export declare function githubMirrorState(root?: string): Record<string, unknown>;