just-git 1.3.6 → 1.3.9

package/dist/server/index.d.ts

@@ -1,4 +1,13 @@
-import { _ as RawObject, $ as Ref, g as GitRepo, a3 as Rejection, N as NetworkPolicy } from '../hooks-DNBNCTgb.js';
+import { i as ObjectId, W as RawObject, X as Ref, g as GitRepo, $ as Rejection, N as NetworkPolicy } from '../hooks-C7c_BLqp.js';
+import { b as CommitOptions } from '../writing-CnM1ufDP.js';
+
+/** Shallow boundary delta: what to add/remove from `.git/shallow`. */
+interface ShallowUpdate {
+    /** Commits to add to the shallow boundary. */
+    shallow: ObjectId[];
+    /** Commits to remove from the shallow boundary (now have full parents). */
+    unshallow: ObjectId[];
+}
 
 /**
  * A value that may be synchronous or asynchronous.
@@ -263,8 +272,10 @@ interface GitServerConfig<S = Session> {
      * The server calls `createStorageAdapter(storage)` internally to build the
      * git-aware adapter. Users provide the storage backend; they never see
      * the `StorageAdapter` interface.
+     *
+     * Defaults to {@link MemoryStorage} when omitted.
      */
-    storage: Storage;
+    storage?: Storage;
     /**
      * Map a request path to a repo ID.
      *
@@ -337,8 +348,8 @@ interface GitServerConfig<S = Session> {
 /**
  * A ref update request for {@link GitServer.updateRefs}.
  *
- * In-process equivalent of a push command — updates a ref with CAS
- * protection and hook enforcement, without transport overhead.
+ * In-process ref update with CAS protection. Objects must already
+ * exist in the repo's object store.
  */
 interface RefUpdateRequest {
     /** Full ref name (e.g. `"refs/heads/main"`, `"refs/tags/v1.0"`). */
@@ -356,7 +367,7 @@ interface RefUpdateRequest {
      */
     oldHash?: string | null;
 }
-interface GitServer<S = Session> {
+interface GitServer {
     /** Standard fetch-API handler for HTTP: (Request) => Response */
     fetch(request: Request): Promise<Response>;
     /**
@@ -393,14 +404,15 @@ interface GitServer<S = Session> {
      */
     handleSession(command: string, channel: SshChannel, session?: SshSessionInfo): Promise<number>;
     /**
-     * Update refs in-process with hook enforcement and CAS protection.
+     * Update refs in-process with CAS protection.
      *
-     * Equivalent to a push, but without transport overhead — no pack
-     * negotiation, no object transfer. Objects must already exist in
-     * the repo's object store (e.g. via `createCommit` from `just-git/repo`).
+     * Applies compare-and-swap ref updates without transport overhead.
+     * Does NOT fire hooks (`preReceive`, `update`, `postReceive`) —
+     * hooks are a transport boundary concern. For hook enforcement,
+     * push through {@link asNetwork} instead.
      *
-     * Runs the full hook lifecycle: `preReceive` → per-ref `update` →
-     * CAS application → `postReceive`. Returns per-ref results.
+     * Objects must already exist in the repo's object store (e.g. via
+     * `createCommit` or `buildCommit` from `just-git/repo`).
      *
      * ```ts
      * import { createCommit, writeBlob, writeTree } from "just-git/repo";
@@ -417,7 +429,36 @@ interface GitServer<S = Session> {
      *
      * @throws If the repo does not exist or the server is shutting down.
      */
-    updateRefs(repoId: string, refs: RefUpdateRequest[], session?: S): Promise<RefUpdateResult>;
+    updateRefs(repoId: string, refs: RefUpdateRequest[]): Promise<RefUpdateResult>;
+    /**
+     * Commit files to a branch with CAS protection.
+     *
+     * High-level convenience that combines object creation ({@link buildCommit}
+     * from `just-git/repo`) with CAS-protected ref advancement
+     * ({@link updateRefs}). This is the recommended API for trusted
+     * server-side writes (bots, scripts, platform features).
+     *
+     * Does NOT fire hooks — hooks are a transport boundary concern.
+     * For hook enforcement (auth, policy), push through
+     * {@link asNetwork} instead.
+     *
+     * ```ts
+     * const hash = await server.commit("my-repo", {
+     *   files: { "README.md": "# Hello\n" },
+     *   message: "auto-fix",
+     *   author: { name: "Bot", email: "bot@example.com" },
+     *   branch: "main",
+     * });
+     * ```
+     *
+     * For lower-level control (e.g. constructing trees manually, multi-ref
+     * updates), use `buildCommit()` + {@link updateRefs} directly.
+     *
+     * @returns The new commit's hash.
+     * @throws If the repo does not exist, the server is shutting down,
+     *   or a concurrent write moved the branch.
+     */
+    commit(repoId: string, options: CommitOptions): Promise<string>;
     /**
      * Node.js `http.createServer` compatible handler.
      *
@@ -527,8 +568,8 @@ interface PreReceiveEvent<S = Session> {
     /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
     repoId: string;
     updates: readonly RefUpdate[];
-    /** Session info. Present for HTTP and SSH; absent for in-process pushes. */
-    session?: S;
+    /** Session built by the transport's session builder. Always present — hooks only fire from HTTP/SSH transport. */
+    session: S;
 }
 /** Fired per-ref after preReceive passes. */
 interface UpdateEvent<S = Session> {
@@ -536,8 +577,8 @@ interface UpdateEvent<S = Session> {
     /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
     repoId: string;
     update: RefUpdate;
-    /** Session info. Present for HTTP and SSH; absent for in-process pushes. */
-    session?: S;
+    /** Session built by the transport's session builder. Always present — hooks only fire from HTTP/SSH transport. */
+    session: S;
 }
 /** Fired after all ref updates succeed. */
 interface PostReceiveEvent<S = Session> {
@@ -545,8 +586,8 @@ interface PostReceiveEvent<S = Session> {
     /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
     repoId: string;
     updates: readonly RefUpdate[];
-    /** Session info. Present for HTTP and SSH; absent for in-process pushes. */
-    session?: S;
+    /** Session built by the transport's session builder. Always present — hooks only fire from HTTP/SSH transport. */
+    session: S;
 }
 /** Fired during ref advertisement (info/refs). */
 interface AdvertiseRefsEvent<S = Session> {
@@ -555,15 +596,15 @@ interface AdvertiseRefsEvent<S = Session> {
     repoId: string;
     refs: RefAdvertisement[];
     service: "git-upload-pack" | "git-receive-pack";
-    /** Session info. Present for HTTP and SSH; absent for in-process requests. */
-    session?: S;
+    /** Session built by the transport's session builder. Always present — hooks only fire from HTTP/SSH transport. */
+    session: S;
 }
 /** A ref name and hash advertised to clients during fetch/push discovery. */
 interface RefAdvertisement {
     name: string;
     hash: string;
 }
-/** Per-ref result from a push or {@link GitServer.updateRefs} call. */
+/** Per-ref result from a push, {@link GitServer.updateRefs}, or {@link GitServer.commit} call. */
 interface RefResult {
     ref: string;
     ok: boolean;
@@ -584,10 +625,7 @@ interface RefUpdateResult {
  * works with any SSH library (ssh2, etc.) through a thin adapter.
  *
  * ```ts
- * const server = createServer({
- *   storage: new MemoryStorage(),
- *   autoCreate: true,
- * });
+ * const server = createServer({ autoCreate: true });
  * await server.createRepo("my-repo");
  *
  * // HTTP
@@ -600,7 +638,6 @@ interface RefUpdateResult {
  *
  * ```ts
  * const server = createServer({
- *   storage: new MemoryStorage(),
  *   autoCreate: true,
  * });
  * await server.createRepo("my-repo");
@@ -612,7 +649,7 @@ interface RefUpdateResult {
  * server.handleSession(command, channel, { username });
  * ```
  */
-declare function createServer<S = Session>(config: GitServerConfig<S>): GitServer<S>;
+declare function createServer<S = Session>(config?: GitServerConfig<S>): GitServer;
 /**
  * Compose multiple hook sets into a single `ServerHooks` object.
  *
@@ -654,6 +691,86 @@ interface PushCommand {
     newHash: string;
     refName: string;
 }
+/**
+ * Build the v2 capability advertisement response body.
+ *
+ * Format:
+ *   PKT-LINE("version 2\n")
+ *   PKT-LINE(capability LF)
+ *   ...
+ *   flush-pkt
+ */
+declare function buildV2CapabilityAdvertisement(capabilities: string[]): Uint8Array;
+interface V2CommandRequest {
+    command: string;
+    capabilities: string[];
+    args: string[];
+}
+/**
+ * Parse a v2 command request body.
+ *
+ * Format:
+ *   PKT-LINE("command=" key LF)
+ *   *(PKT-LINE(capability LF))
+ *   delim-pkt
+ *   *(PKT-LINE(command-arg LF))
+ *   flush-pkt
+ */
+declare function parseV2CommandRequest(body: Uint8Array): V2CommandRequest;
+interface V2LsRefsRef {
+    hash: string;
+    name: string;
+    symrefTarget?: string;
+    peeledHash?: string;
+}
+/**
+ * Build the v2 ls-refs response.
+ *
+ * Format:
+ *   PKT-LINE(obj-id SP refname *(SP ref-attribute) LF)
+ *   ...
+ *   flush-pkt
+ */
+declare function buildV2LsRefsResponse(refs: V2LsRefsRef[]): Uint8Array;
+interface V2FetchRequest {
+    wants: string[];
+    haves: string[];
+    done: boolean;
+    clientShallows: string[];
+    depth?: number;
+    includeTag: boolean;
+    ofsDeltas: boolean;
+    wantRefs: string[];
+}
+/**
+ * Parse v2 fetch command args into structured request.
+ */
+declare function parseV2FetchArgs(args: string[]): V2FetchRequest;
+interface V2FetchResponseOptions {
+    commonHashes?: string[];
+    shallowInfo?: ShallowUpdate;
+    wantedRefs?: Array<{
+        hash: string;
+        name: string;
+    }>;
+}
+/**
+ * Build a v2 fetch response with section-based format.
+ *
+ * Per the spec, when commonHashes are provided the acknowledgments
+ * section is included (with "ready") followed by the packfile.
+ * When omitted (e.g. fresh clone with no haves), acks are skipped.
+ *
+ * Sections (separated by delim-pkt):
+ *   [acknowledgments section]
+ *   [shallow-info section]
+ *   [wanted-refs section]
+ *   packfile section
+ *
+ * The packfile section always uses sideband-64k.
+ * Terminated by flush-pkt.
+ */
+declare function buildV2FetchResponse(packData: Uint8Array, options?: V2FetchResponseOptions): Uint8Array;
 
 /**
  * High-level server operations.
@@ -728,7 +845,7 @@ interface AdvertiseResult {
  * Both HTTP and SSH code paths use this — the caller handles the
  * transport-specific response (HTTP 403 vs SSH exit 128).
  */
-declare function advertiseRefsWithHooks<S>(repo: GitRepo, repoId: string, service: "git-upload-pack" | "git-receive-pack", hooks?: ServerHooks<S>, session?: S): Promise<AdvertiseResult | Rejection>;
+declare function advertiseRefsWithHooks<S>(repo: GitRepo, repoId: string, service: "git-upload-pack" | "git-receive-pack", hooks: ServerHooks<S> | undefined, session: S): Promise<AdvertiseResult | Rejection>;
 interface UploadPackOptions {
     /** Pack cache instance. When provided, full clones (no haves) are cached. */
     cache?: PackCache;
@@ -770,18 +887,26 @@ declare function ingestReceivePack(repo: GitRepo, requestBody: Uint8Array): Prom
  * pkt-line commands.
  */
 declare function ingestReceivePackFromStream(repo: GitRepo, commands: PushCommand[], capabilities: string[], packStream: AsyncIterable<Uint8Array>, sawFlush?: boolean): Promise<ReceivePackResult>;
+/**
+ * Apply ref updates with CAS protection only — no hooks.
+ *
+ * Validates ref format, checks object existence, and performs
+ * `compareAndSwapRef` per ref. Used directly by in-process APIs
+ * (`server.updateRefs`, `server.commit`) and internally by
+ * {@link applyReceivePack} for the transport path.
+ */
+declare function applyCasRefUpdates(repo: GitRepo, updates: readonly RefUpdate[]): Promise<RefUpdateResult>;
 interface ApplyReceivePackOptions<S = unknown> {
     repo: GitRepo;
     repoId: string;
     ingestResult: ReceivePackResult;
     hooks?: ServerHooks<S>;
-    /** Session info threaded through to hooks. */
-    session?: S;
+    session: S;
 }
 /**
  * Run the full receive-pack lifecycle: preReceive hook, per-ref update
  * hook with ref format validation, CAS ref application, and postReceive
- * hook. Transport-agnostic — works for HTTP, SSH, or in-process pushes.
+ * hook. Transport-only — used by HTTP and SSH push handlers.
  *
  * Returns per-ref results and the list of successfully applied updates.
  * Does NOT handle unpack failures — the caller should check
@@ -795,6 +920,19 @@ declare function applyReceivePack<S = unknown>(options: ApplyReceivePackOptions<
  * `isFF`/`isCreate`/`isDelete` for each entry.
  */
 declare function resolveRefUpdates(repo: GitRepo, requests: RefUpdateRequest[]): Promise<RefUpdate[]>;
+declare function buildV2CapabilityAdvertisementBytes(): Uint8Array;
+/**
+ * Handle a v2 `ls-refs` command. Collects refs, applies hook filtering,
+ * then builds a v2 ls-refs response respecting the client's requested
+ * attributes (symrefs, peel, ref-prefix, unborn).
+ */
+declare function handleLsRefs<S>(repo: GitRepo, repoId: string, args: string[], hooks: ServerHooks<S> | undefined, session: S): Promise<Uint8Array | Rejection>;
+/**
+ * Handle a v2 `fetch` command. Parses fetch args, performs object
+ * enumeration and pack building via the shared pipeline, then
+ * builds a v2 section-based response.
+ */
+declare function handleV2Fetch(repo: GitRepo, args: string[], options?: UploadPackOptions): Promise<Uint8Array | ReadableStream<Uint8Array>>;
 
 /**
  * In-memory storage backend with multi-repo support.
@@ -803,10 +941,9 @@ declare function resolveRefUpdates(repo: GitRepo, requests: RefUpdateRequest[]):
  * Data is lost when the process exits.
  *
  * ```ts
- * const server = createServer({
- *   storage: new MemoryStorage(),
- * });
- * await server.createRepo("my-repo");
+ * // MemoryStorage is the default — these are equivalent:
+ * const server = createServer();
+ * const server2 = createServer({ storage: new MemoryStorage() });
  * ```
  */
 declare class MemoryStorage implements Storage {
@@ -832,6 +969,7 @@ declare class MemoryStorage implements Storage {
     removeRef(repoId: string, name: string): void;
     listRefs(repoId: string, prefix?: string): RawRefEntry[];
     atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => T): T;
+    /** List all created repo IDs. Convenience for tests and debugging. */
     repoIds(): string[];
     private getObjMap;
     private getRefMap;
@@ -981,4 +1119,4 @@ declare class PgStorage implements Storage {
     atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => Promise<T> | T): Promise<T>;
 }
 
-export { type AdvertiseRefsEvent, type AdvertiseResult, type ApplyReceivePackOptions, type BetterSqlite3Database, BetterSqlite3Storage, type BunSqliteDatabase, BunSqliteStorage, type CreateRepoOptions, type GcOptions, type GcResult, GitRepo, type GitServer, type GitServerConfig, type MaybeAsync, MemoryStorage, type NodeHttpRequest, type NodeHttpResponse, type PgPool, PgStorage, type PostReceiveEvent, type PreReceiveEvent, type PushCommand, RawObject, type RawRefEntry, type ReceivePackResult, Ref, type RefAdvertisement, type RefOps, type RefResult, type RefUpdate, type RefUpdateRequest, type RefUpdateResult, Rejection, type ServerHooks, type ServerPolicy, type Session, type SessionBuilder, type SshChannel, type SshSessionInfo, type Storage, type UpdateEvent, advertiseRefsWithHooks, applyReceivePack, buildRefAdvertisementBytes, buildRefListBytes, buildRefListPktLines, collectRefs, composeHooks, createServer, handleUploadPack, ingestReceivePack, ingestReceivePackFromStream, resolveRefUpdates };
+export { type AdvertiseRefsEvent, type AdvertiseResult, type ApplyReceivePackOptions, type BetterSqlite3Database, BetterSqlite3Storage, type BunSqliteDatabase, BunSqliteStorage, type CreateRepoOptions, type GcOptions, type GcResult, GitRepo, type GitServer, type GitServerConfig, type MaybeAsync, MemoryStorage, type NodeHttpRequest, type NodeHttpResponse, type PgPool, PgStorage, type PostReceiveEvent, type PreReceiveEvent, type PushCommand, RawObject, type RawRefEntry, type ReceivePackResult, Ref, type RefAdvertisement, type RefOps, type RefResult, type RefUpdate, type RefUpdateRequest, type RefUpdateResult, Rejection, type ServerHooks, type ServerPolicy, type Session, type SessionBuilder, type SshChannel, type SshSessionInfo, type Storage, type UpdateEvent, type V2CommandRequest, type V2FetchRequest, type V2FetchResponseOptions, type V2LsRefsRef, advertiseRefsWithHooks, applyCasRefUpdates, applyReceivePack, buildRefAdvertisementBytes, buildRefListBytes, buildRefListPktLines, buildV2CapabilityAdvertisement, buildV2CapabilityAdvertisementBytes, buildV2FetchResponse, buildV2LsRefsResponse, collectRefs, composeHooks, createServer, handleLsRefs, handleUploadPack, handleV2Fetch, ingestReceivePack, ingestReceivePackFromStream, parseV2CommandRequest, parseV2FetchArgs, resolveRefUpdates };