just-git 1.3.6 → 1.3.9

package/dist/writing-CnM1ufDP.d.ts

@@ -0,0 +1,204 @@
+import { h as Identity, j as ObjectType, g as GitRepo } from './hooks-C7c_BLqp.js';
+
+/**
+ * Simplified identity for the public API. When `date` is omitted,
+ * defaults to the current time. Accepts either this form or the
+ * internal `Identity` (with `timestamp`/`timezone`) for full control.
+ */
+interface CommitAuthor {
+    name: string;
+    email: string;
+    /** Defaults to `new Date()` (current time). */
+    date?: Date;
+}
+/** Accepts either the simplified {@link CommitAuthor} or the internal `Identity` with raw timestamp/timezone. */
+type CommitIdentity = CommitAuthor | Identity;
+/** Options for {@link createCommit}. */
+interface CreateCommitOptions {
+    /** Hash of the tree object for this commit. */
+    tree: string;
+    /** Parent commit hashes (empty for root commits). */
+    parents: string[];
+    /** Author identity. Accepts `{ name, email, date? }` or full `Identity`. */
+    author: CommitIdentity;
+    /** Committer identity. Defaults to `author` when omitted. */
+    committer?: CommitIdentity;
+    message: string;
+    /**
+     * When set, advances `refs/heads/<branch>` to the new commit.
+     * If HEAD does not exist yet, it is created as a symbolic ref
+     * pointing to the branch — matching `git init` + `git commit`.
+     */
+    branch?: string;
+}
+/**
+ * Create a commit object directly in the object store.
+ * Returns the new commit's hash.
+ *
+ * When `branch` is provided, also advances the branch ref and
+ * (if HEAD is absent) initializes HEAD as a symbolic ref to it.
+ * Without `branch`, no refs are updated.
+ */
+declare function createCommit(repo: GitRepo, options: CreateCommitOptions): Promise<string>;
+/** Options for {@link createAnnotatedTag}. */
+interface CreateAnnotatedTagOptions {
+    /** Hash of the target object (usually a commit). */
+    target: string;
+    /** Tag name (written into the tag object and used for the ref). */
+    name: string;
+    /** Tagger identity. Accepts `{ name, email, date? }` or full `Identity`. */
+    tagger: CommitIdentity;
+    message: string;
+    /** Type of the target object. Defaults to `"commit"`. */
+    targetType?: ObjectType;
+}
+/**
+ * Create an annotated tag object and its ref.
+ * Returns the tag object's hash.
+ *
+ * ```ts
+ * await createAnnotatedTag(repo, {
+ *   target: commitHash,
+ *   name: "v1.0.0",
+ *   tagger: { name: "Alice", email: "alice@example.com" },
+ *   message: "Release 1.0.0",
+ * });
+ * ```
+ */
+declare function createAnnotatedTag(repo: GitRepo, options: CreateAnnotatedTagOptions): Promise<string>;
+/** Options for {@link buildCommit}. */
+interface BuildCommitOptions {
+    /**
+     * Files to add, update, or delete.
+     * - `string` values are written as UTF-8 blobs.
+     * - `Uint8Array` values are written as raw blobs.
+     * - `null` deletes the file from the tree.
+     */
+    files: Record<string, string | Uint8Array | null>;
+    message: string;
+    /** Author identity. Accepts `{ name, email, date? }` or full `Identity`. Timestamp defaults to now. */
+    author: CommitIdentity;
+    /** Committer identity. Defaults to `author` when omitted. */
+    committer?: CommitIdentity;
+    /**
+     * Branch to read the parent commit from. The new commit builds on
+     * top of this branch's tree. When omitted, creates a root commit
+     * with only the specified files.
+     */
+    branch?: string;
+}
+/** Result of {@link buildCommit}. */
+interface CommitResult {
+    /** The new commit's hash. */
+    hash: string;
+    /** The parent commit hash, or `null` for root commits. Useful as `oldHash` for CAS-protected ref updates. */
+    parentHash: string | null;
+}
+/**
+ * Create a commit from files without advancing any refs.
+ *
+ * Handles blob creation, tree construction, and parent resolution.
+ * When `branch` is provided and the branch exists, the specified
+ * files are applied on top of the existing tree (unmentioned files
+ * are preserved). When the branch doesn't exist or is omitted, a
+ * root commit is created with only the specified files.
+ *
+ * Returns both the commit hash and the parent hash. The parent hash
+ * is useful as `oldHash` for CAS-protected ref updates via
+ * `server.updateRefs()` or `server.commit()`.
+ *
+ * ```ts
+ * const { hash, parentHash } = await buildCommit(repo, {
+ *   files: { "README.md": "# Hello\n" },
+ *   message: "initial commit",
+ *   author: { name: "Alice", email: "alice@example.com" },
+ *   branch: "main",
+ * });
+ * ```
+ */
+declare function buildCommit(repo: GitRepo, options: BuildCommitOptions): Promise<CommitResult>;
+/** Options for {@link commit}. */
+interface CommitOptions {
+    /**
+     * Files to add, update, or delete.
+     * - `string` values are written as UTF-8 blobs.
+     * - `Uint8Array` values are written as raw blobs.
+     * - `null` deletes the file from the tree.
+     */
+    files: Record<string, string | Uint8Array | null>;
+    message: string;
+    /** Author identity. Accepts `{ name, email, date? }` or full `Identity`. Timestamp defaults to now. */
+    author: CommitIdentity;
+    /** Committer identity. Defaults to `author` when omitted. */
+    committer?: CommitIdentity;
+    /** Branch to commit to. Parent is auto-resolved from the current branch tip. */
+    branch: string;
+}
+/**
+ * Commit files to a branch in one call.
+ *
+ * Handles blob creation, tree construction, parent resolution, and
+ * ref advancement. When the branch already exists, the specified
+ * files are applied on top of the existing tree (unmentioned files
+ * are preserved). When the branch doesn't exist, a root commit is
+ * created with only the specified files.
+ *
+ * For server-backed repos where hook enforcement and CAS protection
+ * are needed, use `server.commit()` instead — it uses
+ * {@link buildCommit} + `server.updateRefs()` internally.
+ *
+ * ```ts
+ * await commit(repo, {
+ *   files: { "README.md": "# Hello\n", "src/index.ts": "export {};\n" },
+ *   message: "initial commit",
+ *   author: { name: "Alice", email: "alice@example.com" },
+ *   branch: "main",
+ * });
+ * ```
+ */
+declare function commit(repo: GitRepo, options: CommitOptions): Promise<string>;
+/** An entry to include in a tree built by {@link writeTree}. */
+interface TreeEntryInput {
+    /** Filename (not a path — nesting is achieved by including tree entries). */
+    name: string;
+    /** Hash of the blob or tree object. */
+    hash: string;
+    /** File mode (e.g. "100644"). Auto-detected from the object store when omitted. */
+    mode?: string;
+}
+/**
+ * Build a tree object from a flat list of entries and write it to the
+ * object store. When `mode` is omitted, the object store is consulted:
+ * tree objects get "040000", everything else gets "100644".
+ */
+declare function writeTree(repo: GitRepo, entries: TreeEntryInput[]): Promise<string>;
+/**
+ * Write a UTF-8 string as a blob to the object store.
+ * Returns the blob's hash.
+ */
+declare function writeBlob(repo: GitRepo, content: string): Promise<string>;
+/** A file to add or update in a tree via {@link updateTree}. */
+interface TreeUpdate {
+    /** Full repo-relative path (e.g. `"src/lib/foo.ts"`). */
+    path: string;
+    /** Blob hash. When `null`, the file is removed. */
+    hash: string | null;
+    /** File mode (default `"100644"`). Ignored when `hash` is `null`. */
+    mode?: string;
+}
+/**
+ * Apply path-based additions, updates, and deletions to an existing
+ * tree, handling nested subtree construction automatically.
+ * Returns the new root tree hash.
+ *
+ * ```ts
+ * const blob = await writeBlob(repo, "hello world\n");
+ * const newTree = await updateTree(repo, commit.tree, [
+ *   { path: "src/new-file.ts", hash: blob },
+ *   { path: "old-file.txt", hash: null },
+ * ]);
+ * ```
+ */
+declare function updateTree(repo: GitRepo, treeHash: string, updates: TreeUpdate[]): Promise<string>;
+
+export { type BuildCommitOptions as B, type CommitAuthor as C, type TreeEntryInput as T, type CommitIdentity as a, type CommitOptions as b, type CommitResult as c, type CreateAnnotatedTagOptions as d, type CreateCommitOptions as e, type TreeUpdate as f, buildCommit as g, commit as h, createAnnotatedTag as i, createCommit as j, writeTree as k, updateTree as u, writeBlob as w };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "just-git",
-	"version": "1.3.6",
+	"version": "1.3.9",
 	"description": "Pure TypeScript git implementation: virtual filesystem client and embeddable server.",
 	"keywords": [
 		"agent",