just-git 1.3.1 → 1.3.3

package/dist/server/index.d.ts

@@ -1,62 +1,139 @@
-import { a3 as RawObject, a5 as Ref, f as GitRepo, X as Rejection, N as NetworkPolicy } from '../hooks-BtbyLyYE.js';
+import { _ as RawObject, $ as Ref, g as GitRepo, a3 as Rejection, N as NetworkPolicy } from '../hooks-t3k-y0u_.js';
 
+/**
+ * A value that may be synchronous or asynchronous.
+ *
+ * Storage methods use this return type so that sync backends (e.g. SQLite)
+ * can avoid unnecessary `async`/`await` overhead while async backends
+ * (e.g. PostgreSQL) return promises naturally.
+ */
 type MaybeAsync<T> = T | Promise<T>;
-/** Options for {@link StorageAdapter.createRepo}. */
+/** Options for creating a new repo via `GitServer.createRepo`. */
 interface CreateRepoOptions {
     /** Name of the default branch (default: `"main"`). Used for HEAD initialization. */
     defaultBranch?: string;
 }
-/** Unresolved ref entry as stored by the storage backend. */
+/**
+ * A ref entry as stored by the storage backend, without symref resolution.
+ *
+ * Symbolic refs (like HEAD → refs/heads/main) are returned as-is — the
+ * adapter layer handles resolution. Storage backends should store and
+ * return the exact {@link Ref} value that was written via `putRef`.
+ */
 interface RawRefEntry {
+    /** Full ref name, e.g. `"HEAD"` or `"refs/heads/main"`. */
     name: string;
+    /** The ref value — either a direct hash or a symbolic pointer. */
     ref: Ref;
 }
 /**
- * Ref operations available inside an {@link Storage.atomicRefUpdate} callback.
- * The storage backend provides isolation; the shared adapter runs git-aware CAS logic inside.
+ * Ref operations available inside a {@link Storage.atomicRefUpdate} callback.
+ *
+ * The storage backend wraps the callback in a transaction (or lock), and the
+ * adapter layer uses these operations to implement compare-and-swap with
+ * symref resolution. Implementations should route these to the same
+ * underlying store as the top-level ref methods, but within the
+ * transaction/lock scope.
  */
 interface RefOps {
+    /** Read a single ref within the transaction. */
     getRef(name: string): MaybeAsync<Ref | null>;
+    /** Write a ref within the transaction. */
     putRef(name: string, ref: Ref): MaybeAsync<void>;
+    /** Delete a ref within the transaction. */
     removeRef(name: string): MaybeAsync<void>;
 }
 /**
- * Storage backend interface. Implementations provide raw key-value
- * CRUD for objects and refs, plus an atomic ref operation primitive.
+ * Storage backend interface for multi-repo git object and ref persistence.
+ *
+ * Implementations provide raw key-value CRUD for objects and refs, plus an
+ * atomic ref operation primitive. All git-aware logic — object hashing,
+ * pack ingestion, symref resolution, compare-and-swap semantics — lives
+ * in the internal adapter and does not need to be implemented by backends.
  *
- * All git-aware logic (object hashing, pack ingestion, symref resolution,
- * CAS semantics) lives in the shared adapter built by {@link createStorageAdapter}.
+ * All methods use {@link MaybeAsync} return types: sync backends (SQLite)
+ * can return values directly, async backends (PostgreSQL) return promises.
  *
- * All methods may return synchronously or asynchronously.
+ * See `MemoryStorage` for a minimal reference implementation.
  */
 interface Storage {
+    /** Check whether a repo with this ID has been created. */
     hasRepo(repoId: string): MaybeAsync<boolean>;
+    /** Register a new repo ID. Does not need to create any initial data. */
     insertRepo(repoId: string): MaybeAsync<void>;
     /** Delete the repo record and all associated objects and refs. */
     deleteRepo(repoId: string): MaybeAsync<void>;
+    /**
+     * Read a raw git object by hash.
+     * Returns `null` when the object does not exist.
+     */
     getObject(repoId: string, hash: string): MaybeAsync<RawObject | null>;
+    /** Store a single git object. `content` is the uncompressed object body (no git header). */
     putObject(repoId: string, hash: string, type: string, content: Uint8Array): MaybeAsync<void>;
-    /** Bulk insert. Implementations should use their optimal batch strategy. */
+    /**
+     * Bulk-insert objects. Called during pack ingestion (push, fetch).
+     * Implementations should use their optimal batch strategy (e.g. a
+     * single transaction for SQL backends).
+     */
     putObjects(repoId: string, objects: ReadonlyArray<{
         hash: string;
         type: string;
         content: Uint8Array;
     }>): MaybeAsync<void>;
+    /** Check whether an object exists without reading its content. */
     hasObject(repoId: string, hash: string): MaybeAsync<boolean>;
+    /**
+     * Find all object hashes starting with `prefix` (for short-hash resolution).
+     * `prefix` is at least 4 hex characters.
+     */
     findObjectsByPrefix(repoId: string, prefix: string): MaybeAsync<string[]>;
+    /** Return all object hashes stored for a repo. */
+    listObjectHashes(repoId: string): MaybeAsync<string[]>;
+    /**
+     * Delete specific objects by hash.
+     * Returns the number of objects actually deleted.
+     */
+    deleteObjects(repoId: string, hashes: ReadonlyArray<string>): MaybeAsync<number>;
+    /**
+     * Read a single ref. Returns the stored {@link Ref} value (direct hash
+     * or symbolic pointer) without following symrefs — the adapter handles
+     * resolution.
+     */
     getRef(repoId: string, name: string): MaybeAsync<Ref | null>;
+    /** Write a ref (direct or symbolic). */
     putRef(repoId: string, name: string, ref: Ref): MaybeAsync<void>;
+    /** Delete a ref. */
     removeRef(repoId: string, name: string): MaybeAsync<void>;
-    /** Return all refs under a prefix, unresolved (symrefs not followed). */
+    /**
+     * List all refs, optionally filtered by a prefix (e.g. `"refs/heads/"`).
+     * Returns unresolved entries — symrefs are not followed.
+     */
     listRefs(repoId: string, prefix?: string): MaybeAsync<RawRefEntry[]>;
     /**
-     * Run ref operations atomically. The storage backend wraps the callback in
-     * whatever isolation mechanism it supports (transaction, lock, etc.).
-     * The shared adapter uses this for compare-and-swap with symref resolution.
+     * Run ref operations atomically.
+     *
+     * The storage backend wraps the callback in whatever isolation
+     * mechanism it supports (SQL transaction, in-memory lock, etc.).
+     * The adapter uses this for compare-and-swap with symref resolution.
      */
     atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => MaybeAsync<T>): MaybeAsync<T>;
 }
 
+/** Options for {@link gcRepo}. */
+interface GcOptions {
+    /** Report what would be deleted without actually deleting. Default: false. */
+    dryRun?: boolean;
+}
+/** Result of a {@link gcRepo} call. */
+interface GcResult {
+    /** Number of unreachable objects deleted (or that would be deleted in dry-run mode). */
+    deleted: number;
+    /** Number of reachable objects retained. */
+    retained: number;
+    /** True if GC was aborted because refs changed during the walk (concurrent modification detected). */
+    aborted?: boolean;
+}
+
 /**
  * Default session type, produced by the built-in session builder when
  * no custom `session` config is provided to `createServer`.
@@ -75,10 +152,14 @@ interface Session {
  * User-provided session builder that transforms raw transport input
  * into a typed session object threaded through all hooks.
  *
- * TypeScript infers `S` from the return types of the builder functions,
- * so hooks receive the custom type without explicit generic annotations.
+ * Both properties are optional — provide only the transports you use.
+ * TypeScript infers `S` from whichever builders are present.
+ *
+ * If a transport is used at runtime but its builder is missing, the
+ * server returns an error (HTTP 501 / SSH exit 128).
  *
  * ```ts
+ * // HTTP-only — no need to provide ssh
  * const server = createServer({
  *   storage: new BunSqliteStorage(db),
  *   session: {
@@ -86,10 +167,6 @@ interface Session {
  *       userId: parseJwt(req).sub,
  *       roles: parseJwt(req).roles,
  *     }),
- *     ssh: (info) => ({
- *       userId: info.username ?? "anonymous",
- *       roles: (info.metadata?.roles as string[]) ?? [],
- *     }),
  *   },
  *   hooks: {
  *     preReceive: ({ session }) => {
@@ -108,10 +185,17 @@ interface SessionBuilder<S> {
      * Return `S` to proceed, or return a `Response` to short-circuit
      * the request (e.g. 401 with `WWW-Authenticate` header). This is
      * the primary mechanism for HTTP auth — no separate middleware needed.
+     *
+     * When omitted, HTTP requests receive a 501 response.
+     */
+    http?: (request: Request) => S | Response | Promise<S | Response>;
+    /**
+     * Build a session from SSH session info.
+     *
+     * When omitted, SSH sessions receive exit code 128 with a
+     * diagnostic message.
      */
-    http: (request: Request) => S | Response | Promise<S | Response>;
-    /** Build a session from SSH session info. */
-    ssh: (info: SshSessionInfo) => S | Promise<S>;
+    ssh?: (info: SshSessionInfo) => S | Promise<S>;
 }
 /** Information about the SSH session passed to `handleSession`. */
 interface SshSessionInfo {
@@ -209,11 +293,12 @@ interface GitServerConfig<S = Session> {
      */
     policy?: ServerPolicy;
     /**
-     * Custom session builder. When provided, the server calls
-     * `session.http(request)` for HTTP and `session.ssh(info)` for SSH
-     * to produce the session object threaded through all hooks.
+     * Custom session builder. Provide `http`, `ssh`, or both —
+     * the server calls whichever is present for that transport.
+     * If a transport is used but its builder is missing, the server
+     * returns an error (HTTP 501 / SSH exit 128).
      *
-     * When omitted, the built-in `Session` type is used.
+     * When omitted entirely, the built-in `Session` type is used.
      */
     session?: SessionBuilder<S>;
     /** Base path prefix to strip from HTTP URLs (e.g. "/git"). */
@@ -249,7 +334,29 @@ interface GitServerConfig<S = Session> {
      */
     onError?: false | ((err: unknown, session?: S) => void);
 }
-interface GitServer {
+/**
+ * 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.
+ */
+interface RefUpdateRequest {
+    /** Full ref name (e.g. `"refs/heads/main"`, `"refs/tags/v1.0"`). */
+    ref: string;
+    /** New commit hash, or `null` to delete the ref. */
+    newHash: string | null;
+    /**
+     * Expected current hash for compare-and-swap.
+     *
+     * - `undefined` (default) — the server reads the current ref state
+     *   automatically. Still CAS-protected against concurrent updates.
+     * - `null` — assert the ref does not exist (create-only).
+     * - `string` — explicit CAS: the update fails if the ref's current
+     *   hash doesn't match.
+     */
+    oldHash?: string | null;
+}
+interface GitServer<S = Session> {
     /** Standard fetch-API handler for HTTP: (Request) => Response */
     fetch(request: Request): Promise<Response>;
     /**
@@ -285,6 +392,32 @@ interface GitServer {
      * ```
      */
     handleSession(command: string, channel: SshChannel, session?: SshSessionInfo): Promise<number>;
+    /**
+     * Update refs in-process with hook enforcement and 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`).
+     *
+     * Runs the full hook lifecycle: `preReceive` → per-ref `update` →
+     * CAS application → `postReceive`. Returns per-ref results.
+     *
+     * ```ts
+     * import { createCommit, writeBlob, writeTree } from "just-git/repo";
+     *
+     * const repo = await server.repo("my-repo");
+     * const blob = await writeBlob(repo, "content");
+     * const tree = await writeTree(repo, [{ name: "file.txt", hash: blob }]);
+     * const commit = await createCommit(repo, { tree, parents: [head], ... });
+     *
+     * await server.updateRefs("my-repo", [
+     *   { ref: "refs/heads/auto-fix", newHash: commit },
+     * ]);
+     * ```
+     *
+     * @throws If the repo does not exist or the server is shutting down.
+     */
+    updateRefs(repoId: string, refs: RefUpdateRequest[], session?: S): Promise<RefUpdateResult>;
     /**
      * Node.js `http.createServer` compatible handler.
      *
@@ -300,6 +433,19 @@ interface GitServer {
     repo(id: string): Promise<GitRepo | null>;
     /** Delete a repo and all its data. */
     deleteRepo(id: string): Promise<void>;
+    /**
+     * Remove unreachable objects from a repo's storage.
+     *
+     * Walks all objects reachable from the repo's refs, compares against
+     * the full set of stored objects, and deletes the difference.
+     *
+     * If refs change during the walk (e.g. a concurrent push completes),
+     * GC aborts and returns `{ aborted: true }` to prevent deleting
+     * newly-reachable objects. Callers can retry.
+     *
+     * @throws If the repo does not exist or the server is shutting down.
+     */
+    gc(repoId: string, options?: GcOptions): Promise<GcResult>;
     /**
      * Graceful shutdown. After calling, new HTTP requests receive 503
      * and new SSH sessions get exit 128. Resolves when all in-flight
@@ -415,6 +561,17 @@ interface RefAdvertisement {
     name: string;
     hash: string;
 }
+/** Per-ref result from a push or {@link GitServer.updateRefs} call. */
+interface RefResult {
+    ref: string;
+    ok: boolean;
+    error?: string;
+}
+/** Result of a push or {@link GitServer.updateRefs} call. */
+interface RefUpdateResult {
+    refResults: RefResult[];
+    applied: RefUpdate[];
+}
 
 /**
  * Unified Git server: Smart HTTP + SSH session handling.
@@ -453,7 +610,7 @@ interface RefAdvertisement {
  * server.handleSession(command, channel, { username });
  * ```
  */
-declare function createServer<S = Session>(config: GitServerConfig<S>): GitServer;
+declare function createServer<S = Session>(config: GitServerConfig<S>): GitServer<S>;
 /**
  * Compose multiple hook sets into a single `ServerHooks` object.
  *
@@ -619,15 +776,6 @@ interface ApplyReceivePackOptions<S = unknown> {
     /** Session info threaded through to hooks. */
     session?: S;
 }
-interface RefResult {
-    ref: string;
-    ok: boolean;
-    error?: string;
-}
-interface ApplyReceivePackResult {
-    refResults: RefResult[];
-    applied: RefUpdate[];
-}
 /**
  * Run the full receive-pack lifecycle: preReceive hook, per-ref update
  * hook with ref format validation, CAS ref application, and postReceive
@@ -637,28 +785,14 @@ interface ApplyReceivePackResult {
  * Does NOT handle unpack failures — the caller should check
  * `ingestResult.unpackOk` and short-circuit before calling this.
  */
-declare function applyReceivePack<S = unknown>(options: ApplyReceivePackOptions<S>): Promise<ApplyReceivePackResult>;
-
-/**
- * SSH protocol helpers for the unified Git server.
- *
- * Provides the pkt-line stream reader, command parser, and
- * receive-pack streaming logic used by `createServer`'s
- * `handleSession` method. Not a public entry point — see
- * `createServer` for usage.
- */
-
-type GitSshService = "git-upload-pack" | "git-receive-pack";
+declare function applyReceivePack<S = unknown>(options: ApplyReceivePackOptions<S>): Promise<RefUpdateResult>;
 /**
- * Parse a git SSH exec command into service and repo path.
+ * Resolve `RefUpdateRequest[]` into fully computed `RefUpdate[]`.
  *
- * Handles `git-upload-pack '/path'`, `git upload-pack '/path'`,
- * and unquoted variants.
+ * Reads current ref state when `oldHash` is not provided, and computes
+ * `isFF`/`isCreate`/`isDelete` for each entry.
  */
-declare function parseGitSshCommand(command: string): {
-    service: GitSshService;
-    repoPath: string;
-} | null;
+declare function resolveRefUpdates(repo: GitRepo, requests: RefUpdateRequest[]): Promise<RefUpdate[]>;
 
 /**
  * In-memory storage backend with multi-repo support.
@@ -689,6 +823,8 @@ declare class MemoryStorage implements Storage {
     }>): void;
     hasObject(repoId: string, hash: string): boolean;
     findObjectsByPrefix(repoId: string, prefix: string): string[];
+    listObjectHashes(repoId: string): string[];
+    deleteObjects(repoId: string, hashes: ReadonlyArray<string>): number;
     getRef(repoId: string, name: string): Ref | null;
     putRef(repoId: string, name: string, ref: Ref): void;
     removeRef(repoId: string, name: string): void;
@@ -723,6 +859,7 @@ declare class BunSqliteStorage implements Storage {
     private db;
     private stmts;
     private batchInsertTx;
+    private batchDeleteTx;
     constructor(db: BunSqliteDatabase);
     hasRepo(repoId: string): boolean;
     insertRepo(repoId: string): void;
@@ -736,6 +873,8 @@ declare class BunSqliteStorage implements Storage {
     }>): void;
     hasObject(repoId: string, hash: string): boolean;
     findObjectsByPrefix(repoId: string, prefix: string): string[];
+    listObjectHashes(repoId: string): string[];
+    deleteObjects(repoId: string, hashes: ReadonlyArray<string>): number;
     getRef(repoId: string, name: string): Ref | null;
     putRef(repoId: string, name: string, ref: Ref): void;
     removeRef(repoId: string, name: string): void;
@@ -767,6 +906,7 @@ declare class BetterSqlite3Storage implements Storage {
     private db;
     private stmts;
     private batchInsertTx;
+    private batchDeleteTx;
     constructor(db: BetterSqlite3Database);
     hasRepo(repoId: string): boolean;
     insertRepo(repoId: string): void;
@@ -780,6 +920,8 @@ declare class BetterSqlite3Storage implements Storage {
     }>): void;
     hasObject(repoId: string, hash: string): boolean;
     findObjectsByPrefix(repoId: string, prefix: string): string[];
+    listObjectHashes(repoId: string): string[];
+    deleteObjects(repoId: string, hashes: ReadonlyArray<string>): number;
     getRef(repoId: string, name: string): Ref | null;
     putRef(repoId: string, name: string, ref: Ref): void;
     removeRef(repoId: string, name: string): void;
@@ -847,6 +989,8 @@ declare class PgStorage implements Storage {
     }>): Promise<void>;
     hasObject(repoId: string, hash: string): Promise<boolean>;
     findObjectsByPrefix(repoId: string, prefix: string): Promise<string[]>;
+    listObjectHashes(repoId: string): Promise<string[]>;
+    deleteObjects(repoId: string, hashes: ReadonlyArray<string>): Promise<number>;
     getRef(repoId: string, name: string): Promise<Ref | null>;
     putRef(repoId: string, name: string, ref: Ref): Promise<void>;
     removeRef(repoId: string, name: string): Promise<void>;
@@ -854,4 +998,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 ApplyReceivePackResult, type BetterSqlite3Database, type BetterSqlite3Statement, BetterSqlite3Storage, type BunSqliteDatabase, type BunSqliteStatement, BunSqliteStorage, type CreateRepoOptions, type GitServer, type GitServerConfig, type MaybeAsync, MemoryStorage, type NodeHttpRequest, type NodeHttpResponse, type PgDatabase, type PgPool, type PgPoolClient, PgStorage, type PostReceiveEvent, type PreReceiveEvent, type RawRefEntry, type ReceivePackResult, type RefAdvertisement, type RefOps, type RefResult, type RefUpdate, 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, parseGitSshCommand, wrapPgPool };
+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 PgDatabase, type PgPool, type PgPoolClient, 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, wrapPgPool };