just-git 1.1.0 → 1.1.2

package/README.md

@@ -118,6 +118,40 @@ const git = createGit({
 
 Available pre-hooks: `preCommit`, `commitMsg`, `mergeMsg`, `preMergeCommit`, `preCheckout`, `prePush`, `preFetch`, `preClone`, `prePull`, `preRebase`, `preReset`, `preClean`, `preRm`, `preCherryPick`, `preRevert`, `preStash`. Available post-hooks: `postCommit`, `postMerge`, `postCheckout`, `postPush`, `postFetch`, `postClone`, `postPull`, `postReset`, `postClean`, `postRm`, `postCherryPick`, `postRevert`, `postStash`. Low-level events: `onRefUpdate`, `onRefDelete`, `onObjectWrite`. Command-level: `beforeCommand`, `afterCommand`.
 
+## Repo module
+
+`just-git/repo` provides a high-level API for working with repositories programmatically — reading commits, diffing trees, creating objects, and merging — without going through command execution. This is what you use inside hooks (all hook payloads include `repo: GitRepo`) and anywhere else you need direct repo access.
+
+```ts
+import {
+  readCommit,
+  readFileAtCommit,
+  getChangedFiles,
+  resolveRef,
+  listBranches,
+  diffTrees,
+  flattenTree,
+  createCommit,
+  writeBlob,
+  writeTree,
+  mergeTrees,
+  checkoutTo,
+  readonlyRepo,
+} from "just-git/repo";
+
+// Read a file at a specific commit
+const content = await readFileAtCommit(repo, commitHash, "src/index.ts");
+
+// Diff two commits
+const changes = await getChangedFiles(repo, parentHash, commitHash);
+
+// Merge two branches at the tree level (no worktree needed)
+const result = await mergeTrees(repo, oursCommit, theirsCommit);
+if (!result.clean) console.log("conflicts:", result.conflicts);
+```
+
+Also re-exports `PackedObjectStore` and `FileSystemRefStore` for custom storage backends, and `readonlyRepo()` to wrap a repo so all write operations throw.
+
 ## Multi-agent collaboration
 
 Multiple agents can work on clones of the same repository in the same process, each with full VFS isolation. The `resolveRemote` option maps remote URLs to `GitRepo` instances (any object/ref store — VFS-backed, SQLite, etc.), so clone/fetch/push/pull cross VFS boundaries without any network or shared filesystem.
@@ -171,6 +205,43 @@ Concurrent pushes to the same remote are automatically serialized — if two age
 
 See [`examples/multi-agent.ts`](examples/multi-agent.ts) for a full working example with a coordinator agent that merges feature branches.
 
+## Server
+
+`just-git/server` is an embeddable Git Smart HTTP server. Any standard git client can clone, fetch, and push. Uses web-standard `Request`/`Response` — works with Bun, Hono, Cloudflare Workers, or any fetch-compatible runtime.
+
+```ts
+import { createGitServer, SqliteStorage } from "just-git/server";
+import { getChangedFiles } from "just-git/repo";
+import { Database } from "bun:sqlite";
+
+const storage = new SqliteStorage(new Database("repos.sqlite"));
+
+const server = createGitServer({
+  resolveRepo: async (repoPath) => storage.repo(repoPath),
+  hooks: {
+    preReceive: async ({ updates }) => {
+      for (const u of updates) {
+        if (u.ref === "refs/heads/main" && !u.isFF && !u.isCreate) {
+          return { reject: true, message: "no force-push to main" };
+        }
+      }
+    },
+    postReceive: async ({ repo, updates }) => {
+      for (const u of updates) {
+        const files = await getChangedFiles(repo, u.oldHash, u.newHash);
+        console.log(`${u.ref}: ${files.length} files changed`);
+      }
+    },
+  },
+});
+
+Bun.serve({ fetch: server.fetch });
+```
+
+`SqliteStorage` persists repos in SQLite without a filesystem — works with `bun:sqlite`, `better-sqlite3`, or any compatible driver. Repos backed by `SqliteStorage` work with both the server (external HTTP) and `resolveRemote` (in-process), with CAS-protected ref updates ensuring correctness regardless of write path.
+
+See [SERVER.md](SERVER.md) for the full API: hooks, `createStandardHooks`, `SqliteStorage`, configuration, and deployment patterns. See [`examples/sqlite-server.ts`](examples/sqlite-server.ts) for a runnable SQLite server and [`examples/server.ts`](examples/server.ts) for a VFS-backed server with virtual client. See [`src/platform/`](src/platform/) for a reference implementation that builds GitHub-like functionality (repos, pull requests, merge strategies) on top of these primitives.
+
 ## Command coverage
 
 See [CLI.md](CLI.md) for full usage details.
@@ -254,3 +325,18 @@ console.log(result.exitCode); // 0
 ```
 
 The `FileSystem` interface requires: `readFile`, `readFileBuffer`, `writeFile`, `exists`, `stat`, `mkdir`, `readdir`, `rm`. Optional: `lstat`, `readlink`, `symlink`.
+
+## Examples
+
+Runnable examples in [`examples/`](examples/):
+
+| File                                                            | What it demonstrates                                                 |
+| --------------------------------------------------------------- | -------------------------------------------------------------------- |
+| [`usage.ts`](examples/usage.ts)                                 | Identity, disabled commands, hooks, compose, full sandbox setup      |
+| [`multi-agent.ts`](examples/multi-agent.ts)                     | Cross-VFS collaboration with clone/push/pull between isolated agents |
+| [`server.ts`](examples/server.ts)                               | VFS-backed Smart HTTP server with virtual client clone and push      |
+| [`sqlite-server.ts`](examples/sqlite-server.ts)                 | SQLite-backed server with auto-creating repos, works with real `git` |
+| [`platform-server.ts`](examples/platform-server.ts)             | GitHub-like PR workflows: create, merge, close via REST API          |
+| [`agent-remote-workflow.ts`](examples/agent-remote-workflow.ts) | Clone from GitHub, work in sandbox, push back (requires token)       |
+
+Run any example with `bun examples/<file>`.

package/dist/{hooks-jTfqkfs1.d.ts → hooks-1dcjVqc3.d.ts}

@@ -477,4 +477,4 @@ interface GitHooks {
 }
 declare function composeGitHooks(...hookSets: (GitHooks | undefined)[]): GitHooks;
 
-export { type Commit as $, type AfterCommandEvent as A, type BeforeCommandEvent as B, type CredentialProvider as C, type PrePullEvent as D, type ExecResult as E, type FileSystem as F, type GitHooks as G, type HttpAuth as H, type IdentityOverride as I, type PrePushEvent as J, type PreRebaseEvent as K, type PreResetEvent as L, type MergeMsgEvent as M, type NetworkPolicy as N, type ObjectStore as O, type PostCheckoutEvent as P, type PreRevertEvent as Q, type RemoteResolver as R, type PreRmEvent as S, type PreStashEvent as T, type RefDeleteEvent as U, type RefEntry as V, type RefUpdateEvent as W, type Rejection as X, composeGitHooks as Y, isRejection as Z, type ObjectId as _, type RefStore as a, type Identity as a0, type TreeDiffEntry as a1, type ObjectType as a2, type RawObject as a3, type Ref as a4, type FetchFunction as b, type GitContext as c, type CommitMsgEvent as d, type FileStat as e, type GitRepo as f, type ObjectWriteEvent as g, type PostCherryPickEvent as h, type PostCleanEvent as i, type PostCloneEvent as j, type PostCommitEvent as k, type PostFetchEvent as l, type PostMergeEvent as m, type PostPullEvent as n, type PostPushEvent as o, type PostResetEvent as p, type PostRevertEvent as q, type PostRmEvent as r, type PostStashEvent as s, type PreCheckoutEvent as t, type PreCherryPickEvent as u, type PreCleanEvent as v, type PreCloneEvent as w, type PreCommitEvent as x, type PreFetchEvent as y, type PreMergeCommitEvent as z };
+export { type Identity as $, type AfterCommandEvent as A, type BeforeCommandEvent as B, type CredentialProvider as C, type PrePullEvent as D, type ExecResult as E, type FileSystem as F, type GitHooks as G, type HttpAuth as H, type IdentityOverride as I, type PrePushEvent as J, type PreRebaseEvent as K, type PreResetEvent as L, type MergeMsgEvent as M, type NetworkPolicy as N, type ObjectStore as O, type PostCheckoutEvent as P, type PreRevertEvent as Q, type RemoteResolver as R, type PreRmEvent as S, type PreStashEvent as T, type RefDeleteEvent as U, type RefEntry as V, type RefUpdateEvent as W, type Rejection as X, composeGitHooks as Y, isRejection as Z, type ObjectId as _, type RefStore as a, type TreeDiffEntry as a0, type Commit as a1, type ObjectType as a2, type RawObject as a3, type Ref as a4, type FetchFunction as b, type GitContext as c, type CommitMsgEvent as d, type FileStat as e, type GitRepo as f, type ObjectWriteEvent as g, type PostCherryPickEvent as h, type PostCleanEvent as i, type PostCloneEvent as j, type PostCommitEvent as k, type PostFetchEvent as l, type PostMergeEvent as m, type PostPullEvent as n, type PostPushEvent as o, type PostResetEvent as p, type PostRevertEvent as q, type PostRmEvent as r, type PostStashEvent as s, type PreCheckoutEvent as t, type PreCherryPickEvent as u, type PreCleanEvent as v, type PreCloneEvent as w, type PreCommitEvent as x, type PreFetchEvent as y, type PreMergeCommitEvent as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FileSystem, E as ExecResult, G as GitHooks, C as CredentialProvider, I as IdentityOverride, N as NetworkPolicy, R as RemoteResolver, O as ObjectStore, a as RefStore, b as FetchFunction, c as GitContext } from './hooks-jTfqkfs1.js';
-export { A as AfterCommandEvent, B as BeforeCommandEvent, d as CommitMsgEvent, e as FileStat, f as GitRepo, H as HttpAuth, M as MergeMsgEvent, g as ObjectWriteEvent, P as PostCheckoutEvent, h as PostCherryPickEvent, i as PostCleanEvent, j as PostCloneEvent, k as PostCommitEvent, l as PostFetchEvent, m as PostMergeEvent, n as PostPullEvent, o as PostPushEvent, p as PostResetEvent, q as PostRevertEvent, r as PostRmEvent, s as PostStashEvent, t as PreCheckoutEvent, u as PreCherryPickEvent, v as PreCleanEvent, w as PreCloneEvent, x as PreCommitEvent, y as PreFetchEvent, z as PreMergeCommitEvent, D as PrePullEvent, J as PrePushEvent, K as PreRebaseEvent, L as PreResetEvent, Q as PreRevertEvent, S as PreRmEvent, T as PreStashEvent, U as RefDeleteEvent, V as RefEntry, W as RefUpdateEvent, X as Rejection, Y as composeGitHooks, Z as isRejection } from './hooks-jTfqkfs1.js';
+import { F as FileSystem, E as ExecResult, G as GitHooks, C as CredentialProvider, I as IdentityOverride, N as NetworkPolicy, R as RemoteResolver, O as ObjectStore, a as RefStore, b as FetchFunction, c as GitContext } from './hooks-1dcjVqc3.js';
+export { A as AfterCommandEvent, B as BeforeCommandEvent, d as CommitMsgEvent, e as FileStat, f as GitRepo, H as HttpAuth, M as MergeMsgEvent, g as ObjectWriteEvent, P as PostCheckoutEvent, h as PostCherryPickEvent, i as PostCleanEvent, j as PostCloneEvent, k as PostCommitEvent, l as PostFetchEvent, m as PostMergeEvent, n as PostPullEvent, o as PostPushEvent, p as PostResetEvent, q as PostRevertEvent, r as PostRmEvent, s as PostStashEvent, t as PreCheckoutEvent, u as PreCherryPickEvent, v as PreCleanEvent, w as PreCloneEvent, x as PreCommitEvent, y as PreFetchEvent, z as PreMergeCommitEvent, D as PrePullEvent, J as PrePushEvent, K as PreRebaseEvent, L as PreResetEvent, Q as PreRevertEvent, S as PreRmEvent, T as PreStashEvent, U as RefDeleteEvent, V as RefEntry, W as RefUpdateEvent, X as Rejection, Y as composeGitHooks, Z as isRejection } from './hooks-1dcjVqc3.js';
 
 /** Options for subcommand execution (mirrors just-bash's CommandExecOptions). */
 interface CommandExecOptions {