@mhalle/vost 0.8.1

package/dist/mirror.js

@@ -0,0 +1,270 @@
+/**
+ * Mirror (backup/restore) operations for vost.
+ *
+ * Uses isomorphic-git's push/fetch for HTTP transport.
+ * Each ref is pushed/fetched individually to achieve mirror semantics.
+ */
+import git from 'isomorphic-git';
+/**
+ * Inject credentials into an HTTPS URL if available.
+ *
+ * Tries `git credential fill` first (works with any configured helper:
+ * osxkeychain, wincred, libsecret, `gh auth setup-git`, etc.).  Falls
+ * back to `gh auth token` for GitHub hosts.  Non-HTTPS URLs and URLs
+ * that already contain credentials are returned unchanged.
+ *
+ * Requires Node.js — returns the original URL unchanged in browser
+ * environments where `child_process` is not available.
+ *
+ * @param url - The URL to resolve credentials for.
+ * @returns The URL with credentials injected, or the original URL.
+ */
+export async function resolveCredentials(url) {
+    if (!url.startsWith('https://'))
+        return url;
+    const parsed = new URL(url);
+    if (parsed.username)
+        return url; // already has credentials
+    const hostname = parsed.hostname;
+    let execFileSync;
+    try {
+        const cp = await import('node:child_process');
+        execFileSync = cp.execFileSync;
+    }
+    catch {
+        return url; // Not in Node.js
+    }
+    // Try git credential fill
+    try {
+        const input = `protocol=https\nhost=${hostname}\n\n`;
+        const output = execFileSync('git', ['credential', 'fill'], {
+            input,
+            timeout: 5000,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'ignore'],
+        });
+        const creds = {};
+        for (const line of output.trim().split('\n')) {
+            const eq = line.indexOf('=');
+            if (eq > 0)
+                creds[line.slice(0, eq)] = line.slice(eq + 1);
+        }
+        if (creds.username && creds.password) {
+            parsed.username = creds.username;
+            parsed.password = creds.password;
+            return parsed.toString();
+        }
+    }
+    catch {
+        // git credential fill failed or not available
+    }
+    // Fallback: gh auth token (GitHub-specific)
+    try {
+        const token = execFileSync('gh', ['auth', 'token', '--hostname', hostname], {
+            timeout: 5000,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        if (token) {
+            parsed.username = 'x-access-token';
+            parsed.password = token;
+            return parsed.toString();
+        }
+    }
+    catch {
+        // gh not available or not authenticated
+    }
+    return url;
+}
+/**
+ * Push all local refs to url, creating an exact mirror.
+ * Remote-only refs are deleted.
+ *
+ * @param store - The GitStore to backup from.
+ * @param url   - Remote repository URL (HTTPS or local path).
+ * @param opts  - Options: `http` client, `dryRun` to compute diff without pushing,
+ *                and optional `onAuth` callback for credentials.
+ * @returns A {@link MirrorDiff} describing what changed (or would change).
+ */
+export async function backup(store, url, opts) {
+    const diff = await diffRefs(store, url, 'push', opts);
+    if (!opts.dryRun) {
+        // Push all local branches
+        const branches = await store.branches.list();
+        for (const branch of branches) {
+            await git.push({
+                fs: store._fsModule,
+                gitdir: store._gitdir,
+                http: opts.http,
+                url,
+                ref: `refs/heads/${branch}`,
+                remoteRef: `refs/heads/${branch}`,
+                force: true,
+                onAuth: opts.onAuth,
+            });
+        }
+        // Push all tags
+        const tags = await store.tags.list();
+        for (const tag of tags) {
+            await git.push({
+                fs: store._fsModule,
+                gitdir: store._gitdir,
+                http: opts.http,
+                url,
+                ref: `refs/tags/${tag}`,
+                remoteRef: `refs/tags/${tag}`,
+                force: true,
+                onAuth: opts.onAuth,
+            });
+        }
+        // Delete stale remote refs
+        for (const change of diff.delete) {
+            try {
+                await git.push({
+                    fs: store._fsModule,
+                    gitdir: store._gitdir,
+                    http: opts.http,
+                    url,
+                    ref: change.ref,
+                    delete: true,
+                    onAuth: opts.onAuth,
+                });
+            }
+            catch {
+                // Ignore delete failures
+            }
+        }
+    }
+    return diff;
+}
+/**
+ * Fetch all remote refs from url, overwriting local state.
+ * Local-only refs are deleted.
+ *
+ * @param store - The GitStore to restore into.
+ * @param url   - Remote repository URL (HTTPS or local path).
+ * @param opts  - Options: `http` client, `dryRun` to compute diff without fetching,
+ *                and optional `onAuth` callback for credentials.
+ * @returns A {@link MirrorDiff} describing what changed (or would change).
+ */
+export async function restore(store, url, opts) {
+    const diff = await diffRefs(store, url, 'pull', opts);
+    if (!opts.dryRun) {
+        // Fetch all remote refs
+        await git.fetch({
+            fs: store._fsModule,
+            gitdir: store._gitdir,
+            http: opts.http,
+            url,
+            tags: true,
+            prune: true,
+            onAuth: opts.onAuth,
+        });
+        // Update local refs to match remote
+        const remoteRefs = await git.listServerRefs({
+            http: opts.http,
+            url,
+            onAuth: opts.onAuth,
+        });
+        const remoteRefMap = new Map();
+        for (const ref of remoteRefs) {
+            if (ref.ref !== 'HEAD' && !ref.ref.endsWith('^{}')) {
+                remoteRefMap.set(ref.ref, ref.oid);
+            }
+        }
+        // Set local refs to match remote
+        for (const [ref, oid] of remoteRefMap) {
+            await git.writeRef({
+                fs: store._fsModule,
+                gitdir: store._gitdir,
+                ref,
+                value: oid,
+                force: true,
+            });
+        }
+        // Delete local refs not on remote
+        const localBranches = await store.branches.list();
+        for (const branch of localBranches) {
+            if (!remoteRefMap.has(`refs/heads/${branch}`)) {
+                await git.deleteRef({
+                    fs: store._fsModule,
+                    gitdir: store._gitdir,
+                    ref: `refs/heads/${branch}`,
+                });
+            }
+        }
+        const localTags = await store.tags.list();
+        for (const tag of localTags) {
+            if (!remoteRefMap.has(`refs/tags/${tag}`)) {
+                await git.deleteRef({
+                    fs: store._fsModule,
+                    gitdir: store._gitdir,
+                    ref: `refs/tags/${tag}`,
+                });
+            }
+        }
+    }
+    return diff;
+}
+/**
+ * Compare local and remote refs.
+ */
+async function diffRefs(store, url, direction, opts) {
+    // Get remote refs
+    let remoteRefs;
+    try {
+        const refs = await git.listServerRefs({
+            http: opts.http,
+            url,
+            onAuth: opts.onAuth,
+        });
+        remoteRefs = new Map();
+        for (const ref of refs) {
+            if (ref.ref !== 'HEAD' && !ref.ref.endsWith('^{}')) {
+                remoteRefs.set(ref.ref, ref.oid);
+            }
+        }
+    }
+    catch {
+        remoteRefs = new Map();
+    }
+    // Get local refs
+    const localRefs = new Map();
+    const branches = await store.branches.list();
+    for (const branch of branches) {
+        const oid = await git.resolveRef({
+            fs: store._fsModule,
+            gitdir: store._gitdir,
+            ref: `refs/heads/${branch}`,
+        });
+        localRefs.set(`refs/heads/${branch}`, oid);
+    }
+    const tags = await store.tags.list();
+    for (const tag of tags) {
+        const oid = await git.resolveRef({
+            fs: store._fsModule,
+            gitdir: store._gitdir,
+            ref: `refs/tags/${tag}`,
+        });
+        localRefs.set(`refs/tags/${tag}`, oid);
+    }
+    const [src, dest] = direction === 'push' ? [localRefs, remoteRefs] : [remoteRefs, localRefs];
+    const add = [];
+    const update = [];
+    const del = [];
+    for (const [ref, sha] of src) {
+        if (!dest.has(ref)) {
+            add.push({ ref, newTarget: sha });
+        }
+        else if (dest.get(ref) !== sha) {
+            update.push({ ref, oldTarget: dest.get(ref), newTarget: sha });
+        }
+    }
+    for (const [ref] of dest) {
+        if (!src.has(ref)) {
+            del.push({ ref, oldTarget: dest.get(ref) });
+        }
+    }
+    return { add, update, delete: del };
+}
+//# sourceMappingURL=mirror.js.map

package/dist/mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror.js","sourceRoot":"","sources":["../src/mirror.ts"],"names":[],"mappings":"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"}

package/dist/notes.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Git notes support: per-namespace mapping of commit hashes to note text.
+ *
+ * Notes live at `refs/notes/<namespace>`, mapping commit hashes to UTF-8
+ * text blobs. Reads handle both flat (40-char filename) and 2/38 fanout
+ * layouts. Writes always use flat. Each mutation creates a commit on the
+ * namespace's notes ref chain, or batch() defers to a single commit.
+ */
+import type { GitStore } from './gitstore.js';
+/**
+ * One git notes namespace, backed by `refs/notes/<name>`.
+ *
+ * Maps 40-char hex commit hashes to UTF-8 note text.
+ * Supports `get`, `set`, `delete`, `has`, `list`, and `batch()`.
+ */
+export declare class NoteNamespace {
+    /** @internal */ _store: GitStore;
+    /** @internal */ _namespace: string;
+    /** @internal */ _ref: string;
+    constructor(store: GitStore, namespace: string);
+    toString(): string;
+    private get _fs();
+    private get _gitdir();
+    /** Resolve the notes ref to a commit OID, or null. */
+    private _tipOid;
+    /** @internal Read the tree OID from the tip commit, or null. */
+    _treeOid(): Promise<string | null>;
+    /** Find the blob OID for `hash` in a tree, handling flat and fanout. */
+    private _findNoteInTree;
+    /** Yield all [hash, blobOid] pairs from the tree. */
+    private _iterNotes;
+    /** @internal Build a new note tree from a base tree + writes + deletes. */
+    _buildNoteTree(baseTreeOid: string | null, writes: Map<string, string>, // hash → text
+    deletes: Set<string>): Promise<string>;
+    /** @internal Commit a new tree to the notes ref under repo lock. */
+    _commitNoteTree(newTreeOid: string, message: string): Promise<void>;
+    /**
+     * Get the note text for a commit hash.
+     *
+     * @param hash - 40-char lowercase hex commit hash.
+     * @returns The note text (UTF-8).
+     * @throws {GitStoreError} If no note exists for the hash.
+     */
+    get(hash: string): Promise<string>;
+    /**
+     * Set or overwrite the note text for a commit hash.
+     *
+     * Creates a commit on the namespace's notes ref.
+     *
+     * @param hash - 40-char lowercase hex commit hash.
+     * @param text - Note text (UTF-8 string).
+     */
+    set(hash: string, text: string): Promise<void>;
+    /**
+     * Delete the note for a commit hash.
+     *
+     * @param hash - 40-char lowercase hex commit hash.
+     * @throws {GitStoreError} If no note exists for the hash.
+     */
+    delete(hash: string): Promise<void>;
+    /**
+     * Check if a note exists for a commit hash.
+     *
+     * @param hash - 40-char lowercase hex commit hash.
+     * @returns True if a note exists.
+     */
+    has(hash: string): Promise<boolean>;
+    /**
+     * List all commit hashes that have notes in this namespace.
+     *
+     * @returns Array of 40-char hex commit hashes.
+     */
+    list(): Promise<string[]>;
+    /** Return the number of notes in this namespace. */
+    size(): Promise<number>;
+    /**
+     * Get the note for the current HEAD commit.
+     *
+     * @returns The note text.
+     * @throws {GitStoreError} If HEAD is dangling or no note exists.
+     */
+    getForCurrentBranch(): Promise<string>;
+    /**
+     * Set the note for the current HEAD commit.
+     *
+     * @param text - Note text (UTF-8 string).
+     * @throws {GitStoreError} If HEAD is dangling.
+     */
+    setForCurrentBranch(text: string): Promise<void>;
+    /**
+     * Return a NotesBatch that collects writes/deletes and applies them
+     * in a single commit when `commit()` is called.
+     *
+     * @returns A new {@link NotesBatch} instance.
+     */
+    batch(): NotesBatch;
+}
+/**
+ * Collects note writes and deletes, applying them in one commit.
+ *
+ * Call `set()` and `delete()` to stage changes, then `commit()` to flush.
+ */
+export declare class NotesBatch {
+    private _ns;
+    private _writes;
+    private _deletes;
+    private _closed;
+    constructor(ns: NoteNamespace);
+    /**
+     * Stage a note write.
+     *
+     * @param hash - 40-char lowercase hex commit hash.
+     * @param text - Note text (UTF-8 string).
+     */
+    set(hash: string, text: string): Promise<void>;
+    /**
+     * Stage a note deletion.
+     *
+     * @param hash - 40-char lowercase hex commit hash.
+     */
+    delete(hash: string): void;
+    /**
+     * Commit all staged writes and deletes in a single commit.
+     *
+     * After calling this the batch is closed and no further changes are allowed.
+     */
+    commit(): Promise<void>;
+}
+/**
+ * Outer container for git notes namespaces on a GitStore.
+ *
+ * `store.notes.commits` returns the default namespace (`refs/notes/commits`).
+ * `store.notes.namespace('reviews')` returns a custom namespace.
+ */
+export declare class NoteDict {
+    private _store;
+    constructor(store: GitStore);
+    toString(): string;
+    /** The default `refs/notes/commits` namespace. */
+    get commits(): NoteNamespace;
+    /**
+     * Access a custom notes namespace.
+     *
+     * @param name - Namespace name (e.g. 'reviews').
+     * @returns NoteNamespace for `refs/notes/<name>`.
+     */
+    namespace(name: string): NoteNamespace;
+}