@scolladon/tsgit 0.9.0

package/dist/types/chunks/repository-Cv4Y0T9t.d.cts

@@ -0,0 +1,89 @@
+import { add, branch, checkout, clone, commit, diff, fetch, init, log, merge, push, reset, revParse, rm, status, tag } from '../commands/index.cjs';
+import { createCommit, diffTrees, getRepoRoot, mergeBase, readBlob, readIndex, readObject, readTree, resolveRef, updateRef, walkCommits, walkTree, writeObject, writeSymbolicRef, writeTree } from '../primitives/index.cjs';
+import { F as FileSystem, H as HashService, C as Compressor, R as RepositoryConfig, L as Logger, P as ProgressReporter, a as Context } from './context-Ku1aP8Ie.cjs';
+import { H as HttpTransport } from './http-transport--_NdQOiw.cjs';
+
+/**
+ * Helper that strips the leading `Context` parameter from a function type so
+ * the bound version on `Repository` exposes the user-facing signature.
+ */
+type BindCtx<F> = F extends (ctx: Context, ...rest: infer A) => infer R ? (...args: A) => R : never;
+/**
+ * User-facing options passed to `openRepository`. Subset of the design's
+ * `OpenRepositoryOptions` that this Step 3 implementation honors. Every field
+ * is optional; the facade fills sensible defaults. Field-level validation runs
+ * eagerly before the Repository is returned (Phase 10 §8.1).
+ */
+interface OpenRepositoryOptions {
+    /** Working directory. Default: `process.cwd()` on Node, `'/'` on browser/memory. */
+    readonly cwd?: string;
+    /** Adapter overrides. Each is optional; missing slots fall back to runtime detection. */
+    readonly fs?: FileSystem;
+    readonly hash?: HashService;
+    readonly compressor?: Compressor;
+    readonly transport?: HttpTransport;
+    /** Repository config (auth, parallelism, SSRF allowlist, etc.). Frozen via deepFreeze. */
+    readonly config?: RepositoryConfig;
+    /** Logger for diagnostics. Wrapped to prevent mutation post-construction. */
+    readonly logger?: Logger;
+    /** Progress reporter; defaults to `noopProgress`. */
+    readonly progress?: ProgressReporter;
+    /** AbortSignal threaded into every bound method's ctx.signal. */
+    readonly signal?: AbortSignal;
+    /**
+     * Opt OUT of adapter validator wrapping for `fs` and `transport`. NEVER set
+     * with adapters whose code you do not control; a raw transport receives
+     * `config.auth` credentials with no SSRF guard.
+     */
+    readonly unsafeRawAdapters?: boolean;
+}
+/**
+ * The frozen repository handle returned by `openRepository`. Every command
+ * and primitive is bound to a Context constructed at facade-creation time;
+ * users never see Context except through `repo.ctx`.
+ */
+interface Repository {
+    readonly add: BindCtx<typeof add>;
+    readonly branch: BindCtx<typeof branch>;
+    readonly checkout: BindCtx<typeof checkout>;
+    readonly clone: BindCtx<typeof clone>;
+    readonly commit: BindCtx<typeof commit>;
+    readonly diff: BindCtx<typeof diff>;
+    readonly fetch: BindCtx<typeof fetch>;
+    readonly init: BindCtx<typeof init>;
+    readonly log: BindCtx<typeof log>;
+    readonly merge: BindCtx<typeof merge>;
+    readonly push: BindCtx<typeof push>;
+    readonly reset: BindCtx<typeof reset>;
+    readonly revParse: BindCtx<typeof revParse>;
+    readonly rm: BindCtx<typeof rm>;
+    readonly status: BindCtx<typeof status>;
+    readonly tag: BindCtx<typeof tag>;
+    readonly primitives: {
+        readonly createCommit: BindCtx<typeof createCommit>;
+        readonly diffTrees: BindCtx<typeof diffTrees>;
+        readonly getRepoRoot: BindCtx<typeof getRepoRoot>;
+        readonly mergeBase: BindCtx<typeof mergeBase>;
+        readonly readBlob: BindCtx<typeof readBlob>;
+        readonly readIndex: BindCtx<typeof readIndex>;
+        readonly readObject: BindCtx<typeof readObject>;
+        readonly readTree: BindCtx<typeof readTree>;
+        readonly resolveRef: BindCtx<typeof resolveRef>;
+        readonly updateRef: BindCtx<typeof updateRef>;
+        readonly walkCommits: BindCtx<typeof walkCommits>;
+        readonly walkTree: BindCtx<typeof walkTree>;
+        readonly writeObject: BindCtx<typeof writeObject>;
+        readonly writeSymbolicRef: BindCtx<typeof writeSymbolicRef>;
+        readonly writeTree: BindCtx<typeof writeTree>;
+    };
+    /** The frozen Context backing every binding. Exposed for advanced use. */
+    readonly ctx: Context;
+    /**
+     * Dispose the repository. Aborts `ctx.signal` synchronously, yields a
+     * macrotask, then runs `disposeAdapters`. Idempotent. After dispose
+     * resolves, every bound method throws `REPOSITORY_DISPOSED`.
+     */
+    readonly dispose: () => Promise<void>;
+}
+
+export type { OpenRepositoryOptions as O, Repository as R };

package/dist/types/commands/index.d.cts

@@ -0,0 +1,336 @@
+import { b as FilePath, a as Context, j as RefName, O as ObjectId } from '../chunks/context-Ku1aP8Ie.cjs';
+import { A as AuthorIdentity, T as TreeDiff } from '../chunks/diff-change-BwO75AgS.cjs';
+import '../chunks/http-transport--_NdQOiw.cjs';
+
+interface AddOptions {
+    readonly force?: boolean;
+    readonly all?: boolean;
+    readonly breakStaleLockMs?: number;
+}
+interface AddResult {
+    readonly added: ReadonlyArray<FilePath>;
+    readonly modified: ReadonlyArray<FilePath>;
+    readonly removed: ReadonlyArray<FilePath>;
+}
+/**
+ * Add the given pathspecs to the index. Performs:
+ * 1. Repo + bare + pending-op preflight checks.
+ * 2. Path validation for every input (no I/O on rejection).
+ * 3. Read working-tree contents → write blob → produce IndexEntry.
+ * 4. Atomically replace `.git/index` under the index lock.
+ *
+ * Bulk mode (`all: true`) is not yet implemented — this is the literal-paths
+ * happy path used by `init`/`commit` integration tests.
+ */
+declare const add: (ctx: Context, paths: ReadonlyArray<string>, opts?: AddOptions) => Promise<AddResult>;
+
+type BranchAction = {
+    readonly kind: 'list';
+} | {
+    readonly kind: 'create';
+    readonly name: string;
+    readonly startPoint?: string;
+    readonly force?: boolean;
+} | {
+    readonly kind: 'delete';
+    readonly name: string;
+    readonly force?: boolean;
+} | {
+    readonly kind: 'rename';
+    readonly from: string;
+    readonly to: string;
+    readonly force?: boolean;
+};
+interface BranchInfo {
+    readonly name: RefName;
+    readonly id: ObjectId;
+    readonly current: boolean;
+}
+type BranchResult = {
+    readonly kind: 'list';
+    readonly branches: ReadonlyArray<BranchInfo>;
+} | {
+    readonly kind: 'create';
+    readonly name: RefName;
+    readonly id: ObjectId;
+} | {
+    readonly kind: 'delete';
+    readonly name: RefName;
+} | {
+    readonly kind: 'rename';
+    readonly from: RefName;
+    readonly to: RefName;
+};
+declare const branch: (ctx: Context, action: BranchAction) => Promise<BranchResult>;
+
+interface CheckoutOptions {
+    readonly target: string;
+    readonly detach?: boolean;
+    readonly force?: boolean;
+}
+interface CheckoutResult {
+    readonly branch: RefName | undefined;
+    readonly id: ObjectId;
+    readonly detached: boolean;
+}
+declare const checkout: (ctx: Context, opts: CheckoutOptions) => Promise<CheckoutResult>;
+
+/** Pluggable DNS resolver. Returns the addresses for `host`, in order. */
+type DnsResolver = (host: string) => Promise<ReadonlyArray<string>>;
+
+interface CloneOptions {
+    readonly url: string;
+    readonly bare?: boolean;
+    readonly initialBranch?: string;
+    readonly depth?: number;
+    /** DNS resolver injected by the caller; required to enforce SSRF guards. */
+    readonly resolver?: DnsResolver;
+    readonly allowInsecure?: boolean;
+    readonly allowPrivateNetworks?: boolean;
+}
+interface CloneResult {
+    readonly path: FilePath;
+    readonly head: RefName | undefined;
+    readonly fetchedRefs: ReadonlyArray<{
+        readonly name: RefName;
+        readonly id: ObjectId;
+    }>;
+}
+declare const clone: (ctx: Context, opts: CloneOptions) => Promise<CloneResult>;
+
+interface CommitOptions {
+    readonly message: string;
+    readonly author?: AuthorIdentity;
+    readonly committer?: AuthorIdentity;
+    readonly allowEmpty?: boolean;
+    readonly allowEmptyMessage?: boolean;
+}
+interface CommitResult {
+    readonly id: ObjectId;
+    readonly tree: ObjectId;
+    readonly branch: RefName | undefined;
+    readonly parents: ReadonlyArray<ObjectId>;
+}
+/**
+ * Create a new commit from the current index. Resolves author/committer from
+ * options or `.git/config` `[user]`, writes a tree from the index, builds the
+ * commit object, and updates HEAD's target ref (or detached HEAD itself).
+ *
+ * Throws `NOTHING_TO_COMMIT` when the new tree matches the parent's tree and
+ * `allowEmpty` is not set; `EMPTY_COMMIT_MESSAGE` when the message is blank
+ * and `allowEmptyMessage` is not set.
+ */
+declare const commit: (ctx: Context, opts: CommitOptions) => Promise<CommitResult>;
+
+interface DiffOptions {
+    /** Resolve to a tree. Accepts ref name, oid, or 'HEAD'. */
+    readonly from?: string;
+    readonly to?: string;
+    readonly detectRenames?: boolean;
+}
+/**
+ * Diff two tree-like targets and return the resulting `TreeDiff`. When `from`
+ * is omitted, defaults to HEAD's tree; when `to` is omitted, defaults to
+ * `undefined` (interpreted by `diffTrees` as the empty tree).
+ */
+declare const diff: (ctx: Context, opts?: DiffOptions) => Promise<TreeDiff>;
+
+interface FetchOptions {
+    readonly remote?: string;
+    readonly refspecs?: ReadonlyArray<string>;
+    readonly prune?: boolean;
+}
+interface FetchResult {
+    readonly remote: string;
+    readonly url: string;
+    readonly updatedRefs: ReadonlyArray<{
+        readonly name: RefName;
+        readonly oldId: ObjectId | undefined;
+        readonly newId: ObjectId;
+    }>;
+}
+declare const fetch: (ctx: Context, opts?: FetchOptions) => Promise<FetchResult>;
+
+interface InitOptions {
+    readonly initialBranch?: string;
+    readonly bare?: boolean;
+}
+interface InitResult {
+    readonly path: FilePath;
+    readonly initialBranch: RefName;
+    readonly bare: boolean;
+}
+/**
+ * Initialize a fresh repository at `ctx.layout.gitDir`. Throws
+ * `ALREADY_INITIALIZED` when the target gitDir already exists; otherwise
+ * delegates to `bootstrapRepository` for the standard layout.
+ *
+ * For non-bare repos, the gitDir is `<workDir>/.git`. For bare, gitDir IS the
+ * working dir — callers must construct a Context with `bare: true` for that
+ * shape (Phase 10 facade will derive this automatically).
+ */
+declare const init: (ctx: Context, opts?: InitOptions) => Promise<InitResult>;
+
+interface LogOptions {
+    readonly from?: string;
+    readonly limit?: number;
+    readonly excluding?: ReadonlyArray<string>;
+    readonly before?: Date;
+}
+interface LogEntry {
+    readonly id: ObjectId;
+    readonly tree: ObjectId;
+    readonly parents: ReadonlyArray<ObjectId>;
+    readonly author: AuthorIdentity;
+    readonly committer: AuthorIdentity;
+    readonly message: string;
+}
+/**
+ * Walk first-parent commits starting from `from` (default: HEAD), yielding
+ * ordered `LogEntry` records. Honors `limit`, `excluding` (oid stops), and
+ * `before` (only commits with `committer.timestamp < before`).
+ */
+declare const log: (ctx: Context, opts?: LogOptions) => Promise<ReadonlyArray<LogEntry>>;
+
+interface MergeOptions {
+    readonly target: string;
+    readonly message?: string;
+    readonly fastForwardOnly?: boolean;
+    readonly noFastForward?: boolean;
+    readonly author?: AuthorIdentity;
+    readonly committer?: AuthorIdentity;
+}
+type MergeResult = {
+    readonly kind: 'up-to-date';
+    readonly id: ObjectId;
+} | {
+    readonly kind: 'fast-forward';
+    readonly id: ObjectId;
+    readonly branch: RefName;
+} | {
+    readonly kind: 'merge';
+    readonly id: ObjectId;
+    readonly branch: RefName;
+    readonly parents: ReadonlyArray<ObjectId>;
+};
+/**
+ * Merge `target` into the current HEAD branch. v1 supports:
+ * - Up-to-date detection (target is ancestor of HEAD).
+ * - Fast-forward (HEAD is ancestor of target → branch advances).
+ * - True merge for diverged histories: writes a merge commit using HEAD's tree
+ *   (callers must run `add` to incorporate target's content). Conflict
+ *   resolution and three-way tree merge land in Phase 11.
+ */
+declare const merge: (ctx: Context, opts: MergeOptions) => Promise<MergeResult>;
+
+interface PushOptions {
+    readonly remote?: string;
+    readonly refspecs?: ReadonlyArray<string>;
+    readonly force?: boolean;
+    readonly forceWithLease?: ObjectId | 'auto';
+}
+interface PushResult {
+    readonly remote: string;
+    readonly url: string;
+    readonly pushedRefs: ReadonlyArray<{
+        readonly name: RefName;
+        readonly newId: ObjectId;
+        readonly status: 'ok' | 'rejected';
+    }>;
+}
+declare const push: (ctx: Context, opts?: PushOptions) => Promise<PushResult>;
+
+type ResetMode = 'soft' | 'mixed' | 'hard';
+interface ResetOptions {
+    readonly mode: ResetMode;
+    readonly target: string;
+}
+interface ResetResult {
+    readonly mode: ResetMode;
+    readonly id: ObjectId;
+    readonly branch: RefName | undefined;
+}
+/**
+ * Reset HEAD (and optionally index/working tree) to `target`.
+ *
+ * - `soft`:  HEAD only.
+ * - `mixed`: HEAD + clears the index (Phase 9 stub: index cleared via lock release).
+ * - `hard`:  HEAD + index + working tree (working-tree mutation deferred to Phase 11).
+ *
+ * v1 implements the HEAD-update path; index/working-tree side effects beyond
+ * the HEAD move land in subsequent passes once `materializeFile`/`removeFile`
+ * orchestration is in place.
+ */
+declare const reset: (ctx: Context, opts: ResetOptions) => Promise<ResetResult>;
+
+declare const revParse: (ctx: Context, expression: string) => Promise<ObjectId>;
+
+interface RmOptions {
+    readonly cached?: boolean;
+    readonly breakStaleLockMs?: number;
+}
+interface RmResult {
+    readonly removed: ReadonlyArray<FilePath>;
+}
+/**
+ * Remove the given paths from the index (and from the working tree unless
+ * `cached: true`). Refuses when a path isn't tracked, matches `git rm`'s default.
+ */
+declare const rm: (ctx: Context, paths: ReadonlyArray<string>, opts?: RmOptions) => Promise<RmResult>;
+
+type ChangeKind = 'modified' | 'added' | 'deleted' | 'untracked';
+interface ChangeEntry {
+    readonly kind: ChangeKind;
+    readonly path: FilePath;
+}
+interface StatusResult {
+    readonly branch: RefName | undefined;
+    readonly detached: boolean;
+    readonly indexChanges: ReadonlyArray<ChangeEntry>;
+    readonly workingTreeChanges: ReadonlyArray<ChangeEntry>;
+    readonly clean: boolean;
+}
+/**
+ * Summarize the state of the working tree relative to the index, and the
+ * branch HEAD points at. Working-tree-vs-HEAD diff (Git's "staged" column)
+ * is approximated via index-vs-working-tree comparisons until Phase 11
+ * adds the stat-cache fast path.
+ *
+ * Progress reporting (Phase 10 §6.2): emits `status:scan` start before the
+ * fan-out, updates at every 100 lstat completions, and end in a finally
+ * block so the consumer always pairs start with end. `total` is undefined
+ * — design choice that prevents revealing repository size to non-trusted
+ * progress sinks.
+ */
+declare const status: (ctx: Context) => Promise<StatusResult>;
+
+type TagAction = {
+    readonly kind: 'list';
+} | {
+    readonly kind: 'create';
+    readonly name: string;
+    readonly target?: string;
+    readonly force?: boolean;
+} | {
+    readonly kind: 'delete';
+    readonly name: string;
+};
+interface TagInfo {
+    readonly name: RefName;
+    readonly id: ObjectId;
+}
+type TagResult = {
+    readonly kind: 'list';
+    readonly tags: ReadonlyArray<TagInfo>;
+} | {
+    readonly kind: 'create';
+    readonly name: RefName;
+    readonly id: ObjectId;
+} | {
+    readonly kind: 'delete';
+    readonly name: RefName;
+};
+declare const tag: (ctx: Context, action: TagAction) => Promise<TagResult>;
+
+export { add, branch, checkout, clone, commit, diff, fetch, init, log, merge, push, reset, revParse, rm, status, tag };
+export type { AddOptions, AddResult, BranchAction, BranchInfo, BranchResult, ChangeEntry, ChangeKind, CheckoutOptions, CheckoutResult, CloneOptions, CloneResult, CommitOptions, CommitResult, DiffOptions, FetchOptions, FetchResult, InitOptions, InitResult, LogEntry, LogOptions, MergeOptions, MergeResult, PushOptions, PushResult, ResetMode, ResetOptions, ResetResult, RmOptions, RmResult, StatusResult, TagAction, TagInfo, TagResult };