docs: update all documentation for node:sqlite, pnpm, proman workflow
- README: bun → pnpm, update API examples, add Node >=22.5.0 requirement - CLAUDE.md: replace 3-phase release process with proman bump/publish - Package READMEs: fix package names, update storage/API descriptions - Cards: update store.md (sqlite), cli.md (db filename, remove --var-db) - docs/sync-readme.md: update to proman workflow
This commit is contained in:
+1
-1
@@ -17,7 +17,7 @@ The `ocas` CLI is the primary interface for interacting with an OCAS [[Store]].
|
|||||||
| 2 | `OCAS_HOME` env var | `export OCAS_HOME=/data/ocas` |
|
| 2 | `OCAS_HOME` env var | `export OCAS_HOME=/data/ocas` |
|
||||||
| 3 | Default | `~/.ocas` |
|
| 3 | Default | `~/.ocas` |
|
||||||
|
|
||||||
The variable database lives at `<home>/variables.db` by default, overridable with `--var-db <path>`.
|
The SQLite database lives at `<home>/_store.db`.
|
||||||
|
|
||||||
## Commands
|
## Commands
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -53,7 +53,7 @@ In-memory `Map<Hash, CasNode>`. Used in tests and for ephemeral computation (e.g
|
|||||||
|
|
||||||
### FsStore (`@ocas/fs`)
|
### FsStore (`@ocas/fs`)
|
||||||
|
|
||||||
Filesystem-backed store. Nodes are serialized as CBOR files under a content-addressed directory tree. Created via `openStore(path)`, which:
|
Filesystem-backed store. CAS nodes are stored as CBOR files; variables and tags use SQLite (`node:sqlite`). Created via `openStore(path)`, which:
|
||||||
|
|
||||||
1. Creates the directory if it doesn't exist
|
1. Creates the directory if it doesn't exist
|
||||||
2. Runs [[Bootstrap]] automatically
|
2. Runs [[Bootstrap]] automatically
|
||||||
|
|||||||
@@ -20,7 +20,7 @@ Monorepo with 3 packages under `packages/`:
|
|||||||
- **Test:** Vitest (`npx vitest run`)
|
- **Test:** Vitest (`npx vitest run`)
|
||||||
- **Package Manager:** pnpm (workspace)
|
- **Package Manager:** pnpm (workspace)
|
||||||
- **Lint/Format:** Biome (`biome check .` / `biome format --write .`)
|
- **Lint/Format:** Biome (`biome check .` / `biome format --write .`)
|
||||||
- **Publish:** Changesets + `pnpm publish` → npmjs (`@ocas/*`)
|
- **Publish:** @shazhou/proman (`proman bump` + `proman publish`)
|
||||||
|
|
||||||
## Commands
|
## Commands
|
||||||
|
|
||||||
@@ -98,10 +98,7 @@ This is resolved to real version numbers only during publishing (see below).
|
|||||||
|
|
||||||
## Release Process
|
## Release Process
|
||||||
|
|
||||||
Releases use a **release branch** workflow with three phases: prepare → candidate → finalize.
|
Uses `@shazhou/proman` for releases. No release branches needed.
|
||||||
|
|
||||||
`main` always keeps `workspace:*` for internal deps; release branches fix them to real versions.
|
|
||||||
Changeset files are **only consumed once** during finalize — prerelease (rc) never touches them.
|
|
||||||
|
|
||||||
### Adding a Changeset
|
### Adding a Changeset
|
||||||
|
|
||||||
@@ -110,7 +107,7 @@ Add changesets alongside feature PRs on `main`:
|
|||||||
```markdown
|
```markdown
|
||||||
<!-- .changeset/my-change.md -->
|
<!-- .changeset/my-change.md -->
|
||||||
---
|
---
|
||||||
"@ocas/cli": patch
|
"@ocas/fs": minor
|
||||||
---
|
---
|
||||||
|
|
||||||
Description of the change
|
Description of the change
|
||||||
@@ -119,44 +116,15 @@ Description of the change
|
|||||||
Changesets live in `.changeset/` as markdown files. Bump types: `patch` / `minor` / `major`.
|
Changesets live in `.changeset/` as markdown files. Bump types: `patch` / `minor` / `major`.
|
||||||
One changeset can cover multiple packages.
|
One changeset can cover multiple packages.
|
||||||
|
|
||||||
### Phase 1: Prepare (cut release branch)
|
### Release Steps
|
||||||
|
|
||||||
- **Precondition:** on `main`, clean tree, `.changeset/` has pending changesets
|
1. `proman bump` — consume changesets and bump versions
|
||||||
- **Steps:**
|
2. `proman publish` — build → test → check → publish → changelog → tag → push
|
||||||
1. Determine target version (from changeset bump types or manually)
|
|
||||||
2. `git checkout -b release/<version>`
|
|
||||||
3. Fix `workspace:*` → real version numbers in all `package.json`
|
|
||||||
4. Commit
|
|
||||||
- **Does NOT** run `changeset version`, does NOT write CHANGELOG
|
|
||||||
|
|
||||||
### Phase 2: Candidate (publish rc for validation)
|
The publish command handles everything: workspace dependency resolution, npm publish order (core → fs → cli), changelog generation, git tagging, and pushing.
|
||||||
|
|
||||||
- **Precondition:** on `release/*` branch
|
|
||||||
- **Steps:**
|
|
||||||
1. Set version to `<version>-rc.N` (first time rc.1, increment on subsequent runs)
|
|
||||||
2. `pnpm install && pnpm run build && pnpm run test && pnpm run check`
|
|
||||||
3. Publish: `pnpm publish --tag rc` (order: core → fs → cli)
|
|
||||||
4. Commit + push
|
|
||||||
- **Repeatable:** fix bugs → add new changesets on the release branch → rc.N+1
|
|
||||||
- **Does NOT** consume changesets, does NOT write CHANGELOG
|
|
||||||
- Install for testing: `pnpm add -g @ocas/cli@rc`
|
|
||||||
|
|
||||||
### Phase 3: Finalize (official release)
|
|
||||||
|
|
||||||
- **Precondition:** on `release/*` branch, rc validated
|
|
||||||
- **Steps:**
|
|
||||||
1. Consume all `.changeset/*.md` → write CHANGELOG entries (use `changeset version` or manual)
|
|
||||||
2. Set final version `<version>` (remove `-rc.N`)
|
|
||||||
3. `pnpm install && pnpm run build && pnpm run test && pnpm run check`
|
|
||||||
4. Publish: `pnpm publish --tag latest` (order: core → fs → cli)
|
|
||||||
5. Git tag `v<version>`
|
|
||||||
6. Merge back to `main` (CHANGELOG comes along)
|
|
||||||
7. Restore `workspace:*` on `main`
|
|
||||||
8. Delete release branch
|
|
||||||
|
|
||||||
### Key Rules
|
### Key Rules
|
||||||
|
|
||||||
- **Publish order** is always `@ocas/core` → `@ocas/fs` → `@ocas/cli`
|
- **Publish order** is always `@ocas/core` → `@ocas/fs` → `@ocas/cli`
|
||||||
- **`workspace:*`** must be fixed before any publish — `pnpm publish` does NOT auto-replace them
|
- **`workspace:*`** is auto-resolved by pnpm during publish
|
||||||
- **CHANGELOG** only contains official releases, never rc entries
|
- **CHANGELOG** only contains official releases
|
||||||
- **Changesets added on release branch** (bug fixes during rc) are consumed together at finalize
|
|
||||||
|
|||||||
@@ -7,11 +7,13 @@ Every node has a typed payload: its `type` field is the hash of a JSON Schema th
|
|||||||
## Install
|
## Install
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun add -g @ocas/cli
|
pnpm add -g @ocas/cli
|
||||||
```
|
```
|
||||||
|
|
||||||
The store is auto-created and bootstrapped on first use — no `init` command needed.
|
The store is auto-created and bootstrapped on first use — no `init` command needed.
|
||||||
|
|
||||||
|
> Requires Node.js >= 22.5.0 (uses built-in node:sqlite)
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
@@ -190,8 +192,8 @@ Nodes reachable from any variable binding are kept; everything else is swept.
|
|||||||
## Using as a Library
|
## Using as a Library
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun add @ocas/core # in-memory store
|
pnpm add @ocas/core # in-memory store
|
||||||
bun add @ocas/core @ocas/fs # + filesystem persistence
|
pnpm add @ocas/core @ocas/fs # + filesystem persistence
|
||||||
```
|
```
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
@@ -214,9 +216,9 @@ const node = store.get(hash);
|
|||||||
For filesystem persistence, use `@ocas/fs`:
|
For filesystem persistence, use `@ocas/fs`:
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { openStoreAndVarStore } from "@ocas/fs";
|
import { openStore } from "@ocas/fs";
|
||||||
|
|
||||||
const { store, varStore } = await openStoreAndVarStore("/path/to/store");
|
const store = await openStore("/path/to/store");
|
||||||
```
|
```
|
||||||
|
|
||||||
See individual package READMEs for full API docs:
|
See individual package READMEs for full API docs:
|
||||||
@@ -228,11 +230,11 @@ See individual package READMEs for full API docs:
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone <repo-url> && cd ocas
|
git clone <repo-url> && cd ocas
|
||||||
bun install --no-cache
|
pnpm install
|
||||||
bun run build # tsc --build
|
pnpm run build # tsc --build
|
||||||
bun test # run all tests
|
pnpm test # run all tests
|
||||||
bun run check # biome lint
|
pnpm run check # biome lint
|
||||||
bun run format # biome format
|
pnpm run format # biome format
|
||||||
```
|
```
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|||||||
+4
-4
@@ -17,8 +17,8 @@ The root README should have these sections in order:
|
|||||||
4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib)
|
4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib)
|
||||||
5. **Quick Start** — install, build, basic usage
|
5. **Quick Start** — install, build, basic usage
|
||||||
6. **CLI Reference** — brief command list, detailed usage in cli README
|
6. **CLI Reference** — brief command list, detailed usage in cli README
|
||||||
7. **Development** — bun install / build / check / test
|
7. **Development** — pnpm install / build / check / test
|
||||||
8. **Publishing** — changeset workflow (bun run release)
|
8. **Publishing** — `proman bump` + `proman publish`
|
||||||
|
|
||||||
## Per-Package README Structure
|
## Per-Package README Structure
|
||||||
|
|
||||||
@@ -27,7 +27,7 @@ Each package README should have:
|
|||||||
1. **Title** — package name
|
1. **Title** — package name
|
||||||
2. **One-line description** — matching package.json
|
2. **One-line description** — matching package.json
|
||||||
3. **Overview** — what it does, where it sits in the architecture, dependencies
|
3. **Overview** — what it does, where it sits in the architecture, dependencies
|
||||||
4. **Installation** — bun add (for libs) or "included as binary" (for cli)
|
4. **Installation** — pnpm add (for libs) or "included as binary" (for cli)
|
||||||
5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
|
5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
|
||||||
6. **CLI Usage** (cli packages) — command reference with examples
|
6. **CLI Usage** (cli packages) — command reference with examples
|
||||||
7. **Internal Structure** — brief src/ file organization
|
7. **Internal Structure** — brief src/ file organization
|
||||||
@@ -57,7 +57,7 @@ For each package read:
|
|||||||
- All relative links work
|
- All relative links work
|
||||||
- Package names match package.json
|
- Package names match package.json
|
||||||
- No references to removed/renamed packages
|
- No references to removed/renamed packages
|
||||||
- bun run build still passes
|
- pnpm run build still passes
|
||||||
|
|
||||||
## Guidelines
|
## Guidelines
|
||||||
|
|
||||||
|
|||||||
@@ -15,17 +15,17 @@ The store is **auto-created and bootstrapped** on first use, so there is no `ini
|
|||||||
Published as an npm package with a binary entry:
|
Published as an npm package with a binary entry:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun add -g @ocas/cli
|
pnpm add -g @ocas/cli
|
||||||
# or from the monorepo workspace:
|
# or from the monorepo workspace:
|
||||||
bun link
|
pnpm link
|
||||||
```
|
```
|
||||||
|
|
||||||
**Binary name:** `ocas` (points to `src/index.ts`, run with Bun).
|
**Binary name:** `ocas` (points to `dist/index.js`, run with Node).
|
||||||
|
|
||||||
In development:
|
In development:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun packages/cli-ocas/src/index.ts <command> [args]
|
node packages/cli/dist/index.js <command> [args]
|
||||||
```
|
```
|
||||||
|
|
||||||
## CLI Usage
|
## CLI Usage
|
||||||
|
|||||||
@@ -6,14 +6,14 @@ Core CAS engine — hashing, schema, store, verify, bootstrap.
|
|||||||
|
|
||||||
`@ocas/core` is the foundation of the ocas monorepo. It defines content-addressed nodes (`CasNode`), the `Store` interface, XXH64-based hashing with deterministic CBOR, JSON Schema registration and validation (including `cas_ref` links between nodes), bootstrap seeding, and integrity verification.
|
`@ocas/core` is the foundation of the ocas monorepo. It defines content-addressed nodes (`CasNode`), the `Store` interface, XXH64-based hashing with deterministic CBOR, JSON Schema registration and validation (including `cas_ref` links between nodes), bootstrap seeding, and integrity verification.
|
||||||
|
|
||||||
Other packages build on this layer: `ocas-fs` provides persistence, and `cli-ocas` exposes store operations on the command line.
|
Other packages build on this layer: `@ocas/fs` provides persistence, and `@ocas/cli` exposes store operations on the command line.
|
||||||
|
|
||||||
**Dependencies:** `ajv`, `cborg`, `xxhash-wasm`
|
**Dependencies:** `ajv`, `cborg`, `xxhash-wasm`
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun add @ocas/core
|
pnpm add @ocas/core
|
||||||
```
|
```
|
||||||
|
|
||||||
## API
|
## API
|
||||||
|
|||||||
+7
-20
@@ -4,7 +4,7 @@ Filesystem-backed CAS store.
|
|||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
`@ocas/fs` implements a persistent `Store` on disk. Each node is stored as `<hash>.bin` (CBOR-encoded `CasNode`). A `_index/` directory maps type hashes to content hashes for `listByType`. Stores support bootstrap via the same `BOOTSTRAP_STORE` symbol as the in-memory implementation.
|
`@ocas/fs` implements a persistent `Store` backed by `node:sqlite` (`DatabaseSync`). Nodes are stored as CBOR blobs in SQLite tables. Stores support bootstrap via the same `BOOTSTRAP_STORE` symbol as the in-memory implementation.
|
||||||
|
|
||||||
Depends on `@ocas/core` for hashing, CBOR encoding, and types.
|
Depends on `@ocas/core` for hashing, CBOR encoding, and types.
|
||||||
|
|
||||||
@@ -13,7 +13,7 @@ Depends on `@ocas/core` for hashing, CBOR encoding, and types.
|
|||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
bun add @ocas/fs
|
pnpm add @ocas/fs
|
||||||
```
|
```
|
||||||
|
|
||||||
## API
|
## API
|
||||||
@@ -21,19 +21,18 @@ bun add @ocas/fs
|
|||||||
Exported from `src/index.ts`:
|
Exported from `src/index.ts`:
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
function createFsStore(dir: string): BootstrapCapableStore;
|
function openStore(path: string): Promise<Store>;
|
||||||
```
|
```
|
||||||
|
|
||||||
Returns a `BootstrapCapableStore` from `@ocas/core`. The store loads existing `.bin` files on open and migrates or builds the type index on first use.
|
Returns a unified `Store` with `cas`, `var`, and `tag` sub-stores, backed by SQLite. Bootstraps automatically on open.
|
||||||
|
|
||||||
### Example
|
### Example
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import { bootstrap, putSchema } from "@ocas/core";
|
import { putSchema } from "@ocas/core";
|
||||||
import { createFsStore } from "@ocas/fs";
|
import { openStore } from "@ocas/fs";
|
||||||
|
|
||||||
const store = createFsStore("./my-cas-store");
|
const store = await openStore("./my-cas-store");
|
||||||
await bootstrap(store);
|
|
||||||
|
|
||||||
const typeHash = await putSchema(store, {
|
const typeHash = await putSchema(store, {
|
||||||
type: "object",
|
type: "object",
|
||||||
@@ -46,18 +45,6 @@ const hash = await store.put(typeHash, { id: "item-1" });
|
|||||||
console.log(store.has(hash)); // true after restart if same dir
|
console.log(store.has(hash)); // true after restart if same dir
|
||||||
```
|
```
|
||||||
|
|
||||||
### On-disk layout
|
|
||||||
|
|
||||||
```
|
|
||||||
my-cas-store/
|
|
||||||
├── <hash>.bin # CBOR CasNode
|
|
||||||
├── _index/
|
|
||||||
│ └── <typeHash> # newline-separated content hashes
|
|
||||||
└── ...
|
|
||||||
```
|
|
||||||
|
|
||||||
Writes use atomic rename (`<hash>.tmp` → `<hash>.bin`).
|
|
||||||
|
|
||||||
## Internal Structure
|
## Internal Structure
|
||||||
|
|
||||||
| File | Purpose |
|
| File | Purpose |
|
||||||
|
|||||||
Reference in New Issue
Block a user