From c4d9205eb2944942e8d28feb7f886335a519aedc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E5=A2=A8?= Date: Wed, 3 Jun 2026 23:21:30 +0000 Subject: [PATCH] docs: update all documentation for node:sqlite, pnpm, proman workflow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- .cards/cli.md | 2 +- .cards/store.md | 2 +- CLAUDE.md | 50 ++++++++--------------------------------- README.md | 22 +++++++++--------- docs/sync-readme.md | 8 +++---- packages/cli/README.md | 8 +++---- packages/core/README.md | 4 ++-- packages/fs/README.md | 27 ++++++---------------- 8 files changed, 40 insertions(+), 83 deletions(-) diff --git a/.cards/cli.md b/.cards/cli.md index 4726aed..1ef8c91 100644 --- a/.cards/cli.md +++ b/.cards/cli.md @@ -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` | | 3 | Default | `~/.ocas` | -The variable database lives at `/variables.db` by default, overridable with `--var-db `. +The SQLite database lives at `/_store.db`. ## Commands diff --git a/.cards/store.md b/.cards/store.md index cc537bd..4e0bd42 100644 --- a/.cards/store.md +++ b/.cards/store.md @@ -53,7 +53,7 @@ In-memory `Map`. Used in tests and for ephemeral computation (e.g ### 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 2. Runs [[Bootstrap]] automatically diff --git a/CLAUDE.md b/CLAUDE.md index b2ce255..b0772e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,7 @@ Monorepo with 3 packages under `packages/`: - **Test:** Vitest (`npx vitest run`) - **Package Manager:** pnpm (workspace) - **Lint/Format:** Biome (`biome check .` / `biome format --write .`) -- **Publish:** Changesets + `pnpm publish` → npmjs (`@ocas/*`) +- **Publish:** @shazhou/proman (`proman bump` + `proman publish`) ## Commands @@ -98,10 +98,7 @@ This is resolved to real version numbers only during publishing (see below). ## Release Process -Releases use a **release branch** workflow with three phases: prepare → candidate → finalize. - -`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. +Uses `@shazhou/proman` for releases. No release branches needed. ### Adding a Changeset @@ -110,7 +107,7 @@ Add changesets alongside feature PRs on `main`: ```markdown --- -"@ocas/cli": patch +"@ocas/fs": minor --- Description of the change @@ -119,44 +116,15 @@ Description of the change Changesets live in `.changeset/` as markdown files. Bump types: `patch` / `minor` / `major`. One changeset can cover multiple packages. -### Phase 1: Prepare (cut release branch) +### Release Steps -- **Precondition:** on `main`, clean tree, `.changeset/` has pending changesets -- **Steps:** - 1. Determine target version (from changeset bump types or manually) - 2. `git checkout -b release/` - 3. Fix `workspace:*` → real version numbers in all `package.json` - 4. Commit -- **Does NOT** run `changeset version`, does NOT write CHANGELOG +1. `proman bump` — consume changesets and bump versions +2. `proman publish` — build → test → check → publish → changelog → tag → push -### Phase 2: Candidate (publish rc for validation) - -- **Precondition:** on `release/*` branch -- **Steps:** - 1. Set version to `-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 `` (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` - 6. Merge back to `main` (CHANGELOG comes along) - 7. Restore `workspace:*` on `main` - 8. Delete release branch +The publish command handles everything: workspace dependency resolution, npm publish order (core → fs → cli), changelog generation, git tagging, and pushing. ### Key Rules - **Publish order** is always `@ocas/core` → `@ocas/fs` → `@ocas/cli` -- **`workspace:*`** must be fixed before any publish — `pnpm publish` does NOT auto-replace them -- **CHANGELOG** only contains official releases, never rc entries -- **Changesets added on release branch** (bug fixes during rc) are consumed together at finalize +- **`workspace:*`** is auto-resolved by pnpm during publish +- **CHANGELOG** only contains official releases diff --git a/README.md b/README.md index f757bc7..9bc5b91 100644 --- a/README.md +++ b/README.md @@ -7,11 +7,13 @@ Every node has a typed payload: its `type` field is the hash of a JSON Schema th ## Install ```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. +> Requires Node.js >= 22.5.0 (uses built-in node:sqlite) + ## Quick Start ```bash @@ -190,8 +192,8 @@ Nodes reachable from any variable binding are kept; everything else is swept. ## Using as a Library ```bash -bun add @ocas/core # in-memory store -bun add @ocas/core @ocas/fs # + filesystem persistence +pnpm add @ocas/core # in-memory store +pnpm add @ocas/core @ocas/fs # + filesystem persistence ``` ```typescript @@ -214,9 +216,9 @@ const node = store.get(hash); For filesystem persistence, use `@ocas/fs`: ```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: @@ -228,11 +230,11 @@ See individual package READMEs for full API docs: ```bash git clone && cd ocas -bun install --no-cache -bun run build # tsc --build -bun test # run all tests -bun run check # biome lint -bun run format # biome format +pnpm install +pnpm run build # tsc --build +pnpm test # run all tests +pnpm run check # biome lint +pnpm run format # biome format ``` ## License diff --git a/docs/sync-readme.md b/docs/sync-readme.md index 8d908d0..4e869f3 100644 --- a/docs/sync-readme.md +++ b/docs/sync-readme.md @@ -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) 5. **Quick Start** — install, build, basic usage 6. **CLI Reference** — brief command list, detailed usage in cli README -7. **Development** — bun install / build / check / test -8. **Publishing** — changeset workflow (bun run release) +7. **Development** — pnpm install / build / check / test +8. **Publishing** — `proman bump` + `proman publish` ## Per-Package README Structure @@ -27,7 +27,7 @@ Each package README should have: 1. **Title** — package name 2. **One-line description** — matching package.json 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 6. **CLI Usage** (cli packages) — command reference with examples 7. **Internal Structure** — brief src/ file organization @@ -57,7 +57,7 @@ For each package read: - All relative links work - Package names match package.json - No references to removed/renamed packages -- bun run build still passes +- pnpm run build still passes ## Guidelines diff --git a/packages/cli/README.md b/packages/cli/README.md index ed0652a..7676e2b 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -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: ```bash -bun add -g @ocas/cli +pnpm add -g @ocas/cli # 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: ```bash -bun packages/cli-ocas/src/index.ts [args] +node packages/cli/dist/index.js [args] ``` ## CLI Usage diff --git a/packages/core/README.md b/packages/core/README.md index eadf61f..0697055 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -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. -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` ## Installation ```bash -bun add @ocas/core +pnpm add @ocas/core ``` ## API diff --git a/packages/fs/README.md b/packages/fs/README.md index 8d8bef1..3ad70e2 100644 --- a/packages/fs/README.md +++ b/packages/fs/README.md @@ -4,7 +4,7 @@ Filesystem-backed CAS store. ## Overview -`@ocas/fs` implements a persistent `Store` on disk. Each node is stored as `.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. @@ -13,7 +13,7 @@ Depends on `@ocas/core` for hashing, CBOR encoding, and types. ## Installation ```bash -bun add @ocas/fs +pnpm add @ocas/fs ``` ## API @@ -21,19 +21,18 @@ bun add @ocas/fs Exported from `src/index.ts`: ```typescript -function createFsStore(dir: string): BootstrapCapableStore; +function openStore(path: string): Promise; ``` -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 ```typescript -import { bootstrap, putSchema } from "@ocas/core"; -import { createFsStore } from "@ocas/fs"; +import { putSchema } from "@ocas/core"; +import { openStore } from "@ocas/fs"; -const store = createFsStore("./my-cas-store"); -await bootstrap(store); +const store = await openStore("./my-cas-store"); const typeHash = await putSchema(store, { 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 ``` -### On-disk layout - -``` -my-cas-store/ -├── .bin # CBOR CasNode -├── _index/ -│ └── # newline-separated content hashes -└── ... -``` - -Writes use atomic rename (`.tmp` → `.bin`). - ## Internal Structure | File | Purpose |