just-git 0.1.8 → 0.1.10

package/README.md

@@ -2,8 +2,11 @@
 
 [![CI](https://github.com/blindmansion/just-git/actions/workflows/ci.yml/badge.svg)](https://github.com/blindmansion/just-git/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/just-git)](https://www.npmjs.com/package/just-git)
+[![bundle size](https://img.shields.io/bundlejs/size/just-git)](https://bundlejs.com/?q=just-git)
 
-Git implementation for virtual bash environments (particularly [just-bash](https://github.com/vercel-labs/just-bash)). Pure TypeScript, zero dependencies. Works in Node, Bun, Deno, and the browser. ~100 kB gzipped.
+Pure TypeScript git implementation. Zero dependencies. 34 commands. Works in Node, Bun, Deno, and the browser.
+
+Designed for sandboxed environments where shelling out to real git isn't possible or desirable. Targets faithful reproduction of real git's behavior and output. Operates on an abstract `FileSystem` interface — plug in an in-memory VFS, a real filesystem, or anything else. Pairs with [just-bash](https://github.com/vercel-labs/just-bash), which provides an in-memory filesystem and shell that just-git registers into as a custom command.
 
 ## Install
 
@@ -37,27 +40,26 @@ await bash.exec("git log --oneline");
 
 `createGit(options?)` accepts:
 
-| Option        | Description                                                                                                                                                         |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `identity`    | Author/committer override. With `locked: true`, always wins over env vars and git config. Without `locked`, acts as a fallback.                                     |
-| `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` implementation. Set to `false` to block all network access. |
+| Option          | Description                                                                                                                                                                                   |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `identity`      | Author/committer override. With `locked: true`, always wins over env vars and git config. Without `locked`, acts as a fallback.                                                               |
+| `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).                                                          |
 
 ```ts
 const git = createGit({
   identity: { name: "Agent Bot", email: "bot@company.com", locked: true },
   credentials: async (url) => ({ type: "bearer", token: "ghp_..." }),
   disabled: ["rebase"],
-  network: { allowed: ["github.com"], fetch: customFetch },
+  network: false, // no HTTP access
 });
 ```
 
 ## Middleware
 
-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).
-
-The `CommandEvent` provides the execution context: `{ command, rawArgs, fs, cwd, env, stdin }`, plus optional `exec` and `signal` when available.
+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.
 
 ```ts
 // Audit log — record every command the agent runs
@@ -90,15 +92,11 @@ git.use(async (event, next) => {
 });
 ```
 
-`git.use()` returns an unsubscribe function to remove the middleware dynamically.
-
 ## 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
-
-Pre-hooks can abort the operation by returning `{ abort: true, message? }`.
+Pre-hooks can abort the operation by returning `{ abort: true, message? }`. Post-hooks are observational — return value is ignored.
 
 ```ts
 // Block secrets from being committed
@@ -115,71 +113,77 @@ git.on("commit-msg", (event) => {
     return { abort: true, message: "Commit message must follow conventional commits format" };
   }
 });
-```
 
-| Hook               | Payload                                                         |
-| ------------------ | --------------------------------------------------------------- |
-| `pre-commit`       | `{ index, treeHash }`                                           |
-| `commit-msg`       | `{ message }` (mutable)                                         |
-| `merge-msg`        | `{ message, treeHash, headHash, theirsHash }` (mutable message) |
-| `pre-merge-commit` | `{ mergeMessage, treeHash, headHash, theirsHash }`              |
-| `pre-checkout`     | `{ target, mode }`                                              |
-| `pre-push`         | `{ remote, url, refs[] }`                                       |
-| `pre-fetch`        | `{ remote, url, refspecs, prune, tags }`                        |
-| `pre-clone`        | `{ repository, targetPath, bare, branch }`                      |
-| `pre-pull`         | `{ remote, branch }`                                            |
-| `pre-rebase`       | `{ upstream, branch }`                                          |
-| `pre-reset`        | `{ mode, target }`                                              |
-| `pre-clean`        | `{ dryRun, force, removeDirs, removeIgnored, onlyIgnored }`     |
-| `pre-rm`           | `{ paths, cached, recursive, force }`                           |
-| `pre-cherry-pick`  | `{ mode, commit }`                                              |
-| `pre-revert`       | `{ mode, commit }`                                              |
-| `pre-stash`        | `{ action, ref }`                                               |
-
-### Post-hooks
-
-Post-hooks are observational -- return value is ignored. Handlers are awaited in registration order.
-
-```ts
 // Feed agent activity to your UI or orchestration layer
 git.on("post-commit", (event) => {
   onAgentCommit({ hash: event.hash, branch: event.branch, message: event.message });
 });
+```
+
+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`.
+
+See [HOOKS.md](HOOKS.md) for full payload types and the `CommandEvent` shape.
+
+## 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.
+
+```ts
+import { Bash, InMemoryFs } from "just-bash";
+import { createGit, findGitDir } from "just-git";
+
+// Origin repo on its own filesystem
+const originFs = new InMemoryFs();
+const setupBash = new Bash({
+  fs: originFs,
+  cwd: "/repo",
+  customCommands: [
+    createGit({ identity: { name: "Setup", email: "setup@example.com", locked: true } }),
+  ],
+});
+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,
+    }),
+  ],
+});
 
-git.on("post-push", (event) => {
-  onAgentPush({ remote: event.remote, refs: event.refs });
+const bob = new Bash({
+  fs: new InMemoryFs(),
+  cwd: "/repo",
+  customCommands: [
+    createGit({
+      identity: { name: "Bob", email: "bob@example.com", locked: true },
+      resolveRemote: resolve,
+    }),
+  ],
 });
+
+await alice.exec("git clone /origin /repo");
+await bob.exec("git clone /origin /repo");
+
+// Alice and Bob work independently, push to origin, fetch each other's changes
 ```
 
-| Hook               | Payload                                          |
-| ------------------ | ------------------------------------------------ |
-| `post-commit`      | `{ hash, message, branch, parents, author }`     |
-| `post-merge`       | `{ headHash, theirsHash, strategy, commitHash }` |
-| `post-checkout`    | `{ prevHead, newHead, isBranchCheckout }`        |
-| `post-push`        | same payload as `pre-push`                       |
-| `post-fetch`       | `{ remote, url, refsUpdated }`                   |
-| `post-clone`       | `{ repository, targetPath, bare, branch }`       |
-| `post-pull`        | `{ remote, branch, strategy, commitHash }`       |
-| `post-reset`       | `{ mode, targetHash }`                           |
-| `post-clean`       | `{ removed, dryRun }`                            |
-| `post-rm`          | `{ removedPaths, cached }`                       |
-| `post-cherry-pick` | `{ mode, commitHash, hadConflicts }`             |
-| `post-revert`      | `{ mode, commitHash, hadConflicts }`             |
-| `post-stash`       | `{ action, ok }`                                 |
-
-### Low-level events
-
-Fire-and-forget events emitted on every object/ref write. Handler errors are caught and forwarded to `hooks.onError` (no-op by default).
-
-| Event          | Payload                     |
-| -------------- | --------------------------- |
-| `ref:update`   | `{ ref, oldHash, newHash }` |
-| `ref:delete`   | `{ ref, oldHash }`          |
-| `object:write` | `{ type, hash }`            |
+Concurrent pushes to the same remote are automatically serialized — if two agents push simultaneously, one succeeds and the other gets a proper non-fast-forward rejection, just like real git.
+
+See [`examples/multi-agent.ts`](examples/multi-agent.ts) for a full working example with a coordinator agent that merges feature branches.
 
 ## Command coverage
 
-34 commands implemented. See [CLI.md](CLI.md) for full usage details.
+See [CLI.md](CLI.md) for full usage details.
 
 | Command                           | Flags / options                                                                                                                                                                |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -221,6 +225,7 @@ Fire-and-forget events emitted on every object/ref write. Handler errors are cau
 ### Transport
 
 - **Local paths** -- direct filesystem transfer between repositories.
+- **Cross-VFS** -- clone, fetch, and push between isolated in-memory filesystems via `resolveRemote`. See [Multi-agent collaboration](#multi-agent-collaboration).
 - **Smart HTTP** -- clone, fetch, and push against real Git servers (e.g. GitHub) via Git Smart HTTP protocol. Auth via `credentials` option or `GIT_HTTP_BEARER_TOKEN` / `GIT_HTTP_USER` + `GIT_HTTP_PASSWORD` env vars.
 
 ### Internals
@@ -233,12 +238,30 @@ Fire-and-forget events emitted on every object/ref write. Handler errors are cau
 - Packfiles with zlib compression for storage and transport
 - Pathspec globs across `add`, `rm`, `diff`, `reset`, `checkout`, `restore`, `log`
 
-## Goals and testing
+## Testing
+
+Targets high fidelity to real git (2.53.0). Tested with an [oracle framework](test/oracle/README.md) that generates hundreds of randomized git workflows totaling hundreds of thousands of operations, runs them against real git, then replays each step against just-git and compares repository state and command output. State comparison covers HEAD, refs, index, worktree, active operation state, and stash. Output comparison covers exit codes, stdout, and stderr.
+
+When backed by a real filesystem (e.g. just-bash `ReadWriteFs`), interoperable with real git on the same repo, though less extensively tested than behavioral correctness.
 
-High fidelity to real git (2.53.0) state and output. Tested using real git as an [oracle](test/oracle/README.md) — hundreds of randomized traces totaling hundreds of thousands of git operations, each verified step-by-step against real git's state and output.
+## Without just-bash
 
-When backed by a real filesystem (e.g. `just-bash` `ReadWriteFs`), interoperable with real git on the same repo, though less extensively tested than behavioral correctness.
+`git.execute()` takes an args array and a `CommandContext`. Provide any `FileSystem` implementation:
+
+```ts
+import { createGit } from "just-git";
+
+const git = createGit({ identity: { name: "Bot", email: "bot@example.com" } });
+
+const result = await git.execute(["init"], {
+  fs: myFileSystem, // any FileSystem implementation
+  cwd: "/repo",
+  env: new Map(),
+  stdin: "",
+});
+
+console.log(result.exitCode); // 0
+```
 
-## Disclaimer
+The `FileSystem` interface requires: `readFile`, `readFileBuffer`, `writeFile`, `exists`, `stat`, `mkdir`, `readdir`, `rm`. Optional: `lstat`, `readlink`, `symlink`.
 
-This project is not affiliated with [just-bash](https://github.com/vercel-labs/just-bash) or Vercel.

package/dist/index.d.ts

@@ -28,10 +28,37 @@ interface FileSystem {
     symlink?(target: string, path: string): Promise<void>;
 }
 
+/**
+ * Git object storage: compressed loose objects for new writes, with
+ * retained packfiles from fetch/clone. Reads check loose first,
+ * then fall back to pack indices.
+ */
+declare class PackedObjectStore {
+    private fs;
+    private gitDir;
+    private hooks?;
+    private packs;
+    private loadedPackNames;
+    private discoverPromise;
+    constructor(fs: FileSystem, gitDir: string, hooks?: HookEmitter | undefined);
+    write(type: ObjectType, content: Uint8Array): Promise<ObjectId>;
+    read(hash: ObjectId): Promise<RawObject>;
+    exists(hash: ObjectId): Promise<boolean>;
+    ingestPack(packData: Uint8Array): Promise<number>;
+    /** Scan `.git/objects/pack/` for existing pack/idx pairs. */
+    private discover;
+    private doDiscover;
+}
+
 /** 40-character lowercase hex SHA-1 hash. */
 type ObjectId = string;
 /** The four Git object types. */
 type ObjectType = "blob" | "tree" | "commit" | "tag";
+/** An object as stored in .git/objects — type + raw content bytes. */
+interface RawObject {
+    type: ObjectType;
+    content: Uint8Array;
+}
 /** Author or committer identity with timestamp. */
 interface Identity {
     name: string;
@@ -68,6 +95,32 @@ interface Index {
     version: number;
     entries: IndexEntry[];
 }
+/**
+ * Bundles the filesystem handle with resolved repository paths.
+ * Threaded through all library functions so they don't need to
+ * re-discover the .git directory on every call.
+ */
+interface GitContext {
+    fs: FileSystem;
+    /** Absolute path to the .git directory. */
+    gitDir: string;
+    /** Absolute path to the working tree root, or null for bare repos. */
+    workTree: string | null;
+    /** Hook emitter for operation hooks and low-level events. */
+    hooks?: HookEmitter;
+    /** Operator-provided credential resolver (bypasses env vars). */
+    credentialProvider?: CredentialProvider;
+    /** Operator-provided identity override for author/committer. */
+    identityOverride?: IdentityOverride;
+    /** Custom fetch function for HTTP transport. Falls back to globalThis.fetch. */
+    fetchFn?: FetchFunction;
+    /** Network access policy. `false` blocks all HTTP access. */
+    networkPolicy?: NetworkPolicy | false;
+    /** Resolves remote URLs to GitContexts on potentially different VFS instances. */
+    resolveRemote?: RemoteResolver;
+    /** Cached object store instance. Lazily created by object-db. */
+    objectStore?: PackedObjectStore;
+}
 
 type HttpAuth = {
     type: "basic";
@@ -90,6 +143,12 @@ interface IdentityOverride {
     email: string;
     locked?: boolean;
 }
+/**
+ * Resolves a remote URL to a GitContext, enabling cross-VFS transport.
+ * Called before local filesystem lookup for non-HTTP URLs.
+ * Return null to fall back to local filesystem resolution.
+ */
+type RemoteResolver = (url: string) => GitContext | null | Promise<GitContext | null>;
 type FetchFunction = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface NetworkPolicy {
     /**
@@ -366,6 +425,12 @@ interface GitOptions {
     disabled?: GitCommandName[];
     /** Network policy. Set to `false` to block all HTTP access. */
     network?: NetworkPolicy | false;
+    /**
+     * Resolve a remote URL to a GitContext on a potentially different VFS.
+     * Called before local filesystem lookup for non-HTTP remote URLs.
+     * Return null to fall back to local filesystem resolution.
+     */
+    resolveRemote?: RemoteResolver;
 }
 /**
  * Bundle of operator-level extensions threaded into command handlers
@@ -377,6 +442,7 @@ interface GitExtensions {
     identityOverride?: IdentityOverride;
     fetchFn?: FetchFunction;
     networkPolicy?: NetworkPolicy | false;
+    resolveRemote?: RemoteResolver;
 }
 declare class Git {
     readonly name = "git";
@@ -392,4 +458,12 @@ declare class Git {
 }
 declare function createGit(options?: GitOptions): Git;
 
-export { type AbortResult, type CommandContext, type CommandEvent, type CommandExecOptions, type CommitMsgEvent, type CredentialProvider, type ExecResult, type FetchFunction, type FileStat, type FileSystem, Git, type GitCommandName, type GitExtensions, type GitOptions, type HookEventMap, type HookHandler, type IdentityOverride, type MergeMsgEvent, type Middleware, type NetworkPolicy, type ObjectWriteEvent, type PostCheckoutEvent, type PostCherryPickEvent, type PostCleanEvent, type PostCloneEvent, type PostCommitEvent, type PostFetchEvent, type PostMergeEvent, type PostPullEvent, type PostPushEvent, type PostResetEvent, type PostRevertEvent, type PostRmEvent, type PostStashEvent, type PreCheckoutEvent, type PreCherryPickEvent, type PreCleanEvent, type PreCloneEvent, type PreCommitEvent, type PreFetchEvent, type PreMergeCommitEvent, type PrePullEvent, type PrePushEvent, type PreRebaseEvent, type PreResetEvent, type PreRevertEvent, type PreRmEvent, type PreStashEvent, type RefDeleteEvent, type RefUpdateEvent, createGit };
+/**
+ * Walk up from `startPath` looking for a git repository.
+ * Checks for both normal repos (`.git/` subdirectory) and bare repos
+ * (`HEAD` + `objects/` + `refs/` directly in the directory).
+ * Returns a GitContext if found, null otherwise.
+ */
+declare function findGitDir(fs: FileSystem, startPath: string): Promise<GitContext | null>;
+
+export { type AbortResult, type CommandContext, type CommandEvent, type CommandExecOptions, type CommitMsgEvent, type CredentialProvider, type ExecResult, type FetchFunction, type FileStat, type FileSystem, Git, type GitCommandName, type GitContext, type GitExtensions, type GitOptions, type HookEventMap, type HookHandler, type IdentityOverride, type MergeMsgEvent, type Middleware, type NetworkPolicy, type ObjectWriteEvent, type PostCheckoutEvent, type PostCherryPickEvent, type PostCleanEvent, type PostCloneEvent, type PostCommitEvent, type PostFetchEvent, type PostMergeEvent, type PostPullEvent, type PostPushEvent, type PostResetEvent, type PostRevertEvent, type PostRmEvent, type PostStashEvent, type PreCheckoutEvent, type PreCherryPickEvent, type PreCleanEvent, type PreCloneEvent, type PreCommitEvent, type PreFetchEvent, type PreMergeCommitEvent, type PrePullEvent, type PrePushEvent, type PreRebaseEvent, type PreResetEvent, type PreRevertEvent, type PreRmEvent, type PreStashEvent, type RefDeleteEvent, type RefUpdateEvent, type RemoteResolver, createGit, findGitDir };