just-git 1.0.2 → 1.1.1

package/README.md

@@ -46,7 +46,8 @@ await bash.exec("git log --oneline");
 | `credentials`   | `(url) => HttpAuth \| null` callback for Smart HTTP transport auth.                                                                                                                                                                                |
 | `disabled`      | `GitCommandName[]` of subcommands to block (e.g. `["push", "rebase"]`).                                                                                                                                                                            |
 | `network`       | `{ allowed?: string[], fetch?: FetchFunction }` to restrict HTTP access and/or provide a custom `fetch`. `allowed` accepts hostnames (`"github.com"`) or URL prefixes (`"https://github.com/myorg/"`). Set to `false` to block all network access. |
-| `resolveRemote` | `(url) => GitContext \| null` callback for cross-VFS remote resolution. See [Multi-agent collaboration](#multi-agent-collaboration).                                                                                                               |
+| `hooks`         | `GitHooks` config object with named callback properties. See [Hooks](#hooks).                                                                                                                                                                      |
+| `resolveRemote` | `(url) => GitRepo \| null` callback for cross-VFS remote resolution. See [Multi-agent collaboration](#multi-agent-collaboration).                                                                                                                  |
 
 ```ts
 const git = createGit({
@@ -57,80 +58,107 @@ const git = createGit({
 });
 ```
 
-## Middleware
+## Hooks
+
+Hooks fire at specific points inside command execution. Specified as a `GitHooks` config object at construction time. All hook event payloads include `repo: GitRepo`, providing access to the [repo module helpers](src/repo/) inside hooks.
 
-Middleware wraps every `git <subcommand>` invocation. Each middleware receives a `CommandEvent` and a `next()` function. Call `next()` to proceed, or return an `ExecResult` to short-circuit. Middlewares compose in registration order (first registered = outermost). `git.use()` returns an unsubscribe function.
+Pre-hooks can reject the operation by returning `{ reject: true, message? }`. Post-hooks are observational — return value is ignored.
 
 ```ts
-// Audit log — record every command the agent runs
-git.use(async (event, next) => {
-  const result = await next();
-  auditLog.push({ command: `git ${event.command}`, exitCode: result.exitCode });
-  return result;
-});
+import { createGit, type GitHooks } from "just-git";
+import { getChangedFiles } from "just-git/repo";
 
-// Gate pushes on human approval
-git.use(async (event, next) => {
-  if (event.command === "push" && !(await getHumanApproval(event.rawArgs))) {
-    return { stdout: "", stderr: "Push blocked — awaiting approval.\n", exitCode: 1 };
-  }
-  return next();
-});
+const git = createGit({
+  hooks: {
+    // Block secrets from being committed
+    preCommit: ({ index }) => {
+      const forbidden = index.entries.filter((e) => /\.(env|pem|key)$/.test(e.path));
+      if (forbidden.length) {
+        return { reject: true, message: `Blocked: ${forbidden.map((e) => e.path).join(", ")}` };
+      }
+    },
 
-// Block commits that add large files (uses event.fs to read the worktree)
-git.use(async (event, next) => {
-  if (event.command === "add") {
-    for (const path of event.rawArgs.filter((a) => !a.startsWith("-"))) {
-      const resolved = path.startsWith("/") ? path : `${event.cwd}/${path}`;
-      const stat = await event.fs.stat(resolved).catch(() => null);
-      if (stat && stat.size > 5_000_000) {
-        return { stdout: "", stderr: `Blocked: ${path} exceeds 5 MB\n`, exitCode: 1 };
+    // Enforce conventional commit messages
+    commitMsg: (event) => {
+      if (!/^(feat|fix|docs|refactor|test|chore)(\(.+\))?:/.test(event.message)) {
+        return { reject: true, message: "Commit message must follow conventional commits format" };
+      }
+    },
+
+    // Feed agent activity to your UI — with changed file list
+    postCommit: async ({ repo, hash, branch, parents }) => {
+      const files = await getChangedFiles(repo, parents[0] ?? null, hash);
+      onAgentCommit({ hash, branch, changedFiles: files });
+    },
+
+    // Audit log — record every command
+    afterCommand: ({ command, args, result }) => {
+      auditLog.push({ command: `git ${command}`, exitCode: result.exitCode });
+    },
+
+    // Gate pushes on human approval
+    beforeCommand: async ({ command }) => {
+      if (command === "push" && !(await getHumanApproval())) {
+        return { reject: true, message: "Push blocked — awaiting approval." };
       }
-    }
-  }
-  return next();
+    },
+  },
 });
 ```
 
-## Hooks
-
-Hooks fire at specific points inside command execution (after middleware, inside operation logic). Register with `git.on(event, handler)`, which returns an unsubscribe function.
-
-Pre-hooks can abort the operation by returning `{ abort: true, message? }`. Post-hooks are observational — return value is ignored.
+Use `composeGitHooks()` to combine multiple hook sets:
 
 ```ts
-// Block secrets from being committed
-git.on("pre-commit", (event) => {
-  const forbidden = event.index.entries.filter((e) => /\.(env|pem|key)$/.test(e.path));
-  if (forbidden.length) {
-    return { abort: true, message: `Blocked: ${forbidden.map((e) => e.path).join(", ")}` };
-  }
-});
+import { createGit, composeGitHooks } from "just-git";
 
-// Enforce conventional commit messages
-git.on("commit-msg", (event) => {
-  if (!/^(feat|fix|docs|refactor|test|chore)(\(.+\))?:/.test(event.message)) {
-    return { abort: true, message: "Commit message must follow conventional commits format" };
-  }
-});
-
-// Feed agent activity to your UI or orchestration layer
-git.on("post-commit", (event) => {
-  onAgentCommit({ hash: event.hash, branch: event.branch, message: event.message });
+const git = createGit({
+  hooks: composeGitHooks(auditHooks, policyHooks, loggingHooks),
 });
 ```
 
-Available pre-hooks: `pre-commit`, `commit-msg`, `merge-msg`, `pre-merge-commit`, `pre-checkout`, `pre-push`, `pre-fetch`, `pre-clone`, `pre-pull`, `pre-rebase`, `pre-reset`, `pre-clean`, `pre-rm`, `pre-cherry-pick`, `pre-revert`, `pre-stash`. Available post-hooks: `post-commit`, `post-merge`, `post-checkout`, `post-push`, `post-fetch`, `post-clone`, `post-pull`, `post-reset`, `post-clean`, `post-rm`, `post-cherry-pick`, `post-revert`, `post-stash`. Low-level events: `ref:update`, `ref:delete`, `object:write`.
+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`.
 
-See [HOOKS.md](HOOKS.md) for full payload types and the `CommandEvent` shape.
+## 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 `GitContext` instances on other virtual filesystems, so clone/fetch/push/pull cross VFS boundaries without any network or shared filesystem.
+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.
 
 ```ts
 import { Bash, InMemoryFs } from "just-bash";
-import { createGit, findGitDir } from "just-git";
+import { createGit, findRepo } from "just-git";
 
 // Origin repo on its own filesystem
 const originFs = new InMemoryFs();
@@ -145,17 +173,13 @@ await setupBash.exec("git init");
 await setupBash.exec("echo 'hello' > README.md");
 await setupBash.exec("git add . && git commit -m 'initial'");
 
-const originCtx = await findGitDir(originFs, "/repo");
-const resolve = (url: string) => (url === "/origin" ? originCtx : null);
-
-// Each agent gets its own filesystem + resolveRemote pointing to origin
 const alice = new Bash({
   fs: new InMemoryFs(),
   cwd: "/repo",
   customCommands: [
     createGit({
       identity: { name: "Alice", email: "alice@example.com", locked: true },
-      resolveRemote: resolve,
+      resolveRemote: () => findRepo(originFs, "/repo"),
     }),
   ],
 });
@@ -166,7 +190,7 @@ const bob = new Bash({
   customCommands: [
     createGit({
       identity: { name: "Bob", email: "bob@example.com", locked: true },
-      resolveRemote: resolve,
+      resolveRemote: () => findRepo(originFs, "/repo"),
     }),
   ],
 });
@@ -181,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.
@@ -264,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>`.