git-remote-ops 0.1.0

package/types/protocol/upload_pack.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @module upload-pack
+ *
+ * Build `git-upload-pack` request bodies (protocol v0 and v2) and demux the
+ * sideband-multiplexed response back into a raw packfile.
+ *
+ * Sideband framing: each data pkt-line is prefixed by a single byte channel
+ * marker — `1` packfile bytes, `2` human-readable progress, `3` fatal error
+ * text. The packfile itself is the concatenation of all channel-1 payloads.
+ */
+import { Result } from "better-result";
+import { PktLineError, UploadPackError } from "../errors.js";
+import type { DiagnosticFn, FetchRequestOptions, SidebandData } from "../types.js";
+/**
+ * Build the POST body for `/git-upload-pack`. Dispatches to a v0 or v2 encoder
+ * based on `options.protocolVersion` (defaults to v0).
+ *
+ * @returns Encoded request bytes, or {@link PktLineError} if any inner frame
+ *   exceeds the pkt-line size cap.
+ */
+export declare function buildFetchRequest(options: FetchRequestOptions): Result<Uint8Array, PktLineError>;
+/**
+ * Demultiplex sideband-framed `git-upload-pack` response bytes into three
+ * channel-segregated streams (pack / progress / errors). All payloads from a
+ * given channel are concatenated in order.
+ *
+ * Inputs that lack a sideband framing byte are dropped — callers needing the
+ * non-sideband path should use {@link extractPack}.
+ */
+export declare function demuxSideband(body: Uint8Array): Result<SidebandData, PktLineError>;
+/**
+ * Pull the packfile bytes out of a `git-upload-pack` response.
+ *
+ * Walks pkt-lines until it finds the first non-control data line and then
+ * picks the right strategy:
+ *
+ *  1. raw `PACK` signature inline — slice from there to end-of-buffer;
+ *  2. sideband byte (1/2/3) prefix — demux and return channel 1;
+ *  3. no framed data at all — fall back to a byte-level `PACK` search.
+ *
+ * @param response Raw HTTP response body.
+ * @param diagnostic Optional sink for non-fatal server stderr (channel 3).
+ */
+export declare function extractPack(response: Uint8Array, diagnostic?: DiagnosticFn): Result<Uint8Array, PktLineError | UploadPackError>;
+//# sourceMappingURL=upload_pack.d.ts.map

package/types/protocol/upload_pack.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upload_pack.d.ts","sourceRoot":"","sources":["../../src/protocol/upload_pack.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AA0CnF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,GAC3B,MAAM,CAAC,UAAU,EAAE,YAAY,CAAC,CAIlC;AA6ED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,CA4BlF;AA4BD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,UAAU,EACpB,UAAU,CAAC,EAAE,YAAY,GACxB,MAAM,CAAC,UAAU,EAAE,YAAY,GAAG,eAAe,CAAC,CAgCpD"}

package/types/transport.d.ts

@@ -0,0 +1,24 @@
+import { Result } from "better-result";
+import { TransportError } from "./errors.js";
+import { Logger } from "./logger.js";
+import type { GitProtocolOptions, HttpTransportResponse } from "./types.js";
+/** Per-request transport context: protocol version + optional logger. */
+export interface TransportContext extends GitProtocolOptions {
+    logger?: Logger;
+}
+/**
+ * Issue a smart-HTTP GET to `${url}${path}`. Used to fetch the ref/capability
+ * advertisement. When `protocolVersion === 2`, sends `Git-Protocol: version=2`
+ * so the server responds with a v2 capability ad instead of the legacy format.
+ */
+export declare function getSmartHttp(url: string, path: string, options?: TransportContext): Promise<Result<HttpTransportResponse, TransportError>>;
+/**
+ * POST a `git-upload-pack` request body. Sets the magic content/accept types
+ * the upload-pack service expects and forwards the response bytes as-is for
+ * the protocol layer to demux.
+ *
+ * `Connection: close` is set explicitly because some servers (notably
+ * `dumb-http-bridge` setups) hang on keep-alive.
+ */
+export declare function postUploadPack(url: string, body: Uint8Array, options?: TransportContext): Promise<Result<HttpTransportResponse, TransportError>>;
+//# sourceMappingURL=transport.d.ts.map

package/types/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,MAAM,EAAe,MAAM,aAAa,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAK5E,yEAAyE;AACzE,MAAM,WAAW,gBAAiB,SAAQ,kBAAkB;IAC1D,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA2CD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,cAAc,CAAC,CAAC,CA8BxD;AAED;;;;;;;GAOG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,UAAU,EAChB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,MAAM,CAAC,qBAAqB,EAAE,cAAc,CAAC,CAAC,CA0CxD"}

package/types/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @module types
+ *
+ * Public and internal type vocabulary. Anything that crosses a module
+ * boundary lives here so dependents don't end up importing each other's
+ * implementation files just to name a shape.
+ */
+/** Git's four loose-object kinds. */
+export type GitObjectType = "commit" | "tree" | "blob" | "tag";
+/** A reconstructed object: its kind plus its uncompressed body. */
+export interface GitObject {
+    type: GitObjectType;
+    content: Uint8Array;
+}
+/** Object store keyed by hex SHA-1. The client keeps a single one of these. */
+export type GitObjectMap = Map<string, GitObject>;
+/** One entry in a tree object. `sha` is hex SHA-1. */
+export interface TreeEntry {
+    /** Octal mode string as it appears in the tree (`"100644"`, `"40000"`, …). */
+    mode: string;
+    /** Entry name — last path component only. */
+    name: string;
+    /** Hex SHA-1 of the referenced blob or subtree. */
+    sha: string;
+}
+/** The interesting headers from a commit object. */
+export interface CommitInfo {
+    /** Hex SHA-1 of the root tree. */
+    tree: string;
+    /** First parent only; merge commits' additional parents are dropped. */
+    parent?: string;
+    /** Raw `author` line (name, email, timestamp), unparsed. */
+    author?: string;
+    /** Raw `committer` line, unparsed. */
+    committer?: string;
+}
+/** Knobs accepted by {@link RemoteGit.fetchCommit} and friends. */
+export interface FetchCommitOptions {
+    /** Shallow-clone depth. Server must advertise `shallow`; otherwise ignored. */
+    depth?: number;
+    /** Object filter spec (`"blob:none"`, `"tree:0"`, …). Ignored if unsupported. */
+    filter?: string;
+    /**
+     * When true, the parser keeps every object in the pack instead of bailing
+     * out as soon as the requested commit is materialized. Required by
+     * snapshot-style operations that walk into the commit's tree.
+     */
+    parseFull?: boolean;
+}
+/** Cached server capability profile, populated by `discover()` + `probe()`. */
+export interface ServerProfile {
+    url: string;
+    refs: Map<string, string>;
+    advertisedCaps: Set<string>;
+    /** 0 = legacy/v1, 2 = protocol v2. */
+    protocolVersion: 0 | 2;
+    /** Filter probe result for `blob:none` (set by {@link RemoteGit.probe}). */
+    supportsFilterBlobNone: boolean;
+    /** Filter probe result for `tree:0`. */
+    supportsFilterTree0: boolean;
+    /** Whether `shallow` appeared in the advertisement. */
+    supportsShallow: boolean;
+    /** Set to `true` after a successful probe so we don't re-run probes. */
+    probed: boolean;
+}
+/** Constructor options for {@link RemoteGit}. */
+export interface RemoteGitOptions {
+    /** Optional callback for low-level diagnostic strings (e.g. server stderr). */
+    diagnostic?: DiagnosticFn;
+    /** Inject a configured {@link Logger}; otherwise one is built from `diagnostic`. */
+    logger?: import("./logger.js").Logger;
+}
+/** Sink for free-form diagnostic strings. */
+export type DiagnosticFn = (message: string) => void;
+/** One decoded pkt-line. `payload === null` marks a flush/delim/response-end. */
+export interface PktLine {
+    /** Byte offset of the byte just after this frame. */
+    offset: number;
+    /** Payload bytes (subarray view into the source buffer), or `null` for control. */
+    payload: Uint8Array | null;
+}
+/** Generic `value + cursor advance` carrier returned by streaming readers. */
+export interface ReadResult<T> {
+    value: T;
+    offset: number;
+}
+/** One decoded pack object header. `type` is a pack type code, not a string. */
+export interface PackObjectHeader {
+    type: number;
+    size: number;
+    offset: number;
+}
+/** Output of {@link parseRefAdvertisement}. */
+export interface ParsedRefAdvertisement {
+    refs: Map<string, string>;
+    capabilities: Set<string>;
+}
+/** Channel-segregated outputs from sideband demultiplexing. */
+export interface SidebandData {
+    pack: Uint8Array;
+    progress: Uint8Array;
+    errors: Uint8Array;
+}
+/** Inputs to {@link buildFetchRequest}. */
+export interface FetchRequestOptions {
+    wants: string[];
+    caps: string[];
+    depth?: number;
+    filterSpec?: string;
+    protocolVersion?: 0 | 2;
+}
+/** What the transport layer returns to the protocol layer. */
+export interface HttpTransportResponse {
+    body: Uint8Array;
+    status: number;
+}
+/** Mixed into transport options; controls the `Git-Protocol` header. */
+export interface GitProtocolOptions {
+    protocolVersion?: 0 | 2;
+}
+//# sourceMappingURL=types.d.ts.map

package/types/types.d.ts.map

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