From 3f90f9454766afab8a0c11a6f32d17916448f632 Mon Sep 17 00:00:00 2001 From: J Chris Anderson Date: Mon, 11 Aug 2025 13:05:11 -0700 Subject: [PATCH 1/4] docs: add development guide with workspace layout and release process --- CLAUDE.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..eba4a8de2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,90 @@ +# Fireproof Development Guide + +## Development Workflow + +Always run after making changes: +```bash +pnpm check +``` + +This command runs formatting, linting, tests, and build to ensure code quality. + +## Workspace Layout + +This is a pnpm monorepo with packages organized as follows: + +### Core Packages (`core/`) +- **`core/base/`** - Core database logic (CRDT, indexing, querying) + - Tests: `tests/fireproof/` (database.test.ts, crdt.test.ts, etc.) +- **`core/blockstore/`** - Storage layer (transactions, loaders, connections) + - Tests: `tests/blockstore/` (store.test.ts, transaction.test.ts, etc.) +- **`core/runtime/`** - Runtime utilities (crypto, file handling, task management) + - Tests: `tests/runtime/` (key-bag.test.ts, etc.) +- **`core/gateways/`** - Storage adapters for different environments: + - `indexeddb/` - Browser IndexedDB storage + - `file/`, `file-node/`, `file-deno/` - File system storage + - `memory/` - In-memory storage + - `cloud/` - Cloud/remote storage + - Tests: `tests/gateway/` +- **`core/types/`** - TypeScript type definitions +- **`core/protocols/`** - Communication protocols (dashboard, cloud sync) + +### React Integration (`use-fireproof/`) +- **`use-fireproof/react/`** - React hooks (useFireproof, useDocument, useLiveQuery) +- **`use-fireproof/tests/`** - React component tests + +### Applications +- **`dashboard/`** - Web dashboard for managing Fireproof instances +- **`cloud/`** - Cloud backend services +- **`examples/`** - Example applications + +### Test Organization +- **`tests/`** - Main test suite (core functionality) +- **`use-fireproof/tests/`** - React-specific tests +- **`smoke/`** - Integration tests for different environments +- **`tests/__screenshots__/`** - Visual regression test snapshots + +## Release Process + +### Creating a New Release + +To release a new version of Fireproof packages (`@fireproof/core` and `use-fireproof`), simply create and push a git tag with the format `core@v`: + +```bash +git tag -a core@v0.23.0 -m "Release v0.23.0" +git push origin core@v0.23.0 +``` + +### What Happens Automatically + +The GitHub Actions workflow `.github/workflows/ci-core-publish.yaml` will automatically: + +1. **Trigger** on any tag matching `core@*` +2. **Build** the packages using the existing build system +3. **Extract** the version from the tag (e.g., `v0.23.0` → `0.23.0`) +4. **Publish** both packages to npm: + - `@fireproof/core@0.23.0` + - `use-fireproof@0.23.0` + +### Recent Release Examples + +- `core@v0.22.0-keybag` → Published as `0.22.0-keybag` +- `core@v0.22.0-dev-preview-4` → Published as `0.22.0-dev-preview-4` +- `core@v0.22.0-dev-preview-3` → Published as `0.22.0-dev-preview-3` + +### Monitoring Release Status + +Check the GitHub Actions tab to monitor the release progress: +```bash +gh run list --limit 10 +``` + +The release is successful when you see a "completed success" status for the `@fireproof/core-publish` workflow. + +### Version History + +Current npm versions can be checked with: +```bash +npm view @fireproof/core versions --json +npm view use-fireproof versions --json +``` \ No newline at end of file From 5a7b71372b4f16c4ed8f6556bec5c8d9e20b4576 Mon Sep 17 00:00:00 2001 From: J Chris Anderson Date: Mon, 11 Aug 2025 13:08:19 -0700 Subject: [PATCH 2/4] docs: add branch naming convention --- CLAUDE.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index eba4a8de2..8306cb5c4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,6 +9,14 @@ pnpm check This command runs formatting, linting, tests, and build to ensure code quality. +## Branch Naming Convention + +Use the format `{username}/{topic}` for branch names: +```bash +git checkout -b jchris/fix-bug-123 +git checkout -b alice/add-new-feature +``` + ## Workspace Layout This is a pnpm monorepo with packages organized as follows: From 5cf8c5ae90a17af98bbe75d8e0e0ec1b765d314b Mon Sep 17 00:00:00 2001 From: J Chris Anderson Date: Mon, 11 Aug 2025 13:11:52 -0700 Subject: [PATCH 3/4] docs: improve markdown formatting and readability in CLAUDE.md --- CLAUDE.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8306cb5c4..02b06e82e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,6 +3,7 @@ ## Development Workflow Always run after making changes: + ```bash pnpm check ``` @@ -12,6 +13,7 @@ This command runs formatting, linting, tests, and build to ensure code quality. ## Branch Naming Convention Use the format `{username}/{topic}` for branch names: + ```bash git checkout -b jchris/fix-bug-123 git checkout -b alice/add-new-feature @@ -22,7 +24,8 @@ git checkout -b alice/add-new-feature This is a pnpm monorepo with packages organized as follows: ### Core Packages (`core/`) -- **`core/base/`** - Core database logic (CRDT, indexing, querying) + +- **`core/base/`** - Core database logic (CRDT, indexing, querying) - Tests: `tests/fireproof/` (database.test.ts, crdt.test.ts, etc.) - **`core/blockstore/`** - Storage layer (transactions, loaders, connections) - Tests: `tests/blockstore/` (store.test.ts, transaction.test.ts, etc.) @@ -30,7 +33,7 @@ This is a pnpm monorepo with packages organized as follows: - Tests: `tests/runtime/` (key-bag.test.ts, etc.) - **`core/gateways/`** - Storage adapters for different environments: - `indexeddb/` - Browser IndexedDB storage - - `file/`, `file-node/`, `file-deno/` - File system storage + - `file/`, `file-node/`, `file-deno/` - File system storage - `memory/` - In-memory storage - `cloud/` - Cloud/remote storage - Tests: `tests/gateway/` @@ -38,17 +41,20 @@ This is a pnpm monorepo with packages organized as follows: - **`core/protocols/`** - Communication protocols (dashboard, cloud sync) ### React Integration (`use-fireproof/`) + - **`use-fireproof/react/`** - React hooks (useFireproof, useDocument, useLiveQuery) - **`use-fireproof/tests/`** - React component tests -### Applications +### Applications + - **`dashboard/`** - Web dashboard for managing Fireproof instances - **`cloud/`** - Cloud backend services - **`examples/`** - Example applications ### Test Organization + - **`tests/`** - Main test suite (core functionality) -- **`use-fireproof/tests/`** - React-specific tests +- **`use-fireproof/tests/`** - React-specific tests - **`smoke/`** - Integration tests for different environments - **`tests/__screenshots__/`** - Visual regression test snapshots @@ -83,6 +89,7 @@ The GitHub Actions workflow `.github/workflows/ci-core-publish.yaml` will automa ### Monitoring Release Status Check the GitHub Actions tab to monitor the release progress: + ```bash gh run list --limit 10 ``` @@ -92,7 +99,8 @@ The release is successful when you see a "completed success" status for the `@fi ### Version History Current npm versions can be checked with: + ```bash npm view @fireproof/core versions --json npm view use-fireproof versions --json -``` \ No newline at end of file +``` From db2f57afe253bfcd9e6af22a9625250610ac51f3 Mon Sep 17 00:00:00 2001 From: J Chris Anderson Date: Wed, 13 Aug 2025 12:57:17 -0700 Subject: [PATCH 4/4] docs: add code style guidelines including TypeScript best practices and testing mock policy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Never use 'any' type - require specific types or union types - Use 'function' keyword for top-level functions over arrow functions - Document Vitest mocking patterns used in codebase (vi.fn(), custom mock classes) - Reference test helpers in tests/helpers.ts for consistent test setup - Specify mock call verification patterns (fn.mock.calls) 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 02b06e82e..07ec16e0b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,21 @@ pnpm check This command runs formatting, linting, tests, and build to ensure code quality. +## Code Style Guidelines + +### TypeScript Best Practices + +- **Never use `any` type** - Always provide specific types or use union types +- **Use `function` keyword** - Prefer `function functionName() {}` over arrow functions for top-level functions + +### Testing and Mock Policy + +- **Use Vitest mocking** - Use `vi.fn()` for creating mock functions and spies +- **Custom mock classes** - Create mock implementations that implement interfaces (see `MockLoader`, `MockSuperThis` in `tests/helpers.ts`) +- **Test helpers** - Use `mockSuperThis()` and other helpers from `tests/helpers.ts` for consistent test setup +- **Mock call verification** - Access mock call data via `fn.mock.calls` for assertions +- **Avoid real dependencies** - Use mocks to isolate units under test from external dependencies + ## Branch Naming Convention Use the format `{username}/{topic}` for branch names: