just-git 1.3.2 → 1.3.4

package/dist/server/index.d.ts

@@ -87,6 +87,13 @@ interface Storage {
      * `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
@@ -112,6 +119,21 @@ interface Storage {
     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`.
@@ -130,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: {
@@ -141,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 }) => {
@@ -163,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 {
@@ -264,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"). */
@@ -304,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>;
     /**
@@ -340,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.
      *
@@ -355,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
@@ -470,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.
@@ -508,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.
  *
@@ -674,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
@@ -692,7 +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>;
+declare function applyReceivePack<S = unknown>(options: ApplyReceivePackOptions<S>): Promise<RefUpdateResult>;
+/**
+ * Resolve `RefUpdateRequest[]` into fully computed `RefUpdate[]`.
+ *
+ * Reads current ref state when `oldHash` is not provided, and computes
+ * `isFF`/`isCreate`/`isDelete` for each entry.
+ */
+declare function resolveRefUpdates(repo: GitRepo, requests: RefUpdateRequest[]): Promise<RefUpdate[]>;
 
 /**
  * In-memory storage backend with multi-repo support.
@@ -723,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;
@@ -757,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;
@@ -770,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;
@@ -801,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;
@@ -814,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;
@@ -821,54 +929,35 @@ declare class BetterSqlite3Storage implements Storage {
     atomicRefUpdate<T>(repoId: string, fn: (ops: RefOps) => T): T;
 }
 
-/** Minimal database interface for PostgreSQL. Use {@link wrapPgPool} to adapt a `pg` Pool. */
-interface PgDatabase {
-    query<T = any>(text: string, values?: any[]): Promise<{
-        rows: T[];
-    }>;
-    transaction<R>(fn: (tx: PgDatabase) => Promise<R>): Promise<R>;
-}
 /** Minimal pool interface matching the `pg` package's `Pool` class. */
 interface PgPool {
-    query(text: string, values?: any[]): Promise<{
-        rows: any[];
+    query<T = any>(text: string, values?: any[]): Promise<{
+        rows: T[];
     }>;
     connect(): Promise<PgPoolClient>;
 }
-/** Minimal pool client interface matching the `pg` package's `PoolClient`. */
 interface PgPoolClient {
-    query(text: string, values?: any[]): Promise<{
-        rows: any[];
+    query<T = any>(text: string, values?: any[]): Promise<{
+        rows: T[];
     }>;
     release(): void;
 }
 /**
- * Wrap a `pg`-style pool into a `PgDatabase`.
- *
- * Handles `BEGIN`/`COMMIT`/`ROLLBACK` and client release automatically.
- *
- * ```ts
- * import { Pool } from "pg";
- * const pool = new Pool({ connectionString: "..." });
- * const db = wrapPgPool(pool);
- * ```
- */
-declare function wrapPgPool(pool: PgPool): PgDatabase;
-/**
- * PostgreSQL-backed storage.
+ * PostgreSQL-backed storage. Accepts a `pg`-style pool directly.
  *
  * Use the static `create` factory (schema setup is async):
  *
  * ```ts
  * import { Pool } from "pg";
  * const pool = new Pool({ connectionString: "..." });
- * const storage = await PgStorage.create(wrapPgPool(pool));
+ * const storage = await PgStorage.create(pool);
  * ```
  */
 declare class PgStorage implements Storage {
-    private db;
+    private pool;
     private constructor();
-    static create(db: PgDatabase): Promise<PgStorage>;
+    static create(pool: PgPool): Promise<PgStorage>;
+    private transaction;
     hasRepo(repoId: string): Promise<boolean>;
     insertRepo(repoId: string): Promise<void>;
     deleteRepo(repoId: string): Promise<void>;
@@ -881,6 +970,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>;
@@ -888,4 +979,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, BetterSqlite3Storage, type BunSqliteDatabase, BunSqliteStorage, type CreateRepoOptions, 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, 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, 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 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 };