just-git 1.3.7 → 1.4.0

package/dist/server/index.d.ts

@@ -1,4 +1,5 @@
-import { i as ObjectId, _ 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 {
@@ -143,13 +144,13 @@ interface GcResult {
 }
 
 /**
- * Default session type, produced by the built-in session builder when
- * no custom `session` config is provided to `createServer`.
+ * Default auth context type, produced by the built-in auth provider when
+ * no custom `auth` config is provided to `createServer`.
  *
  * HTTP requests produce `{ transport: "http", request }`.
  * SSH sessions produce `{ transport: "ssh", username }`.
  */
-interface Session {
+interface Auth {
     transport: "http" | "ssh";
     /** Authenticated username, when available. */
     username?: string;
@@ -157,53 +158,53 @@ interface Session {
     request?: Request;
 }
 /**
- * User-provided session builder that transforms raw transport input
- * into a typed session object threaded through all hooks.
+ * Auth provider that transforms raw transport input into a typed
+ * auth context threaded through all hooks.
  *
  * Both properties are optional — provide only the transports you use.
- * TypeScript infers `S` from whichever builders are present.
+ * TypeScript infers `A` from whichever callbacks are present.
  *
- * If a transport is used at runtime but its builder is missing, the
+ * If a transport is used at runtime but its callback 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: {
+ *   auth: {
  *     http: (req) => ({
  *       userId: parseJwt(req).sub,
  *       roles: parseJwt(req).roles,
  *     }),
  *   },
  *   hooks: {
- *     preReceive: ({ session }) => {
- *       // session is { userId: string, roles: string[] } — inferred!
- *       if (!session?.roles.includes("push"))
+ *     preReceive: ({ auth }) => {
+ *       // auth is { userId: string, roles: string[] } — inferred!
+ *       if (!auth.roles.includes("push"))
  *         return { reject: true, message: "forbidden" };
  *     },
  *   },
  * });
  * ```
  */
-interface SessionBuilder<S> {
+interface AuthProvider<A> {
     /**
-     * Build a session from an HTTP request.
+     * Authenticate an HTTP request.
      *
-     * Return `S` to proceed, or return a `Response` to short-circuit
+     * Return `A` 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>;
+    http?: (request: Request) => A | Response | Promise<A | Response>;
     /**
-     * Build a session from SSH session info.
+     * Authenticate an SSH session.
      *
      * When omitted, SSH sessions receive exit code 128 with a
      * diagnostic message.
      */
-    ssh?: (info: SshSessionInfo) => S | Promise<S>;
+    ssh?: (info: SshSessionInfo) => A | Promise<A>;
 }
 /** Information about the SSH session passed to `handleSession`. */
 interface SshSessionInfo {
@@ -212,7 +213,7 @@ interface SshSessionInfo {
     /**
      * Arbitrary metadata from the SSH auth layer.
      * Stash key fingerprints, client IPs, roles, etc. here —
-     * the session builder can extract and type them.
+     * the auth provider can extract and type them.
      */
     metadata?: Record<string, unknown>;
 }
@@ -251,8 +252,8 @@ interface NodeHttpResponse {
 /**
  * Declarative push rules applied before user-provided hooks.
  *
- * These are git-level constraints that don't depend on the session.
- * For session-dependent logic (auth, logging), use hooks directly.
+ * These are git-level constraints that don't depend on the caller's
+ * identity. For auth-dependent logic, use hooks directly.
  */
 interface ServerPolicy {
     /** Branches that cannot be force-pushed to or deleted. */
@@ -264,15 +265,17 @@ interface ServerPolicy {
     /** Tags are immutable — no deletion, no overwrite once created. */
     immutableTags?: boolean;
 }
-interface GitServerConfig<S = Session> {
+interface GitServerConfig<A = Auth> {
     /**
      * Storage backend for git object and ref persistence.
      *
      * 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.
      *
@@ -293,22 +296,22 @@ interface GitServerConfig<S = Session> {
         defaultBranch?: string;
     };
     /** Server-side hooks. All optional. */
-    hooks?: ServerHooks<S>;
+    hooks?: ServerHooks<A>;
     /**
      * Declarative push policy. Rules run before user-provided hooks.
      *
-     * For session-dependent logic (auth, post-push actions), use `hooks`.
+     * For auth-dependent logic (permissions, post-push actions), use `hooks`.
      */
     policy?: ServerPolicy;
     /**
-     * Custom session builder. Provide `http`, `ssh`, or both —
+     * Auth provider. 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
+     * If a transport is used but its callback is missing, the server
      * returns an error (HTTP 501 / SSH exit 128).
      *
-     * When omitted entirely, the built-in `Session` type is used.
+     * When omitted entirely, the built-in `Auth` type is used.
      */
-    session?: SessionBuilder<S>;
+    auth?: AuthProvider<A>;
     /** Base path prefix to strip from HTTP URLs (e.g. "/git"). */
     basePath?: string;
     /**
@@ -340,13 +343,13 @@ interface GitServerConfig<S = Session> {
      * Override to integrate with your own logging, or set to `false` to
      * suppress all error output.
      */
-    onError?: false | ((err: unknown, session?: S) => void);
+    onError?: false | ((err: unknown, auth?: A) => void);
 }
 /**
  * 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"`). */
@@ -364,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>;
     /**
@@ -401,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";
@@ -425,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.
      *
@@ -488,31 +521,31 @@ interface GitServer<S = Session> {
      */
     asNetwork(baseUrl?: string): NetworkPolicy;
 }
-interface ServerHooks<S = Session> {
+interface ServerHooks<A = Auth> {
     /**
      * Called after objects are unpacked but before any refs update.
      * Receives ALL ref updates as a batch. Return a Rejection to abort
      * the entire push. Auth, branch protection, and repo-wide policy
      * belong here.
      */
-    preReceive?: (event: PreReceiveEvent<S>) => void | Rejection | Promise<void | Rejection>;
+    preReceive?: (event: PreReceiveEvent<A>) => void | Rejection | Promise<void | Rejection>;
     /**
      * Called per-ref, after preReceive passes.
      * Return a Rejection to block this specific ref update while
      * allowing others. Per-branch rules belong here.
      */
-    update?: (event: UpdateEvent<S>) => void | Rejection | Promise<void | Rejection>;
+    update?: (event: UpdateEvent<A>) => void | Rejection | Promise<void | Rejection>;
     /**
      * Called after all ref updates succeed. Cannot reject.
      * CI triggers, webhooks, notifications belong here.
      */
-    postReceive?: (event: PostReceiveEvent<S>) => void | Promise<void>;
+    postReceive?: (event: PostReceiveEvent<A>) => void | Promise<void>;
     /**
      * Called when a client wants to fetch or push (during ref advertisement).
      * Return a filtered ref list to hide branches, a Rejection to deny
      * access entirely, or void to advertise all refs.
      */
-    advertiseRefs?: (event: AdvertiseRefsEvent<S>) => RefAdvertisement[] | void | Rejection | Promise<RefAdvertisement[] | void | Rejection>;
+    advertiseRefs?: (event: AdvertiseRefsEvent<A>) => RefAdvertisement[] | void | Rejection | Promise<RefAdvertisement[] | void | Rejection>;
 }
 /** A single ref update within a push. */
 interface RefUpdate {
@@ -530,48 +563,48 @@ interface RefUpdate {
     isDelete: boolean;
 }
 /** Fired after objects are unpacked but before refs are updated. */
-interface PreReceiveEvent<S = Session> {
+interface PreReceiveEvent<A = Auth> {
     repo: GitRepo;
     /** 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;
+    /** Auth context from the transport's auth provider. Always present — hooks only fire from HTTP/SSH transport. */
+    auth: A;
 }
 /** Fired per-ref after preReceive passes. */
-interface UpdateEvent<S = Session> {
+interface UpdateEvent<A = Auth> {
     repo: GitRepo;
     /** 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;
+    /** Auth context from the transport's auth provider. Always present — hooks only fire from HTTP/SSH transport. */
+    auth: A;
 }
 /** Fired after all ref updates succeed. */
-interface PostReceiveEvent<S = Session> {
+interface PostReceiveEvent<A = Auth> {
     repo: GitRepo;
     /** 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;
+    /** Auth context from the transport's auth provider. Always present — hooks only fire from HTTP/SSH transport. */
+    auth: A;
 }
 /** Fired during ref advertisement (info/refs). */
-interface AdvertiseRefsEvent<S = Session> {
+interface AdvertiseRefsEvent<A = Auth> {
     repo: GitRepo;
     /** Resolved repo ID (the value returned by `resolve`, or the raw path when `resolve` is not set). */
     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;
+    /** Auth context from the transport's auth provider. Always present — hooks only fire from HTTP/SSH transport. */
+    auth: A;
 }
 /** 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;
@@ -592,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
@@ -608,7 +638,6 @@ interface RefUpdateResult {
  *
  * ```ts
  * const server = createServer({
- *   storage: new MemoryStorage(),
  *   autoCreate: true,
  * });
  * await server.createRepo("my-repo");
@@ -620,7 +649,7 @@ interface RefUpdateResult {
  * server.handleSession(command, channel, { username });
  * ```
  */
-declare function createServer<S = Session>(config: GitServerConfig<S>): GitServer<S>;
+declare function createServer<A = Auth>(config?: GitServerConfig<A>): GitServer;
 /**
  * Compose multiple hook sets into a single `ServerHooks` object.
  *
@@ -632,7 +661,7 @@ declare function createServer<S = Session>(config: GitServerConfig<S>): GitServe
  *   refs returned by the previous one. Short-circuits on `Rejection`.
  *   Returning void passes through unchanged.
  */
-declare function composeHooks<S = Session>(...hookSets: (ServerHooks<S> | undefined)[]): ServerHooks<S>;
+declare function composeHooks<A = Auth>(...hookSets: (ServerHooks<A> | undefined)[]): ServerHooks<A>;
 
 /**
  * Server-side Git protocol helpers.
@@ -816,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<A>(repo: GitRepo, repoId: string, service: "git-upload-pack" | "git-receive-pack", hooks: ServerHooks<A> | undefined, auth: A): Promise<AdvertiseResult | Rejection>;
 interface UploadPackOptions {
     /** Pack cache instance. When provided, full clones (no haves) are cached. */
     cache?: PackCache;
@@ -858,24 +887,32 @@ 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>;
-interface ApplyReceivePackOptions<S = unknown> {
+/**
+ * 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<A = unknown> {
     repo: GitRepo;
     repoId: string;
     ingestResult: ReceivePackResult;
-    hooks?: ServerHooks<S>;
-    /** Session info threaded through to hooks. */
-    session?: S;
+    hooks?: ServerHooks<A>;
+    auth: A;
 }
 /**
  * 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
  * `ingestResult.unpackOk` and short-circuit before calling this.
  */
-declare function applyReceivePack<S = unknown>(options: ApplyReceivePackOptions<S>): Promise<RefUpdateResult>;
+declare function applyReceivePack<A = unknown>(options: ApplyReceivePackOptions<A>): Promise<RefUpdateResult>;
 /**
  * Resolve `RefUpdateRequest[]` into fully computed `RefUpdate[]`.
  *
@@ -889,7 +926,7 @@ declare function buildV2CapabilityAdvertisementBytes(): Uint8Array;
  * 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>, session?: S): Promise<Uint8Array | Rejection>;
+declare function handleLsRefs<A>(repo: GitRepo, repoId: string, args: string[], hooks: ServerHooks<A> | undefined, auth: A): Promise<Uint8Array | Rejection>;
 /**
  * Handle a v2 `fetch` command. Parses fetch args, performs object
  * enumeration and pack building via the shared pipeline, then
@@ -904,10 +941,9 @@ declare function handleV2Fetch(repo: GitRepo, args: string[], options?: UploadPa
  * 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 {
@@ -933,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;
@@ -1082,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, type V2CommandRequest, type V2FetchRequest, type V2FetchResponseOptions, type V2LsRefsRef, advertiseRefsWithHooks, applyReceivePack, buildRefAdvertisementBytes, buildRefListBytes, buildRefListPktLines, buildV2CapabilityAdvertisement, buildV2CapabilityAdvertisementBytes, buildV2FetchResponse, buildV2LsRefsResponse, collectRefs, composeHooks, createServer, handleLsRefs, handleUploadPack, handleV2Fetch, ingestReceivePack, ingestReceivePackFromStream, parseV2CommandRequest, parseV2FetchArgs, resolveRefUpdates };
+export { type AdvertiseRefsEvent, type AdvertiseResult, type ApplyReceivePackOptions, type Auth, type AuthProvider, 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 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 };