Skip to content

CLAUDE.md

Latest commit

 

History

History
76 lines (49 loc) · 3.49 KB

CLAUDE.md

File metadata and controls

76 lines (49 loc) · 3.49 KB

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

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:

npx jest tests/clone.test.ts

Run a specific test by name:

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