Skip to content

Add a kb create command to provision new KB stores #720

Description

@williamthorsen

Problem

@codeassembly/kb can validate and manage stores but cannot create one. The only provisioning today is provision-codeassembly-event-store.sh, a bespoke bash script hardcoded to a single store (codeassembly) and living in a consumer package rather than the library. "Copy the script and edit the hardcoded name" is exactly the drift-prone pattern this effort exists to remove, and the script has already drifted from the package: it installs a schema template that diverges from the package's own defaultSchema (with extra event fields no code reads), and it registers stores with hand-rolled awk/grep that requires kbs: to be the last top-level key.

Context

The package already holds the canonical sources a create command needs:

  • defaultSchema is the bundled schema every store inherits when it declares no .kb/schema.yaml; the static template under agents/templates/ is a second, drifted copy.
  • defaultKbConfig supplies the effective .kb/config.yaml defaults; config.yaml field-merges, so a store works with the file absent.
  • tag-aliases.yaml is optional and additive; absent, it loads as an empty map.
  • The kb.yaml registry has a typed schema and loader but no write path — registration is genuinely new.

A store's .kb/schema.yaml replaces the bundled default outright (no merge), so a store that wants to customize its schema needs the full default in hand to edit. That is why kb create materializes a schema seed rather than leaving the store to inherit silently. The generic kb-* skills hardcode the record types and required fields they read and write, so the materialized seed must faithfully reproduce the default record types; validating edited schemas against that skill contract is tracked separately in #746.

Two layout facts constrain the scaffold: capture-event writes events to a fixed content/events/, while kb-add writes assertions to an agent-chosen topical folder under content/. There is no content/assertions/ convention.

Proposed solution

Add a kb create command, available as both a CLI subcommand and a library export consistent with check, that scaffolds a new store in the current directory and registers it:

  • Scaffold .kb/schema.yaml (serialized from defaultSchema, with a header explaining the override-and-inherit contract and warning against removing the default record types or required fields), .kb/config.yaml (a fully-commented stub whose documented defaults are rendered from defaultKbConfig), .kb/tag-aliases.yaml (an empty aliases: {} skeleton with guidance), and the content/ and content/events/ directories. Stub values are generated from the in-package constants so they cannot drift.
  • Register the store in ~/.agents/kb.yaml through kb-core's registry schema, preserving existing comments. The name defaults to the directory name; --name overrides it and --no-register scaffolds without registering.
  • Refuse to clobber: an existing .kb/ or an already-registered name is an error, not an overwrite. No --force for now.
  • Retire the bespoke script and the drifted template: delete provision-codeassembly-event-store.sh and the agents/templates/codeassembly-event-store/ template, whose behavior kb create now covers from the package's canonical sources.

Dropped from the original scope: parameterizing the schema by record-type set (no current store needs a restricted vocabulary; an over-broad schema is inert, and the "both" case is just the inherited default), and scaffolding a .kb/templates/ directory (no code reads it).

Acceptance criteria

Must have

  • kb create scaffolds a new store: .kb/schema.yaml, .kb/config.yaml, .kb/tag-aliases.yaml, and the content/ and content/events/ directories.
  • The scaffolded schema.yaml, config.yaml, and tag-aliases.yaml are generated from the in-package constants and parse back to defaultSchema, defaultKbConfig, and an empty alias map respectively.
  • The store is registered in ~/.agents/kb.yaml through kb-core's registry schema, preserving existing comments; --name and --no-register are supported.
  • kb create refuses to clobber: an existing .kb/ or an already-registered name produces an error rather than an overwrite.
  • provision-codeassembly-event-store.sh and the agents/templates/codeassembly-event-store/ template are removed.
  • kb create is available as both a CLI subcommand and a library export, consistent with check.
  • New and modified behavior is covered by tests.
  • kb help text and the package README document kb create, its flags, and the scaffolded layout.

Dependencies

Metadata

Metadata

Labels

featureAdded or improved external functionalityscope:kb

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions