catmint-fs

A TypeScript monorepo providing a copy-on-write virtual filesystem with pluggable adapters and a pure-TypeScript git implementation built on top of it.

Packages

Package	Description
@catmint-fs/core	Virtual filesystem layer with copy-on-write semantics over a pluggable backing store
@catmint-fs/sqlite-adapter	SQLite-backed FsAdapter for @catmint-fs/core
@catmint-fs/git	Programmatic git operations (init, commit, branch, merge, diff, stash, fetch, push, clone)

Architecture

@catmint-fs/core              Virtual filesystem layer (adapters + copy-on-write)
    |
    +-- LocalAdapter           Node.js fs-backed adapter (built in)
    |
    +-- @catmint-fs/sqlite-adapter   SQLite-backed adapter
    |
    +-- @catmint-fs/git        Git operations over any Layer

@catmint-fs/core provides a POSIX-like filesystem API where reads fall through to the backing adapter and writes are captured in memory. Changes can be inspected, applied atomically, or discarded.

@catmint-fs/sqlite-adapter stores the entire filesystem in a single SQLite database -- useful for embedded, portable, or in-memory scenarios.

@catmint-fs/git implements git plumbing and porcelain in pure TypeScript. It operates on any Layer instance, so git repositories can live on disk, in SQLite, or in memory. Repositories are fully compatible with the canonical git CLI.

Browser compatibility

@catmint-fs/core and @catmint-fs/git are browser-safe -- they use Uint8Array instead of Buffer, ReadableStream instead of Node streams, Web Crypto for SHA-1, and fetch() for HTTP. LocalAdapter and @catmint-fs/sqlite-adapter are Node.js only.

Quick start

pnpm install
pnpm build

In-memory git repo

import { createLayer } from "@catmint-fs/core";
import { SqliteAdapter } from "@catmint-fs/sqlite-adapter";
import { initRepository } from "@catmint-fs/git";

const adapter = new SqliteAdapter({ database: ":memory:" });
const layer = await createLayer({ root: "/", adapter });

const repo = await initRepository(layer);
await layer.writeFile("/readme.txt", "Hello\n");
await repo.add("/readme.txt");
await repo.commit({ message: "first commit" });

const log = await repo.log();
console.log(log[0].message); // "first commit"

Local disk git repo

import { createLayer } from "@catmint-fs/core";
import { initRepository } from "@catmint-fs/git";

const layer = await createLayer({ root: "/tmp/my-repo" });
const repo = await initRepository(layer);
// ... works with standard git CLI

Development

Prerequisites

• Node.js >= 18
• pnpm 9

Scripts

pnpm build            # Build all packages
pnpm test             # Run all tests
pnpm test:coverage    # Run tests with coverage
pnpm typecheck        # Type-check all packages
pnpm clean            # Remove build artifacts

Running tests for a single package

pnpm --filter @catmint-fs/core test
pnpm --filter @catmint-fs/sqlite-adapter test
pnpm --filter @catmint-fs/git test

Test suite

The monorepo contains 588 tests across the three packages:

Package	Tests
@catmint-fs/core	212
@catmint-fs/sqlite-adapter	87
@catmint-fs/git	289

Tests are organized into unit/, integration/, and stress/ directories. The git package includes CLI compatibility tests that verify interoperability with the canonical git binary.

License

GPL-2.0 -- see LICENSE for details.