git-remote-ops 0.1.0

package/esm/deps/jsr.io/@std/text/1.0.18/closest_string.js

@@ -0,0 +1,46 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+import { levenshteinDistance } from "./levenshtein_distance.js";
+/**
+ * Finds the most similar string from an array of strings.
+ *
+ * By default, calculates the distance between words using the
+ * {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
+ *
+ * @example Usage
+ * ```ts
+ * import { closestString } from "@std/text/closest-string";
+ * import { assertEquals } from "@std/assert";
+ *
+ * const possibleWords = ["length", "size", "blah", "help"];
+ * const suggestion = closestString("hep", possibleWords);
+ *
+ * assertEquals(suggestion, "help");
+ * ```
+ *
+ * @param givenWord The string to measure distance against
+ * @param possibleWords The string-array to pick the closest string from
+ * @param options The options for the comparison.
+ * @returns The closest string
+ */
+export function closestString(givenWord, possibleWords, options) {
+    if (possibleWords.length === 0) {
+        throw new TypeError("When using closestString(), the possibleWords array must contain at least one word");
+    }
+    const { caseSensitive, compareFn = levenshteinDistance } = { ...options };
+    if (!caseSensitive) {
+        givenWord = givenWord.toLowerCase();
+    }
+    let nearestWord = possibleWords[0];
+    let closestStringDistance = Infinity;
+    for (const each of possibleWords) {
+        const distance = caseSensitive
+            ? compareFn(givenWord, each)
+            : compareFn(givenWord, each.toLowerCase());
+        if (distance < closestStringDistance) {
+            nearestWord = each;
+            closestStringDistance = distance;
+        }
+    }
+    return nearestWord;
+}

package/esm/deps/jsr.io/@std/text/1.0.18/levenshtein_distance.js

@@ -0,0 +1,127 @@
+// Copyright 2018-2026 the Deno authors. MIT license.
+// This module is browser compatible.
+const { ceil } = Math;
+// This implements Myers' bit-vector algorithm as described here:
+// https://dl.acm.org/doi/pdf/10.1145/316542.316550
+const peq = new Uint32Array(0x110000);
+function myers32(t, p) {
+    const n = t.length;
+    const m = p.length;
+    for (let i = 0; i < m; i++) {
+        peq[p[i].codePointAt(0)] |= 1 << i;
+    }
+    const last = m - 1;
+    let pv = -1;
+    let mv = 0;
+    let score = m;
+    for (let j = 0; j < n; j++) {
+        const eq = peq[t[j].codePointAt(0)];
+        const xv = eq | mv;
+        const xh = (((eq & pv) + pv) ^ pv) | eq;
+        let ph = mv | ~(xh | pv);
+        let mh = pv & xh;
+        score += ((ph >>> last) & 1) - ((mh >>> last) & 1);
+        // Set the horizontal delta in the first row to +1
+        // because we are computing the distance between two full strings.
+        ph = (ph << 1) | 1;
+        mh = mh << 1;
+        pv = mh | ~(xv | ph);
+        mv = ph & xv;
+    }
+    for (let i = 0; i < m; i++) {
+        peq[p[i].codePointAt(0)] = 0;
+    }
+    return score;
+}
+function myersX(t, p) {
+    const n = t.length;
+    const m = p.length;
+    // Initialize the horizontal deltas to +1.
+    const h = new Int8Array(n).fill(1);
+    const bmax = ceil(m / 32) - 1;
+    // Process the blocks row by row so that we can use the fixed-size peq array.
+    for (let b = 0; b < bmax; b++) {
+        const start = b * 32;
+        const end = (b + 1) * 32;
+        for (let i = start; i < end; i++) {
+            peq[p[i].codePointAt(0)] |= 1 << i;
+        }
+        let pv = -1;
+        let mv = 0;
+        for (let j = 0; j < n; j++) {
+            const hin = h[j];
+            let eq = peq[t[j].codePointAt(0)];
+            const xv = eq | mv;
+            eq |= hin >>> 31;
+            const xh = (((eq & pv) + pv) ^ pv) | eq;
+            let ph = mv | ~(xh | pv);
+            let mh = pv & xh;
+            h[j] = (ph >>> 31) - (mh >>> 31);
+            ph = (ph << 1) | (-hin >>> 31);
+            mh = (mh << 1) | (hin >>> 31);
+            pv = mh | ~(xv | ph);
+            mv = ph & xv;
+        }
+        for (let i = start; i < end; i++) {
+            peq[p[i].codePointAt(0)] = 0;
+        }
+    }
+    const start = bmax * 32;
+    for (let i = start; i < m; i++) {
+        peq[p[i].codePointAt(0)] |= 1 << i;
+    }
+    const last = m - 1;
+    let pv = -1;
+    let mv = 0;
+    let score = m;
+    for (let j = 0; j < n; j++) {
+        const hin = h[j];
+        let eq = peq[t[j].codePointAt(0)];
+        const xv = eq | mv;
+        eq |= hin >>> 31;
+        const xh = (((eq & pv) + pv) ^ pv) | eq;
+        let ph = mv | ~(xh | pv);
+        let mh = pv & xh;
+        score += ((ph >>> last) & 1) - ((mh >>> last) & 1);
+        ph = (ph << 1) | (-hin >>> 31);
+        mh = (mh << 1) | (hin >>> 31);
+        pv = mh | ~(xv | ph);
+        mv = ph & xv;
+    }
+    for (let i = start; i < m; i++) {
+        peq[p[i].codePointAt(0)] = 0;
+    }
+    return score;
+}
+/**
+ * Calculates the
+ * {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}
+ * between two strings.
+ *
+ * > [!NOTE]
+ * > The complexity of this function is O(m * n), where m and n are the lengths
+ * > of the two strings. It's recommended to limit the length and validate input
+ * > if arbitrarily accepting input.
+ *
+ * @example Usage
+ * ```ts
+ * import { levenshteinDistance } from "@std/text/levenshtein-distance";
+ * import { assertEquals } from "@std/assert";
+ *
+ * assertEquals(levenshteinDistance("aa", "bb"), 2);
+ * ```
+ * @param str1 The first string.
+ * @param str2 The second string.
+ * @returns The Levenshtein distance between the two strings.
+ */
+export function levenshteinDistance(str1, str2) {
+    let t = [...str1];
+    let p = [...str2];
+    if (t.length < p.length) {
+        [p, t] = [t, p];
+    }
+    if (p.length === 0) {
+        return t.length;
+    }
+    return p.length <= 32 ? myers32(t, p) : myersX(t, p);
+}

package/esm/errors.js

@@ -0,0 +1,38 @@
+/**
+ * @module errors
+ *
+ * Tagged error classes returned (never thrown) from every public function.
+ *
+ * Each class wraps `better-result`'s `TaggedError` so failures carry a
+ * narrowable `_tag` field plus structured context (offsets, sha, http
+ * status, etc.). The {@link GitRemoteOpsError} union sweeps them up for
+ * `Result<T, GitRemoteOpsError>` return types throughout the public API.
+ *
+ * A `cause` field, when present, is the underlying thrown value preserved
+ * for `Error.cause`-style chaining.
+ */
+import { TaggedError } from "better-result";
+/** Anything that goes wrong while parsing a packfile or applying a delta. */
+export class PackParseError extends TaggedError("PackParseError")() {
+}
+/** Raised when a commit/tree body fails structural validation. */
+export class ObjectDecodeError extends TaggedError("ObjectDecodeError")() {
+}
+/** Malformed pkt-line framing (bad length prefix or truncation). */
+export class PktLineError extends TaggedError("PktLineError")() {
+}
+/** Server returned a `git-upload-pack` response we couldn't interpret. */
+export class UploadPackError extends TaggedError("UploadPackError")() {
+}
+/** Anything HTTP — network failure, non-2xx status, body-read error. */
+export class TransportError extends TaggedError("TransportError")() {
+}
+/** The requested ref didn't appear in the server's advertisement. */
+export class RefNotFoundError extends TaggedError("RefNotFoundError")() {
+}
+/** An object referenced by sha wasn't present in the materialized store. */
+export class ObjectNotFoundError extends TaggedError("ObjectNotFoundError")() {
+}
+/** Tree-walk couldn't reach the requested path. */
+export class PathNotFoundError extends TaggedError("PathNotFoundError")() {
+}

package/esm/index.js

@@ -0,0 +1,10 @@
+/**
+ * @module git-remote-ops
+ *
+ * Public entry point. Re-exports the {@link RemoteGit} client, the
+ * {@link Logger}, every {@link GitRemoteOpsError} subclass, and the shared
+ * type vocabulary. The CLI ships separately under `./cli`.
+ */
+export { RemoteGit } from "./client.js";
+export { Logger, NULL_LOGGER } from "./logger.js";
+export { ObjectDecodeError, ObjectNotFoundError, PackParseError, PathNotFoundError, PktLineError, RefNotFoundError, TransportError, UploadPackError, } from "./errors.js";

package/esm/logger.js

@@ -0,0 +1,216 @@
+/**
+ * @module logger
+ *
+ * A tiny levelled logger with namespaced children, optional ANSI colour, and
+ * cumulative metrics for HTTP and pack-parsing activity.
+ *
+ * Output goes to a configurable sink (defaults to `console.error`). Levels
+ * stack: `info ⊂ debug ⊂ trace`. The library never logs above `info` unless
+ * `--verbose` / `--debug` is set on the CLI or the caller passes its own
+ * configured logger.
+ */
+import * as dntShim from "./_dnt.shims.js";
+/** Numeric ranking — higher means "more verbose". Used for level comparison. */
+const LEVEL_RANK = {
+    silent: 0,
+    info: 1,
+    debug: 2,
+    trace: 3,
+};
+/** ANSI escape codes. Disabled when stderr isn't a TTY or `NO_COLOR` is set. */
+const ANSI = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    gray: "\x1b[90m",
+};
+/** Per-level colour token. `silent` has none — it never emits. */
+const LEVEL_COLOR = {
+    info: ANSI.cyan,
+    debug: ANSI.blue,
+    trace: ANSI.gray,
+};
+function emptyMetrics() {
+    return {
+        httpRequests: 0,
+        httpBytesIn: 0,
+        httpBytesOut: 0,
+        httpDurationMs: 0,
+        packObjects: 0,
+        packBytes: 0,
+        packParseMs: 0,
+        byType: { commit: 0, tree: 0, blob: 0, tag: 0 },
+    };
+}
+function detectColor() {
+    try {
+        if (dntShim.Deno.env.get("NO_COLOR"))
+            return false;
+        return dntShim.Deno.stderr.isTerminal();
+    }
+    catch {
+        return false;
+    }
+}
+/** Pretty-print a byte count with binary-prefix units. */
+export function formatBytes(n) {
+    if (n < 1024)
+        return `${n}B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)}KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(2)}MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)}GB`;
+}
+/** Pretty-print a millisecond duration, scaling unit to magnitude. */
+export function formatDuration(ms) {
+    if (ms < 1)
+        return `${ms.toFixed(2)}ms`;
+    if (ms < 1000)
+        return `${ms.toFixed(1)}ms`;
+    if (ms < 60_000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    const min = Math.floor(ms / 60_000);
+    const s = ((ms % 60_000) / 1000).toFixed(1);
+    return `${min}m${s}s`;
+}
+/**
+ * Levelled logger with namespaced children and shared metrics.
+ *
+ * Children share their parent's `metrics` object so that any `recordHttp` /
+ * `recordPack` call anywhere in the tree contributes to the same totals
+ * surfaced by {@link Logger.summary}.
+ */
+export class Logger {
+    level;
+    metrics;
+    sink;
+    namespace;
+    collect;
+    color;
+    timestamps;
+    epoch;
+    constructor(options = {}, namespace = "") {
+        this.level = options.level ?? "silent";
+        this.sink = options.sink ?? ((line) => console.error(line));
+        this.collect = options.collectMetrics ?? true;
+        this.namespace = namespace;
+        this.color = options.color ?? detectColor();
+        this.timestamps = options.timestamps ?? true;
+        this.metrics = emptyMetrics();
+        this.epoch = performance.now();
+    }
+    /** Spawn a logger that prefixes its messages with `parent.namespace + "." + namespace`. */
+    child(namespace) {
+        const ns = this.namespace ? `${this.namespace}.${namespace}` : namespace;
+        const c = new Logger({
+            level: this.level,
+            sink: this.sink,
+            collectMetrics: this.collect,
+            color: this.color,
+            timestamps: this.timestamps,
+        }, ns);
+        c.metrics = this.metrics;
+        c.epoch = this.epoch;
+        return c;
+    }
+    enabled(level) {
+        return LEVEL_RANK[this.level] >= LEVEL_RANK[level];
+    }
+    paint(s, color) {
+        return this.color ? `${color}${s}${ANSI.reset}` : s;
+    }
+    emit(level, message) {
+        if (!this.enabled(level))
+            return;
+        const parts = [];
+        if (this.timestamps) {
+            const elapsed = performance.now() - this.epoch;
+            parts.push(this.paint(`+${formatDuration(elapsed).padStart(7)}`, ANSI.gray));
+        }
+        parts.push(this.paint(level.padEnd(5), LEVEL_COLOR[level]));
+        if (this.namespace)
+            parts.push(this.paint(this.namespace.padEnd(16), ANSI.dim));
+        parts.push(message);
+        this.sink(parts.join(" "));
+    }
+    /** Emit at `info`. No-op if level is `silent`. */
+    info(message) {
+        this.emit("info", message);
+    }
+    /** Emit at `debug`. No-op unless level ≥ `debug`. */
+    debug(message) {
+        this.emit("debug", message);
+    }
+    /** Emit at `trace`. No-op unless level is `trace`. */
+    trace(message) {
+        this.emit("trace", message);
+    }
+    /** Time an async op; emits at `level` with duration. */
+    async time(level, label, fn) {
+        if (!this.enabled(level))
+            return await fn();
+        const start = performance.now();
+        try {
+            return await fn();
+        }
+        finally {
+            this.emit(level, `${label} ${this.paint(formatDuration(performance.now() - start), ANSI.yellow)}`);
+        }
+    }
+    /** Add one HTTP request's totals to {@link Logger.metrics}. */
+    recordHttp(opts) {
+        if (!this.collect)
+            return;
+        this.metrics.httpRequests++;
+        this.metrics.httpBytesIn += opts.bytesIn;
+        this.metrics.httpBytesOut += opts.bytesOut;
+        this.metrics.httpDurationMs += opts.durationMs;
+    }
+    /** Add one parsed pack's totals to {@link Logger.metrics}. */
+    recordPack(opts) {
+        if (!this.collect)
+            return;
+        this.metrics.packBytes += opts.bytes;
+        this.metrics.packParseMs += opts.durationMs;
+        for (const k of ["commit", "tree", "blob", "tag"]) {
+            this.metrics.byType[k] += opts.byType[k];
+            this.metrics.packObjects += opts.byType[k];
+        }
+    }
+    /** Render an aligned multi-line table of {@link Logger.metrics}. CLI uses this for `--stats`. */
+    summary() {
+        const m = this.metrics;
+        const bold = (s) => this.paint(s, ANSI.bold);
+        const dim = (s) => this.paint(s, ANSI.dim);
+        const num = (s) => this.paint(s, ANSI.green);
+        const rows = [
+            ["HTTP requests", num(String(m.httpRequests))],
+            ["  bytes in", num(formatBytes(m.httpBytesIn))],
+            ["  bytes out", num(formatBytes(m.httpBytesOut))],
+            ["  total time", num(formatDuration(m.httpDurationMs))],
+            [
+                "  avg / req",
+                num(m.httpRequests > 0 ? formatDuration(m.httpDurationMs / m.httpRequests) : "n/a"),
+            ],
+            ["Pack objects", num(String(m.packObjects))],
+            [
+                "  by type",
+                dim(`${m.byType.commit} commit, ${m.byType.tree} tree, ${m.byType.blob} blob, ${m.byType.tag} tag`),
+            ],
+            ["  bytes", num(formatBytes(m.packBytes))],
+            ["  parse time", num(formatDuration(m.packParseMs))],
+        ];
+        const labelW = Math.max(...rows.map(([l]) => l.length));
+        const lines = rows.map(([l, v]) => `  ${l.padEnd(labelW)}  ${v}`);
+        return [bold("── stats ──────────────────────────────"), ...lines].join("\n");
+    }
+}
+/** Shared no-op logger. Use as a default when callers don't pass one in. */
+export const NULL_LOGGER = new Logger({ level: "silent", collectMetrics: false });

package/esm/objects/commit.js

@@ -0,0 +1,47 @@
+/**
+ * @module objects-commit
+ *
+ * Decoder for the loose-commit object body.
+ *
+ * A commit is a header block followed by a blank line and a freeform message.
+ * Each header line is `<field> <value>` and only the first occurrence of any
+ * header is significant for our purposes (Git allows multiple `parent` lines
+ * for merge commits; this client deliberately keeps just the first since it
+ * only ever walks toward the root snapshot).
+ */
+import { Result } from "better-result";
+import { ObjectDecodeError } from "../errors.js";
+const decoder = new TextDecoder();
+/**
+ * Parse the body of a commit object.
+ *
+ * @param content Uncompressed commit bytes (no `commit <size>\0` header).
+ * @returns The decoded {@link CommitInfo}, or {@link ObjectDecodeError} if the
+ *   mandatory `tree` field is absent.
+ */
+export function parseCommit(content) {
+    const text = decoder.decode(content);
+    const headerEnd = text.indexOf("\n\n");
+    const header = headerEnd >= 0 ? text.slice(0, headerEnd) : text;
+    const fields = new Map();
+    for (const line of header.split("\n")) {
+        const space = line.indexOf(" ");
+        if (space <= 0 || fields.has(line.slice(0, space)))
+            continue;
+        fields.set(line.slice(0, space), line.slice(space + 1));
+    }
+    const tree = fields.get("tree");
+    if (!tree) {
+        return Result.err(new ObjectDecodeError({
+            reason: "missing-tree",
+            message: "commit missing tree field",
+            objectType: "commit",
+        }));
+    }
+    return Result.ok({
+        tree,
+        parent: fields.get("parent"),
+        author: fields.get("author"),
+        committer: fields.get("committer"),
+    });
+}

package/esm/objects/index.js

@@ -0,0 +1,2 @@
+export * from "./commit.js";
+export * from "./tree.js";

package/esm/objects/tree.js

@@ -0,0 +1,149 @@
+/**
+ * @module objects-tree
+ *
+ * Tree decoder and helpers for walking trees / resolving paths to blobs.
+ *
+ * A tree entry on disk is `<octal-mode> <name>\0<20-byte-sha>` with no length
+ * prefix; entries are concatenated. Subtrees use mode `"40000"`; everything
+ * else (regular files, executable files, symlinks, gitlinks) is treated as a
+ * leaf by {@link walkTree}.
+ */
+import { Result } from "better-result";
+import { encodeHex } from "../deps/jsr.io/@std/encoding/1.0.10/hex.js";
+import { ObjectDecodeError, PathNotFoundError } from "../errors.js";
+/** Octal mode marker for a subtree entry. */
+const TREE_MODE = "40000";
+/** ASCII space — separates mode from name. */
+const SPACE = 0x20;
+/** ASCII NUL — terminates the name field. */
+const NUL = 0x00;
+/** Raw SHA-1 width in bytes. */
+const SHA_BYTES = 20;
+const decoder = new TextDecoder();
+/**
+ * Parse a tree body into its entries, in the order they appear on disk.
+ *
+ * @param content Uncompressed tree bytes (no `tree <size>\0` header).
+ * @returns Ordered entries, or {@link ObjectDecodeError} on a malformed entry.
+ */
+export function parseTree(content) {
+    const entries = [];
+    let offset = 0;
+    while (offset < content.length) {
+        const space = content.indexOf(SPACE, offset);
+        if (space < 0) {
+            return Result.err(new ObjectDecodeError({
+                reason: "missing-mode-separator",
+                message: "tree entry missing mode separator",
+                objectType: "tree",
+            }));
+        }
+        const nul = content.indexOf(NUL, space + 1);
+        if (nul < 0 || nul + 1 + SHA_BYTES > content.length) {
+            return Result.err(new ObjectDecodeError({
+                reason: "truncated-tree-entry",
+                message: "tree entry missing name terminator or sha",
+                objectType: "tree",
+            }));
+        }
+        entries.push({
+            mode: decoder.decode(content.subarray(offset, space)),
+            name: decoder.decode(content.subarray(space + 1, nul)),
+            sha: encodeHex(content.subarray(nul + 1, nul + 1 + SHA_BYTES)),
+        });
+        offset = nul + 1 + SHA_BYTES;
+    }
+    return Result.ok(entries);
+}
+/**
+ * Recursively flatten a tree into its leaf entries.
+ *
+ * Subtrees are followed; every other mode is treated as a file and emitted
+ * with its full path joined from `pathPrefix`. Requires that every reachable
+ * tree object is already present in `objects` — typically the case after a
+ * full (unfiltered) snapshot fetch.
+ *
+ * @param pathPrefix Internal: prefix prepended to entry names while recursing.
+ */
+export function walkTree(objects, treeSha, pathPrefix = "") {
+    const object = objects.get(treeSha);
+    if (!object) {
+        return Result.err(new ObjectDecodeError({
+            reason: "missing-tree-object",
+            message: `tree object not found: ${treeSha}`,
+            objectType: "tree",
+            sha: treeSha,
+        }));
+    }
+    const entries = parseTree(object.content);
+    if (entries.isErr())
+        return Result.err(entries.error);
+    const files = [];
+    for (const entry of entries.value) {
+        const path = pathPrefix ? `${pathPrefix}/${entry.name}` : entry.name;
+        if (entry.mode === TREE_MODE) {
+            const child = walkTree(objects, entry.sha, path);
+            if (child.isErr())
+                return Result.err(child.error);
+            files.push(...child.value);
+        }
+        else {
+            files.push({ mode: entry.mode, path, sha: entry.sha });
+        }
+    }
+    return Result.ok(files);
+}
+/**
+ * Resolve a slash-separated path inside a tree to the SHA of its leaf entry
+ * (usually a blob).
+ *
+ * Intermediate components must be subtrees; the final component may be any
+ * mode (blob, exec, symlink). Leading/trailing/duplicate slashes are tolerated.
+ *
+ * @returns Leaf SHA-1, or {@link PathNotFoundError} when any component is
+ *   missing or an intermediate component is not a tree.
+ */
+export function resolvePathToBlob(objects, treeSha, path) {
+    const parts = path.split("/").filter(Boolean);
+    if (parts.length === 0) {
+        return Result.err(new PathNotFoundError({
+            path,
+            treeSha,
+            message: `path not found: ${path}`,
+        }));
+    }
+    let currentTree = treeSha;
+    for (let i = 0; i < parts.length; i++) {
+        const object = objects.get(currentTree);
+        if (!object) {
+            return Result.err(new PathNotFoundError({
+                path,
+                treeSha: currentTree,
+                message: `path not found: ${path}`,
+            }));
+        }
+        const entries = parseTree(object.content);
+        if (entries.isErr())
+            return Result.err(entries.error);
+        const entry = entries.value.find((e) => e.name === parts[i]);
+        if (!entry) {
+            return Result.err(new PathNotFoundError({
+                path,
+                treeSha: currentTree,
+                message: `path not found: ${path}`,
+            }));
+        }
+        const isLast = i === parts.length - 1;
+        if (isLast)
+            return Result.ok(entry.sha);
+        if (entry.mode !== TREE_MODE) {
+            return Result.err(new PathNotFoundError({
+                path,
+                treeSha: currentTree,
+                message: `path not found: ${path}`,
+            }));
+        }
+        currentTree = entry.sha;
+    }
+    return Result.err(new PathNotFoundError({ path, treeSha, message: `path not found: ${path}` }));
+}