@scolladon/tsgit 1.0.0 → 1.2.0

package/dist/types/adapters/node/index.d.ts

@@ -1,4 +1,4 @@
-import { b as Context, C as Compressor, I as InflateStreamResult, f as FileSystem, e as FileStat, D as DirEntry, F as FileHandle, H as HashService, g as Hasher } from '../../chunks/context-CTaXSPiP.js';
+import { b as Context, C as Compressor, I as InflateStreamResult, f as FileSystem, e as FileStat, D as DirEntry, F as FileHandle, H as HashService, g as Hasher, k as HookRunner, i as HookRequest, j as HookResult } from '../../chunks/context-BORy7yXb.js';
 import { b as HttpTransport, H as HttpRequest, a as HttpResponse } from '../../chunks/http-transport-DirKfK2S.js';
 
 interface NodeAdapterOptions {
@@ -9,6 +9,12 @@ interface NodeAdapterOptions {
     readonly signal?: AbortSignal;
     readonly deltaCacheMaxBytes?: number;
     readonly deltaCacheMaxEntries?: number;
+    /**
+     * Wire the git-hook runner (default true). Pass `false` to disable hooks.
+     * A wired runner spawns `.git/hooks/*` scripts that inherit the full
+     * `process.env` — disable it for repositories you do not trust.
+     */
+    readonly hooks?: boolean;
 }
 declare function createNodeContext(options: NodeAdapterOptions): Context;
 
@@ -25,15 +31,128 @@ declare class NodeCompressor implements Compressor {
     createInflateStream: () => TransformStream<Uint8Array, Uint8Array>;
 }
 
+/**
+ * Injectable surface for the Node `fs/promises` calls that `NodeFileSystem`
+ * needs. Production code uses `realFsOps`; tests inject a partial fake.
+ *
+ * Why this exists:
+ * - `vi.mock('node:fs/promises')` is file-scoped and patches the module
+ *  system. It dumps every test that "needs to mock fs" into one bucket
+ *  (the previous `node-file-system-containment.test.ts` smell).
+ * - Dependency injection at the adapter constructor makes the dependency
+ *  explicit, scoped per-instance, and cross-platform by construction —
+ *  tests don't depend on Vitest's mock machinery to swap the fs surface.
+ * - The interface is a `Pick` of `fsPromises` so production code can just
+ *  pass the real module without writing any glue. Tests pass a fake
+ *  object that satisfies the subset they exercise.
+ *
+ * @internal — not re-exported from `src/adapters/node/index.ts`.
+ */
+type FsOperations = Pick<typeof fsPromises, 'appendFile' | 'chmod' | 'lstat' | 'mkdir' | 'open' | 'readdir' | 'readFile' | 'readlink' | 'realpath' | 'rename' | 'rm' | 'rmdir' | 'stat' | 'symlink' | 'writeFile'>;
+
+/**
+ * Path-policy abstraction.
+ *
+ * Encapsulates every platform-aware path operation the Node adapter needs.
+ * Production code uses `nativePolicy` (host-matching). Tests inject
+ * `windowsPolicy` or `posixPolicy` to simulate either platform on any host,
+ * eliminating the "host vs. simulated platform" confusion that was
+ * leaking into containment / cache / errno code paths.
+ *
+ * Design notes:
+ * - `sep` is the platform separator string, used for prefix containment.
+ * - `caseInsensitive` drives `normalizeForCompare`; Windows + macOS HFS+
+ *  could share this in theory, but tsgit treats macOS as case-sensitive
+ *  per Git's `core.ignorecase` default and POSIX convention.
+ * - `rootOf` returns the volume/drive prefix produced by `path.parse`.
+ *  Examples: `/` on POSIX, `'C:\\'` on Windows, `'\\\\server\\share\\'`
+ *  for UNC paths.
+ * - The interface is *only* the subset NodeFileSystem actually needs; we
+ *  intentionally do not expose all of `nodePath`'s surface so callers
+ *  can't smuggle host-bound calls back in.
+ */
+interface PathPolicy {
+    readonly sep: '\\' | '/';
+    readonly caseInsensitive: boolean;
+    isAbsolute(path: string): boolean;
+    resolve(...parts: string[]): string;
+    join(...parts: string[]): string;
+    dirname(path: string): string;
+    basename(path: string): string;
+    /**
+     * Returns the volume/drive prefix produced by `path.parse(p).root`.
+     * POSIX: `/` for absolute, `''` for relative.
+     * Windows: `'C:\\'`, `'\\\\server\\share\\'`, or `''` for relative.
+     */
+    rootOf(path: string): string;
+    /** Case-fold on case-insensitive platforms; identity otherwise. */
+    normalizeForCompare(path: string): string;
+}
+
 declare class NodeFileSystem implements FileSystem {
     private readonly rootDir;
-    constructor(rootDir: string);
+    private readonly pathPolicy;
+    private readonly fsOps;
+    /**
+     * Memoised realpath of an *existing* parent directory, keyed by the raw
+     * (pre-realpath) parent path. Populated on every cache-miss inside
+     * `resolveForCreation` so a clone/checkout that writes N files into the
+     * same tree pays the realpath walk-up once per parent rather than once
+     * per file.
+     *
+     * Invariants:
+     * - Only EXISTING parents are cached. ENOENT walks fall back to
+     *   `realpathNearestExisting` and are never recorded.
+     * - `rmRecursive` and `rename` clear the cache, which is correct (the
+     *   parent realpath may have changed) and cheap (the cache holds at
+     *   most a handful of small strings).
+     */
+    private readonly creationParentCache;
+    /**
+     * Lazy long-name canonicalisation of `rootDir` for containment checks.
+     * Promise so concurrent first calls share one `realpath`; cleared on
+     * rejection so a transient ENOENT can be retried.
+     */
+    private canonicalRootPromise;
+    /**
+     * Memoised result of `pathPolicy.normalizeForCompare(rootDir)`. The
+     * rootDir is `readonly` for the adapter's lifetime, so a single
+     * normalisation is amortised across every containment check.
+     */
+    private normalizedRootDir;
+    /**
+     * Memoised result of `pathPolicy.normalizeForCompare(canonicalRoot)`.
+     * Tracked alongside the canonical-root promise: when the promise
+     * resolves we cache the normalised form once. The promise's
+     * rejection-clears-cache rule means a transient ENOENT also clears
+     * this field (so the next call re-normalises against the retried
+     * canonical root).
+     */
+    private normalizedCanonicalRoot;
+    constructor(rootDir: string, pathPolicy?: PathPolicy, fsOps?: FsOperations);
+    private getNormalizedRootDir;
+    /**
+     * Returns the cached normalised canonical root. Caller must have
+     * `await this.getCanonicalRoot()` immediately prior — the cache is
+     * populated by the promise's success arm and cleared on rejection, so
+     * a successful `await` guarantees the field is set.
+     *
+     * Kept synchronous (vs `async` + `await this.getCanonicalRoot()`
+     * inside) so the hot path doesn't pay an extra microtask suspension
+     * per containment check on a settled promise. The `!` is the only
+     * machine-readable form of "trust the post-await invariant"; the
+     * private `await getCanonicalRoot()` discipline at every call site is
+     * what makes it safe.
+     */
+    private getResolvedNormalizedCanonicalRoot;
+    private getCanonicalRoot;
     read: (path: string) => Promise<Uint8Array>;
     readSlice: (path: string, offset: number, length: number) => Promise<Uint8Array>;
     readUtf8: (path: string) => Promise<string>;
     write: (path: string, data: Uint8Array) => Promise<void>;
     writeExclusive: (path: string, data: Uint8Array) => Promise<void>;
     writeUtf8: (path: string, content: string) => Promise<void>;
+    appendUtf8: (path: string, content: string) => Promise<void>;
     exists: (path: string) => Promise<boolean>;
     stat: (path: string) => Promise<FileStat>;
     lstat: (path: string) => Promise<FileStat>;
@@ -46,8 +165,10 @@ declare class NodeFileSystem implements FileSystem {
     chmod: (path: string, mode: number) => Promise<void>;
     rmRecursive: (path: string) => Promise<void>;
     openWithNoFollow: (path: string, mode: "read" | "write") => Promise<FileHandle>;
+    private isSymlinkLeaf;
     private removeTree;
     private resolveForCreation;
+    private realpathForCreation;
     private resolveForMode;
     private checkContainment;
 }
@@ -62,6 +183,60 @@ declare class NodeHashService implements HashService {
     createHasher: () => Hasher;
 }
 
+/** Minimal `stat` result `NodeHookRunner` consumes. */
+interface HookStat {
+    readonly mode: number;
+    isFile(): boolean;
+}
+/** Minimal readable-stream surface — a hook's stdout / stderr. */
+interface HookReadable {
+    on(event: 'data', listener: (chunk: Buffer) => void): void;
+}
+/** Minimal writable surface — a hook's stdin. */
+interface HookWritable {
+    on(event: 'error', listener: () => void): void;
+    end(data: string): void;
+}
+/** Minimal child-process surface `NodeHookRunner` consumes. */
+interface HookChild {
+    readonly stdout: HookReadable;
+    readonly stderr: HookReadable;
+    readonly stdin: HookWritable;
+    on(event: 'error', listener: (err: Error) => void): void;
+    on(event: 'close', listener: (code: number | null) => void): void;
+    kill(): void;
+}
+/**
+ * Injectable process / filesystem surface. Production uses the Node builtins;
+ * unit tests inject a fake so every branch is exercised deterministically
+ * without spawning a real process (mirrors `FsOperations` — ADR-047).
+ */
+interface HookRunnerOps {
+    readonly stat: (path: string) => Promise<HookStat>;
+    readonly spawn: (command: string, args: ReadonlyArray<string>, options: {
+        readonly cwd: string;
+        readonly env: NodeJS.ProcessEnv;
+    }) => HookChild;
+}
+/**
+ * Node `HookRunner`: resolves `${hooksDir}/${name}` and, when it exists and is
+ * executable, spawns it via `node:child_process`. The hook inherits the
+ * process environment plus `GIT_DIR` / `GIT_INDEX_FILE`, runs with `cwd` at the
+ * working tree, and its output is captured (bounded). Never rejects for a
+ * non-zero exit.
+ */
+declare class NodeHookRunner implements HookRunner {
+    private readonly isWindows;
+    private readonly ops;
+    constructor(platform?: NodeJS.Platform, ops?: HookRunnerOps);
+    run(request: HookRequest): Promise<HookResult>;
+    /**
+     * A hook is runnable when it is a regular file that is executable. Windows
+     * has no executable bit, so any regular file qualifies (see ADR-068).
+     */
+    private isRunnable;
+}
+
 interface NodeHttpTransportOptions {
     readonly allowInsecureHttp?: boolean;
 }
@@ -71,5 +246,5 @@ declare class NodeHttpTransport implements HttpTransport {
     request: (req: HttpRequest) => Promise<HttpResponse>;
 }
 
-export { NodeCompressor, NodeFileSystem, NodeHashService, NodeHttpTransport, createNodeContext };
+export { NodeCompressor, NodeFileSystem, NodeHashService, NodeHookRunner, NodeHttpTransport, createNodeContext };
 export type { NodeAdapterOptions, NodeHttpTransportOptions };

package/dist/types/chunks/{context-CTaXSPiP.d.ts → context-BORy7yXb.d.ts}

@@ -83,20 +83,25 @@ interface FileSystem {
     /**
      * Write bytes to file. Fails with FILE_EXISTS if the file already exists (exclusive create).
      *
-     * Contract obligations (Phase 7 §14.17):
+     * Contract obligations:
      * - **Parent-directory creation:** the adapter MUST ensure parent directories exist before the
-     *   exclusive write. Equivalent to `mkdir -p dirname(path)` before `open(path, O_EXCL)`. If the
-     *   parent is removed between the implicit mkdir and the open (e.g. concurrent `git gc` prunes
-     *   the fanout), the adapter retries once: re-create the parent, re-attempt the open. On a second
-     *   ENOENT the error propagates as FILE_NOT_FOUND.
+     *  exclusive write. Equivalent to `mkdir -p dirname(path)` before `open(path, O_EXCL)`. If the
+     *  parent is removed between the implicit mkdir and the open (e.g. concurrent `git gc` prunes
+     *  the fanout), the adapter retries once: re-create the parent, re-attempt the open. On a second
+     *  ENOENT the error propagates as FILE_NOT_FOUND.
      * - **Symlink-safe ancestor check:** the adapter MUST reject writes where any ancestor directory
-     *   of `path` is a symbolic link whose resolved target is outside the containment root. This
-     *   closes the attack where an attacker replaces `objects/xx/` with a symlink pointing elsewhere.
-     *   Implementation: lstat-walk the ancestor chain, or use `openat`-style relative opens.
+     *  of `path` is a symbolic link whose resolved target is outside the containment root. This
+     *  closes the attack where an attacker replaces `objects/xx/` with a symlink pointing elsewhere.
+     *  Implementation: lstat-walk the ancestor chain, or use `openat`-style relative opens.
      */
     readonly writeExclusive: (path: string, data: Uint8Array) => Promise<void>;
     /** Write UTF-8 string to file, creating parent directories as needed. */
     readonly writeUtf8: (path: string, content: string) => Promise<void>;
+    /**
+     * Append UTF-8 to a file, creating parent directories and the file as
+     * needed. Atomic per-call for line-sized writes (relies on `O_APPEND`).
+     */
+    readonly appendUtf8: (path: string, content: string) => Promise<void>;
     /** Check if path exists. */
     readonly exists: (path: string) => Promise<boolean>;
     /** Get file/directory metadata. Throws FILE_NOT_FOUND if not found. Follows symlinks. */
@@ -140,7 +145,7 @@ interface FileSystem {
      * - Node: `fs.open(path, O_NOFOLLOW | (mode === 'write' ? O_WRONLY : O_RDONLY))`.
      * - Memory: rejects with `PERMISSION_DENIED` when the leaf is a memory symlink entry.
      * - Browser OPFS: throws `UNSUPPORTED_OPERATION` (OPFS has no symlinks; callers can
-     *   fall back to a plain `read`/`write` because the no-follow guarantee holds vacuously).
+     *  fall back to a plain `read`/`write` because the no-follow guarantee holds vacuously).
      *
      * Throws `FILE_NOT_FOUND` if the leaf does not exist (in `read` mode).
      * Throws `PERMISSION_DENIED` if the leaf is a symlink.
@@ -206,13 +211,73 @@ interface LruCache<V> {
     readonly entryCount: number;
 }
 
+/**
+ * The lifecycle hooks tsgit invokes. Extend the union to add a hook.
+ *
+ * Kept in the domain layer because both the `HookRunner` port and the
+ * `HOOK_FAILED` command error reference it — a port may import domain, but
+ * domain may never import a port.
+ */
+type HookName = 'pre-commit' | 'commit-msg' | 'pre-push';
+
+/**
+ * A single hook invocation. The port is stateless — every fact the adapter
+ * needs to resolve and spawn the hook travels in this request.
+ */
+interface HookRequest {
+    /** Hook to run. */
+    readonly name: HookName;
+    /** Absolute directory holding hook scripts — `core.hooksPath` or `${gitDir}/hooks`. */
+    readonly hooksDir: string;
+    /** Working directory for the spawned process — the working-tree root. */
+    readonly workDir: string;
+    /** Absolute `.git` directory — exported to the hook environment as `GIT_DIR`. */
+    readonly gitDir: string;
+    /** Positional arguments (e.g. the `COMMIT_EDITMSG` path for `commit-msg`). */
+    readonly args: ReadonlyArray<string>;
+    /** Bytes piped to the hook's stdin. Empty string ⇒ stdin closed empty. */
+    readonly stdin: string;
+    /** Cancels a running hook — the adapter kills the child when it aborts. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Outcome of a hook invocation.
+ *
+ * `skipped` — the hook file is absent or not executable; nothing ran. Git
+ * treats both as "no hook, proceed".
+ *
+ * `ran` — the hook ran to completion; `exitCode` is authoritative (a non-zero
+ * value is the caller's signal to abort).
+ */
+type HookResult = {
+    readonly kind: 'skipped';
+} | {
+    readonly kind: 'ran';
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+};
+/**
+ * Runs git lifecycle hooks. Optional on `Context`: when absent, hooks are
+ * inert (the browser has no runner; a host may opt out).
+ */
+interface HookRunner {
+    /**
+     * Resolve `${hooksDir}/${name}`; when it exists and is executable, spawn it
+     * with `args`, `stdin`, `cwd = workDir`, and `GIT_DIR` in the environment.
+     * Resolves with the exit code and captured output. NEVER rejects for a
+     * non-zero exit — interpreting the exit code is the caller's policy.
+     */
+    readonly run: (request: HookRequest) => Promise<HookResult>;
+}
+
 /**
  * General-purpose level-based logger consumed by the facade and any cross-cutting
  * concern (dispose, validation, lifecycle). Independent from the transport-tier
  * `Logger` in `transport/types.ts`, which is event-based and HTTP-shaped.
  *
  * The facade wraps user-supplied loggers with sanitization at construction time
- * (see Phase 10 design §8.5). Implementations should be tolerant of high call
+ * . Implementations should be tolerant of high call
  * frequency and MUST NOT throw — a throwing logger crashes nothing.
  */
 interface Logger {
@@ -225,8 +290,8 @@ interface Logger {
 declare const noopLogger: Logger;
 /**
  * Wrap a user-supplied logger so every `message` + every string value in the
- * `context` object passes through `sanitize()` (Phase 9 §4.7) before reaching
- * the sink. Per design §8.5 the facade applies this at construction time so no
+ * `context` object passes through `sanitize()` before reaching
+ * the sink. the facade applies this at construction time so no
  * downstream caller ever feeds raw control bytes to a user-controlled sink.
  *
  * Methods that the user did not supply are absent on the wrapper (preserves
@@ -237,7 +302,7 @@ declare const wrapLoggerSanitizer: (logger: Logger) => Logger;
 
 /**
  * Progress reporter shape consumed by long-running commands. The facade
- * (Phase 10) accepts a user-supplied implementation via
+ *  accepts a user-supplied implementation via
  * `OpenRepositoryOptions.progress` and plumbs it onto `Context.progress`.
  *
  * Reporters are synchronous and fire-and-forget. The facade wraps every call
@@ -260,21 +325,51 @@ interface ProgressReporter {
     readonly end: (op: string) => void;
 }
 
+/** Outcome of a promisor-remote lazy fetch (ADR-081). */
+interface PromisorFetchOutcome {
+    /**
+     * False when the repository has no promisor remote configured — the caller
+     * (`readObject`) then falls through to its normal `OBJECT_NOT_FOUND`.
+     */
+    readonly attempted: boolean;
+    /** Objects the caller asked for. */
+    readonly requested: number;
+    /** Objects that were missing locally and were fetched from the promisor. */
+    readonly fetched: number;
+}
 /**
- * Repository physical layout — where the working tree and .git directory live.
- * Renamed in Phase 10 from the previous `RepositoryConfig` (port-tier) to free that
+ * Capability for fetching objects that a partial clone omitted, from the
+ * configured promisor remote. Wired onto `Context` by `openRepository` and
+ * consumed by `readObject` on a miss — the dependency-inverting seam that lets
+ * a primitive trigger a command-tier fetch without importing upward.
+ */
+interface PromisorRemote {
+    fetch(oids: ReadonlyArray<ObjectId>): Promise<PromisorFetchOutcome>;
+}
+
+/**
+ * Repository physical layout — where the working tree and.git directory live.
+ * Renamed in from the previous `RepositoryConfig` (port-tier) to free that
  * name for the facade-tier `RepositoryConfig` shape (auth/parallelism/etc.).
  */
 interface RepositoryLayout {
     /** Absolute path to the repository root (working tree). */
     readonly workDir: string;
-    /** Absolute path to the .git directory (usually `${workDir}/.git`, but may differ for bare repos or worktrees). */
+    /** Absolute path to the.git directory (usually `${workDir}/.git`, but may differ for bare repos or worktrees). */
     readonly gitDir: string;
     /** Whether this is a bare repository. */
     readonly bare: boolean;
+    /**
+     * Home directory for `~`-expansion in config-driven paths (e.g.
+     * `core.excludesFile = ~/.config/git/ignore`). Populated by the node
+     * shim from `os.homedir()`; memory adapter accepts an option; browser
+     * leaves it `undefined`. When `undefined`, loaders that need home
+     * expansion treat the source as missing.
+     */
+    readonly homeDir?: string;
 }
 /**
- * Author / committer identity — Phase 9 §4.7 shape.
+ * Author / committer identity shape.
  */
 interface AuthorIdentity {
     readonly name: string;
@@ -292,7 +387,7 @@ type AuthStrategy = {
     readonly password: string;
 };
 /**
- * Facade-tier configuration. Phase 10 introduces this shape; it carries the
+ * Facade-tier configuration. introduces this shape; it carries the
  * auth/parallelism/SSRF/network options the facade plumbs into network-pipeline.
  * All fields are optional — primitives and commands consult only the keys they need.
  */
@@ -304,7 +399,17 @@ interface RepositoryConfig {
     readonly upstreamRef?: RefName;
     readonly allowInsecure?: boolean;
     readonly allowPrivateNetworks?: boolean;
+    /**
+     * Hard cap (bytes) on a single pack body buffered in memory by `fetchPack`.
+     * Server-controlled byte counts above this raise `PACK_TOO_LARGE`. Default
+     * 512 MiB. Lower it for hardened deployments that clone only small repos.
+     */
     readonly maxResponseBytes?: number;
+    /**
+     * Hard cap on the entry-count field declared in a received pack header.
+     * Server-controlled `uint32` values above this raise `PACK_TOO_LARGE` before
+     * `fetchPack` allocates per-entry state. Default 50_000_000.
+     */
     readonly maxObjectsPerPack?: number;
     readonly detectRenames?: boolean;
     readonly breakStaleLockMs?: number;
@@ -332,6 +437,13 @@ interface Context {
     readonly logger?: Logger;
     /** Optional abort signal for cancelling long-running operations. */
     readonly signal?: AbortSignal;
+    /** Optional hook runner. Absent ⇒ hooks are inert (browser, or opted out). */
+    readonly hooks?: HookRunner;
+    /**
+     * Optional promisor-remote capability. Populated by `openRepository`;
+     * `readObject` consults it to lazy-fetch an object a partial clone omitted.
+     */
+    readonly promisor?: PromisorRemote;
 }
 interface CreateContextParts {
     readonly fs: FileSystem;
@@ -346,9 +458,10 @@ interface CreateContextParts {
     readonly config?: RepositoryConfig;
     readonly logger?: Logger;
     readonly signal?: AbortSignal;
+    readonly hooks?: HookRunner;
 }
 /** Assemble a frozen Context from its constituent ports + layout. */
 declare function createContext(parts: CreateContextParts): Context;
 
-export { ObjectId as O, RefName as R, FilePath as d, createContext as j, noopLogger as n, wrapLoggerSanitizer as w };
-export type { AuthStrategy as A, Compressor as C, DirEntry as D, FileHandle as F, HashService as H, InflateStreamResult as I, Logger as L, ProgressReporter as P, AuthorIdentity as a, Context as b, CreateContextParts as c, FileStat as e, FileSystem as f, Hasher as g, RepositoryConfig as h, RepositoryLayout as i };
+export { ObjectId as O, RefName as R, FilePath as d, createContext as p, noopLogger as q, wrapLoggerSanitizer as w };
+export type { AuthStrategy as A, Compressor as C, DirEntry as D, FileHandle as F, HashService as H, InflateStreamResult as I, Logger as L, ProgressReporter as P, AuthorIdentity as a, Context as b, CreateContextParts as c, FileStat as e, FileSystem as f, Hasher as g, HookName as h, HookRequest as i, HookResult as j, HookRunner as k, PromisorFetchOutcome as l, PromisorRemote as m, RepositoryConfig as n, RepositoryLayout as o };