fix: add CLAUDE.md

Author: alex-titarenko

CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+git-essentials is a TypeScript library providing essential Git commands for both Node.js and browser environments with zero native dependencies. It works by directly modifying `.git` directory contents, aiming for 100% interoperability with canonical git. Based on isomorphic-git.
+
+## Build & Development Commands
+
+```bash
+npm run check          # TypeScript type checking (tsc --noEmit)
+npm run build          # Compile TypeScript to ESM (outputs to dist/)
+npm test               # Run Jest tests with coverage
+npm run test:browser   # Run Karma browser tests (dev mode, needs browsers)
+npm run test:browsers  # Run Karma headless (Chrome, Firefox, WebKit)
+```
+
+Run a single test file:
+```bash
+npx jest tests/clone.test.ts
+```
+
+Run a specific test by name:
+```bash
+npx jest -t "test name pattern"
+```
+
+## Architecture
+
+### Layered Design
+
+The codebase follows a strict layered architecture:
+
+1. **API layer** (`src/api/`) — Public functions. Each validates parameters via `assertParameter`, wraps `FsClient` in a `FileSystem` abstraction, delegates to the command layer, and tags errors with `err.caller`.
+
+2. **Command layer** (`src/commands/`) — Internal implementations prefixed with underscore (e.g., `_clone`). Contains the actual git logic.
+
+3. **Manager layer** (`src/managers/`) — Stateful git resource management: config, index, refs, remotes, ignores, shallow commits.
+
+4. **Model layer** (`src/models/`) — Data structures: `GitCommit`, `GitTree`, `GitIndex`, `GitPackIndex`, `GitObject`, walker types. Re-exported from `src/index.ts`.
+
+5. **Storage layer** (`src/storage/`) — Git object database: reading/writing loose and packed objects.
+
+6. **Wire layer** (`src/wire/`) — Git smart HTTP protocol: parsing and writing upload-pack/receive-pack messages.
+
+### Cross-Environment Support
+
+The library uses an adapter pattern for environment portability:
+
+- **Filesystem clients** (`src/clients/fs/`): `InMemoryFsClient`, `IndexedDbFsClient`, `FileSystemAccessApiFsClient`. All implement the `FsClient` interface.
+- **HTTP clients** (`src/clients/http/`): `NodeHttpClient`, `WebHttpClient`. Both implement `HttpClient`.
+- Consumers pass `fs` and `http` implementations into every API call — the library never imports environment-specific code directly.
+
+### Error Handling
+
+Custom error hierarchy in `src/errors/` with 30+ specific types extending `BaseError`. All API functions catch errors and attach a `caller` property (e.g., `git.clone`).
+
+## Testing
+
+Tests use **Jest** with **ts-jest** and run against in-memory fixtures (no real filesystem or network):
+
+- `makeFsFixture()` — creates an `InMemoryFsClient` with optional pre-populated directory tree from JSON fixture data
+- `makeHttpFixture()` — creates a mock `HttpClient` that matches requests against fixture data (JSON files with base64-encoded request/response pairs)
+- Fixture data is generated by scripts in `scripts/` (`gen-fs-fixture.js`, `gen-http-fixture.js`)
+
+Module aliases in tests: `git-essentials` maps to `src/`, and `src/*` paths are supported via Jest's `moduleNameMapper`.
+
+## Package Exports
+
+The package is ESM-only (`"type": "module"`) with tree-shakeable sub-path exports:
+- `git-essentials` — all API functions + models
+- `git-essentials/api/*` — individual API functions
+- `git-essentials/errors` — error types
+- `git-essentials/models/*` — data models
+- `git-essentials/clients/*` — fs/http client implementations