just-git 0.1.7 → 0.1.9

package/README.md

@@ -3,7 +3,7 @@
 [![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)
 
-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.
+Git implementation for virtual bash environments (particularly [just-bash](https://github.com/vercel-labs/just-bash)). Pure TypeScript, zero dependencies. 34 commands implemented. Works in Node, Bun, Deno, and the browser. ~100 kB gzipped.
 
 ## Install
 
@@ -37,12 +37,13 @@ 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` implementation. 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({
@@ -177,9 +178,55 @@ Fire-and-forget events emitted on every object/ref write. Handler errors are cau
 | `ref:delete`   | `{ ref, oldHash }`          |
 | `object:write` | `{ type, hash }`            |
 
+## 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");
+
+// Each agent gets its own filesystem + resolveRemote pointing to origin
+function createAgent(name: string, email: string) {
+  const agentFs = new InMemoryFs();
+  const git = createGit({
+    identity: { name, email, locked: true },
+    resolveRemote: (url) => (url === "/origin" ? originCtx : null),
+  });
+  return new Bash({ fs: agentFs, cwd: "/repo", customCommands: [git] });
+}
+
+const alice = createAgent("Alice", "alice@example.com");
+const bob = createAgent("Bob", "bob@example.com");
+
+await alice.exec("git clone /origin /repo", { cwd: "/" });
+await bob.exec("git clone /origin /repo", { cwd: "/" });
+
+// Alice and Bob work independently, push to origin, fetch each other's changes
+```
+
+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                                                                                                                                                                |
 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

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 };