xiaoju
b89e31f468
Implements RFC-31 Phase 1 - refactors the Variable model to use a composite
primary key of (name, schema) instead of the previous ULID id + scope approach.
Key changes:
1. **Type Model**:
- Removed `id: VariableId` and `scope: string` fields
- Added `name: string` as part of composite key with `schema: Hash`
- Variables with same name but different schemas are now distinct entities
2. **Database Schema**:
- Changed primary key from `id` to `(name, schema)`
- Updated foreign keys in `variable_tags` and `variable_labels` tables
- Replaced scope-based indexes with name-based indexes
- Enabled foreign key constraints for proper cascade deletes
3. **CRUD Operations** - all methods updated to use `(name, schema)`:
- `create(name, value, options)` - validates unique (name, schema)
- `get(name, schema)` - retrieves by composite key
- `update(name, schema, value)` - updates with schema validation
- `delete(name, schema)` - deletes with cascade to tags/labels
- `list({ namePrefix?, schema?, tags?, labels? })` - filters by name prefix and schema
- `tag(name, schema, operations)` - manages tags/labels by composite key
4. **Error Types**:
- New: `VariableDuplicateError` for duplicate `(name, schema)` pairs
- New: `InvalidVariableNameError` for empty names
- Removed: `InvalidScopeError` (no longer needed)
- Updated: `VariableNotFoundError` to reference `(name, schema)`
5. **GC Adaptation**:
- Garbage collection works correctly with refactored model
- Preserves nodes referenced by variables across all schemas
- Global collection across all variable names and schemas
6. **Tests**:
- Added comprehensive test suite covering all new functionality
- Database schema validation tests
- CRUD operation tests with composite keys
- Multi-schema scenarios (same name, different schemas)
- Tag/label management tests
- GC integration tests
- End-to-end workflow tests
7. **Breaking Changes**:
- This is a backward-incompatible change
- CLI commands will need updates in a future phase (out of scope for Phase 1)
- Data migration is out of scope for Phase 1
Fixes #32
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@uncaged/cli-json-cas
CLI tool for json-cas stores.
Overview
@uncaged/cli-json-cas provides the json-cas command for managing a filesystem-backed store: bootstrap, schema registration, node CRUD, integrity checks, reference listing, and graph walks. It uses @uncaged/json-cas-fs for persistence and @uncaged/json-cas for core operations.
Dependencies: @uncaged/json-cas, @uncaged/json-cas-fs
Installation
Published as an npm package with a binary entry:
bun add -g @uncaged/cli-json-cas
# or from the monorepo workspace:
bun link
Binary name: json-cas (points to src/index.ts, run with Bun).
In development:
bun packages/cli-json-cas/src/index.ts <command> [args]
CLI Usage
Usage: json-cas [--store <path>] [--json] <command> [args]
Global flags
| Flag | Description |
|---|---|
--store <path> |
Store directory (default: ~/.uncaged/json-cas) |
--json |
Compact JSON output for commands that print JSON |
Commands
| Command | Description |
|---|---|
init |
Create store directory and write bootstrap seed; prints meta hash |
bootstrap |
Write meta-schema seed into existing store; prints hash |
schema put <file.json> |
Register schema from file; prints type hash |
schema get <type-hash> |
Print schema JSON |
schema list |
List all schemas (hash name) |
schema validate <hash> |
Validate node against its schema; prints valid / invalid |
put <type-hash> <file.json> |
Store node; prints content hash |
get <hash> |
Print full node as JSON |
has <hash> |
Print true or false |
verify <hash> |
Verify integrity; prints ok or corrupted |
refs <hash> |
Print direct cas_ref targets (one per line) |
walk <hash> |
BFS traversal; one hash per line |
walk <hash> --format tree |
Tree-formatted traversal |
hash <type-hash> <file.json> |
Compute hash without storing |
cat <hash> |
Print node JSON |
cat <hash> --payload |
Print payload only |
Examples
# Initialize default store at ~/.uncaged/json-cas
json-cas init
# Use a custom store path
json-cas --store ./data/cas bootstrap
# Register a schema and store a payload
json-cas schema put ./schemas/item.json
# → prints type hash, e.g. 0123456789ABCD
json-cas put 0123456789ABCD ./payloads/item.json
# → prints content hash
json-cas get <content-hash> --json
json-cas verify <content-hash>
json-cas walk <content-hash> --format tree
Internal Structure
| File | Purpose |
|---|---|
index.ts |
Argument parsing, command dispatch, and all CLI logic |
There is no separate src/ module tree; the CLI is a single entry file. Tests (if present) are co-located under the package.
Configuration
| Setting | Default | Override |
|---|---|---|
| Store directory | ~/.uncaged/json-cas |
--store <path> |
No config file is read; all behavior is controlled via flags and command arguments.