textus 0.5.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 997772ea1cfaafc9f28bd57eda51cde19911ca527893c658aa6edb1329b1e2e6
-  data.tar.gz: a134c101fedfb2cd84c6cc21ab0522597ee1252cdaeaa84bc1b25bf977676538
+  metadata.gz: e4b96d4cff83e901df4b2871b57f9c86d071b11126fd42e8fc5563abf45ce810
+  data.tar.gz: 6afa20a10f7ddee98b5b4adbf6eb87218725b5eb1c3f7b181b8bcb462d4fff74
 SHA512:
-  metadata.gz: 666ac21f47159341408b2399f9051d0dad0fab406d08f73a83aa468ea245aa211f16b9749ccf80668dbdd304c5125fbd87644c7e16301c890538749c4a1c0b5e
-  data.tar.gz: f15b77854967509b1c4918dd8452557949f5f42ce6e1ebcd928b3225596d36dff043bf47eca632c8f46b8ba29873cd26792a09109430903402a6b52e3ac51d66
+  metadata.gz: 83825a241b91ac10c2024ebdf04ec0f1bb753b8deeded27894fbbbff84f3f654ad6cc4c0faa2bbfcf940b989bc0393d832ae90af837039814fe51e5f7e4c4515
+  data.tar.gz: 57079b174111a5e89637140d53ca83f5c9b0c5f777c270be9833174c3dd11c7f4d8b8039ef30c69c6f85e1dfb9d78c89dab3eb99cd517b32e1cf7af2ce7ded7a

data/CHANGELOG.md

@@ -8,7 +8,110 @@ The **gem version** (`0.x.y`) is distinct from the **protocol version**
 (currently `textus/2`, embedded in every envelope as `protocol`). The protocol
 is additive within a major; a new major would change the wire string.
 
-## [Unreleased]
+## 0.8.1 — Terminology cleanup (2026-05-21)
+
+### Breaking — intro output
+- `textus intro` JSON: the `"extensions"` key is renamed to `"hooks"`. Consumers
+  reading `env["extensions"]` must switch to `env["hooks"]`. Wire protocol
+  remains `textus/2`; envelope shape on read/write is unchanged.
+
+### Internal Ruby renames
+- `Textus::Store#load_extensions` → `Textus::Store#load_hooks`.
+- `Textus::Intro.extensions_for` → `Textus::Intro.hooks_for`.
+- Error string `"failed loading extension <file>"` → `"failed loading hook <file>"`.
+
+### Fixed
+- `textus doctor` `:check`-hook failure hint pointed to `.textus/extensions/`,
+  which has never existed in 0.6+. Now correctly points to `.textus/hooks/`.
+
+### Docs
+- SPEC.md §5.10: "single extension verb" → "single hook verb".
+- Scaffolded `.textus/hooks/README.md` no longer mixes "hook" and "extension"
+  terminology.
+
+## 0.8.0 — Folder restructure & Zeitwerk autoload (2026-05-21)
+
+### Breaking — internal Ruby renames
+Internal Ruby constants renamed. No deprecation aliases; downstream code referencing internals must update directly.
+- `Textus::EventBus` → `Textus::Hooks::Dispatcher`
+- `Textus::HookRegistry` → `Textus::Hooks::Registry`
+- `Textus::BuiltinHooks` → `Textus::Hooks::Builtin`
+- `Textus::Extensions` (module) → `Textus::Hooks::Loader`
+- `Textus::StoreView` → `Textus::Store::View`
+- `Textus::AuditLog` → `Textus::Store::AuditLog`
+- `Textus::ManifestEntry` → `Textus::Manifest::Entry`
+- `Textus::KeyDistance` → `Textus::Key::Distance`
+- `Textus::Path` → `Textus::Key::Path`
+- `Textus::SchemaTools` → `Textus::Schema::Tools`
+- `Textus::CLI::<Verb>` → `Textus::CLI::Verb::<Verb>` (all 23 verbs)
+- `Textus::CLI::<Name>Group` → `Textus::CLI::Group::<Name>` (key, schema, hook)
+- `Textus::Doctor::Check::Extensions` → `Textus::Doctor::Check::Hooks`
+- `Hooks::Registry#initialize` keyword `bus:` renamed to `dispatcher:`.
+
+### Breaking — doctor CLI surface
+- `textus doctor --check=extensions` → `textus doctor --check=hooks`. The check name listed in `ALL_CHECKS` and the SPEC §10.2 enumeration changes from `"extensions"` to `"hooks"`, matching the hook subsystem rename in 0.6.
+- Doctor issue `code` for broken hook files: `extension.load_failed` → `hook.load_failed`.
+- Doctor::Check::Hooks now inspects `.textus/hooks/` (matches `Store#load_extensions`). Previously inspected `.textus/extensions/`, which was the pre-0.6 directory — the check was dead code on any store created with current `textus init`.
+
+### Added
+- `Textus::Entry::Base` — explicit strategy interface for entry formats. Concrete strategies inherit and override.
+- `Textus::Builder::Renderer` — explicit base for output renderers.
+- `Textus::Doctor::Check` — explicit base for doctor checks. Each builtin check (9 total) is now its own file under `lib/textus/doctor/check/`.
+
+### Changed
+- Per-format schema validation moved from `Store::Reader`/`Store::Writer` onto `Entry::Base#validate_against`. Reader/Writer no longer carry a `case mentry.format` switch.
+- `Textus::Doctor` reduced to an orchestrator; the 9 builtin checks live under `Doctor::Check::*`.
+- `lib/textus.rb` switched to Zeitwerk autoload. The manual `require_relative` tree (75 lines) is gone.
+- `lib/textus/builder/renderers/` directory renamed to `renderer/` (singular) to match `Builder::Renderer::*` namespace.
+
+### Migration
+External code referencing the old internal constants must rename. `Textus.hook`, `Textus.with_registry`, the entire CLI surface, and the `textus/2` wire format are unchanged. The published API (`Store`, `Manifest`, `Envelope`, `Etag`, `Role`, `Error` hierarchy, `Builder`, `Doctor`, `Refresh`, `Init`, `CLI.run`) is unchanged.
+
+## 0.7.0 — Reader/Writer split, EventBus, Builder pipeline (2026-05-21)
+
+### Added
+- `Textus::EventBus` is now the publish/subscribe core for lifecycle events. Embedded callers can `store.bus.subscribe(:put, :name) { ... }` outside the `.textus/hooks/` directory. Hook semantics, audit behavior, and the 2-second timeout are unchanged.
+
+### Changed
+- Internal: extracted `Textus::Path` and `Textus::Envelope` value modules; `Manifest`, `Store`, `Staleness`, and `Builder` now share the same path/envelope construction.
+- Internal: split `Textus::Store` into `Store::Reader` and `Store::Writer`. Public API unchanged. `Mover`, `Validator`, and `Staleness` now take explicit collaborators instead of the full store.
+- Internal: removed `Store::Events`; replaced by the bus.
+- Internal: restructured `Textus::Builder` as a step pipeline (`LoadSources → Project → Render → Write`) with one renderer per format (`markdown/text/json/yaml`). Adding a new output format is now a single-file change.
+
+## 0.6.1 — Deprecation cleanup
+
+### Breaking
+- Flat verb aliases promised "removed in 0.6" are now actually removed:
+  - `textus mv` → `textus key mv`
+  - `textus uid` → `textus key uid`
+  - `textus migrate-keys` → `textus key migrate`
+  - `textus schema-init` → `textus schema init`
+  - `textus schema-diff` → `textus schema diff`
+  - `textus schema-migrate` → `textus schema migrate`
+  - `textus schema KEY` (positional) → `textus schema show KEY`
+  - `textus action NAME` → `textus hook run NAME`
+- `Textus::CLI::Action` class renamed to `Textus::CLI::HookRun`; file `cli/action.rb` → `cli/hook_run.rb`.
+- `Textus::CLI::DeprecatedAliasMixin` module deleted (no remaining users).
+- `textus migrate v2` command removed along with `Textus::MigrateV2` module and `Textus::CLI::Migrate` class. The migration was a one-line manifest rewrite (`version: textus/1` → `version: textus/2`); on-disk entry shapes never changed. To upgrade a `textus/1` manifest, edit `.textus/manifest.yaml` directly. `Manifest.load` still detects the old version and prints the exact edit in its error message.
+
+## 0.6.0 — Hook unification
+
+### Breaking
+- Four DSL verbs (`Textus.action`, `Textus.reducer`, `Textus.hook`, `Textus.doctor_check`) collapsed into one: `Textus.hook(event, name, **opts) { ... }`.
+- `ExtensionRegistry` class renamed to `HookRegistry`.
+- `.textus/extensions/` directory renamed to `.textus/hooks/`. No back-compat read.
+- Manifest: `source.action:` → `source.fetch:` (also renames the registry event from `:action` to `:fetch` and the `ManifestEntry#action`/`#action_config` accessors to `#fetch`/`#fetch_config`).
+- Manifest: `projection.reducer:` → `projection.reduce:`.
+- CLI: `textus extension list` → `textus hook list`; output rows keyed by `event`+`mode` instead of `kind`.
+- CLI: `textus put --action=NAME` → `textus put --fetch=NAME`.
+- Pub-sub hooks gain an optional `keys:` glob filter for per-key scoping.
+- Hook signatures standardized: `store:` is now mandatory and first on every hook (`:reduce` previously had no `store:`). Event-specific kwargs follow.
+- `:accept` event renames `pending_key:` → `key:` to match every other lifecycle event.
+- All event names are now verbs in a uniform grammar (RPC verbs `:fetch :reduce :check`; pub-sub verbs `:put :delete :refresh :build :accept`).
+
+### New
+- `EVENTS` metadata table on `HookRegistry` is the single source of truth for event names, argument shapes, return shapes, and failure semantics (rpc vs pubsub).
+- Shape-check at registration: callable kwargs are verified against the EVENTS table at load time; mismatched signatures raise `UsageError` immediately instead of surfacing at fire time.
 
 ## 0.5.0 — Wire protocol `textus/2`; CLI restructure; Store split (breaking)
 

data/README.md

@@ -7,14 +7,14 @@
 
 A context store for codebases that humans and AI agents both have to read and write. Dotted keys, schema-validated entries, role-gated writes, byte-copy publish, an audit log of every change. Built so an agent landing in your repo can run one command (`textus intro`) and know what to read, what to write, and what's off-limits.
 
-Reference implementation in Ruby. Wire format `textus/1`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
+Reference implementation in Ruby. Wire format `textus/2`. SPEC: [`SPEC.md`](SPEC.md). Implementation notes: [`docs/`](docs/).
 
 ## Versioning
 
 Two versions, deliberately independent:
 
-- **Protocol wire string:** `textus/1`. Stable; breaking changes require `textus/2`.
-- **Gem version:** semver, currently `0.2.0`. Gem `0.x.y` and `1.x` both speak `textus/1`.
+- **Protocol wire string:** `textus/2`. Stable; breaking changes require `textus/3`.
+- **Gem version:** semver, currently `0.8.0`. The gem version is decoupled from the protocol string — internal refactors bump the gem; only wire-format changes bump the protocol.
 
 Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 
@@ -45,7 +45,7 @@ You get `.textus/` with all five zone directories, baseline schemas, an empty au
   audit.log           # append-only NDJSON, every write
   schemas/            # YAML field shapes per entry family
   templates/          # mustache templates for derived entries
-  extensions/         # one .rb per action / reducer / hook / doctor_check
+  hooks/              # one .rb per hook
   sentinels/          # publish bookkeeping
   zones/
     canon/            # human-only — identity, voice, decisions
@@ -60,23 +60,25 @@ Manifest `path:` fields are relative to `.textus/zones/`. So `working.network.or
 Read and write:
 
 ```sh
-textus get working.network.org.jane --format=json
-textus list --zone=working --format=json
-echo '{"frontmatter":{"name":"bob","org":"acme"},"body":"hi\n"}' \
-  | textus put working.network.org.bob --as=human --stdin --format=json
-textus stale --zone=derived --format=json
+textus get working.network.org.jane
+textus list --zone=working
+echo '{"_meta":{"name":"bob","org":"acme"},"body":"hi\n"}' \
+  | textus put working.network.org.bob --as=human --stdin
+textus stale --zone=derived
 ```
 
+(All verbs return JSON envelopes by default; pass `--format=json` explicitly if you prefer.)
+
 For the full shape — Claude plugin with agents, skills, commands, pending walkthrough, intake action — see [`examples/claude-plugin/`](examples/claude-plugin/).
 
-## What 0.2 ships
+## What ships today
 
 - **Per-entry formats.** `format: markdown | json | yaml | text` on a manifest entry. `cat .textus/zones/derived/marketplace.json | jq .` works without going through textus — the in-store file *is* the consumer-shaped artifact. Structured outputs carry `_meta` at the top level (`generated_at`, `from`, `template`, `reducer`).
 - **Per-leaf publishing.** Nested entries declare `publish_each: "skills/{basename}/SKILL.md"`. Every leaf byte-copies to its consumer location on `textus build`. No more hand-mirrored `agents/` / `skills/` / `commands/` directories.
 - **Stable identity (`uid:`).** 16-char hex, auto-minted on first `put`, preserved across writes and moves. `textus key mv old.key new.key` renames in place — uid survives, audit row records `from_key`, `to_key`, `uid`. Reorganising a tree no longer breaks references.
 - **Strict key grammar.** `/^[a-z0-9][a-z0-9-]*$/`, max 8 segments × 64 chars. `textus key migrate --dry-run|--write` rewrites existing stores with illegal segments deterministically.
-- **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded extensions, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
-- **`textus doctor`.** Health check across 8 categories: missing schemas/templates, broken extensions, illegal nested keys, sentinel drift, audit log readability. Returns `ok: true` only when nothing is wrong; warnings and info don't flip the bit.
+- **`textus intro`.** One-shot store orientation: zones with writers + purposes, entry families with schemas and publish targets, loaded hooks, write flows per role, the full CLI verb table. The boot signal for any agent — one tool call and it knows your store.
+- **`textus doctor`.** Health check across 9 categories: missing schemas/templates, broken hooks, illegal nested keys, sentinel drift, audit log readability, unowned schema fields, schema violations, and missing manifest files. Returns `ok: true` only when nothing is wrong; warnings and info don't flip the bit.
 - **Actionable hints on every error.** `UnknownKey` carries ranked "did you mean" suggestions. `WriteForbidden` names the role that *would* be allowed. `BadFrontmatter` tells you exactly what to rename. Printed to stderr alongside the JSON envelope on stdout.
 
 Symlink-mode publish was removed; publish is `FileUtils.cp` + sentinel. Sentinels for published files live under `.textus/sentinels/<target_rel>.textus-managed.json` so consumer directories stay clean. Legacy sibling sentinels auto-migrate on next publish.
@@ -89,7 +91,7 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 
 | Verb | Purpose |
 |---|---|
-| `intro` | Store orientation: zones, entries, extensions, write flows, CLI map |
+| `intro` | Store orientation: zones, entries, hooks, write flows, CLI map |
 | `list [--prefix=K] [--zone=Z]` | Enumerate keys |
 | `where K` | Resolve a key to its filesystem path |
 | `get K` | Full envelope (frontmatter, body, uid, etag, format) |
@@ -98,14 +100,14 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 | `deps K` / `rdeps K` | Forward / reverse projection dependencies |
 | `published` | List `publish_to:` targets and their backing keys |
 | `doctor --check=schema_violations` | Validate every entry against its schema |
-| `extension list [--kind=K]` | Registered actions, reducers, hooks, doctor_checks |
+| `hook list [--event=E]` | Registered hooks grouped by event (fetch, reduce, check, put, delete, refresh, build, accept) |
 
 **Write:**
 
 | Verb | Role |
 |---|---|
 | `put K --stdin --as=R [--action=NAME]` | per zone |
-| `extension run NAME [--key=val] [--as=R]` | per zone written (invoke a registered action) |
+| `hook run NAME [--key=val] [--as=R]` | per zone written (invoke a registered fetch hook) |
 | `delete K --if-etag=E --as=R` | per zone |
 | `refresh K --as=script` | per zone (typically `script`) |
 | `key mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
@@ -128,8 +130,6 @@ All verbs accept `--format=json` and return the envelope defined in SPEC §8. Wr
 | `schema diff NAME` | Compare a schema against entries that claim it |
 | `schema migrate NAME [--rename=OLD:NEW]` | Rewrite frontmatter keys across affected entries |
 
-**Deprecated (removed in 0.6):** `mv`, `uid`, `migrate-keys`, `schema-init`, `schema-diff`, `schema-migrate`, `extensions`, `action`.
-
 ## Zones and roles
 
 | Zone | `writable_by` | Purpose |
@@ -148,16 +148,24 @@ Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`,
 
 `publish_to: [path]` byte-copies a single derived file to one target. `publish_each: "template/{basename}.md"` on a nested entry byte-copies every leaf to its templated target — substitutes `{leaf}`, `{basename}`, `{key}`, `{ext}`. Sentinels for every published file live under `.textus/sentinels/`. See SPEC §5.2, §5.3, §5.12.
 
-## Extensions
+## Extension points
+
+textus exposes one DSL verb:
+
+```ruby
+Textus.hook(event, name, **opts) { |args| ... }
+```
+
+Drop `.rb` files into `.textus/hooks/`. Events:
 
-Four DSL verbs, registered in `.textus/extensions/*.rb`. Each `Store` gets its own registry — no global state.
+- `:fetch` — bring bytes in from elsewhere (returns `{frontmatter:, body:}`)
+- `:reduce` — transform rows during projection (returns rows)
+- `:check` — custom doctor check (returns issues)
+- `:put`, `:delete`, `:refresh`, `:build`, `:accept` — react to lifecycle events
 
-- **`Textus.action(:name) do |config:, store:, args:|`** — runs in three invocation modes (intake refresh, `textus action` verb, `put --action`). Returns `{frontmatter:, body:}`, `{content:}`, or `{body:}` when its return is consumed (intake and put-fetch); writes via `store.put` for side-effectful work (verb mode). The store normalizes all three return shapes. Configured via `source.action` in the manifest for intake. Five built-ins ship: `json`, `csv`, `markdown-links`, `ical-events`, `rss`.
-- **`Textus.reducer(:name) do |rows:, config:|`** — shapes rows in a derived projection. Pure function. Configured via `projection.reducer`. May return an Array (templated builds) or a Hash (templateless json/yaml).
-- **`Textus.hook(:event, :name) do |kwargs|`** — fires on `:put`, `:delete`, `:refresh`, `:build`, or `:accept`. In-process; 2 s timeout per hook; failures land in the audit log as `event_error` rows.
-- **`Textus.doctor_check(:name) do |store:|`** — contributes whole-tree validators to `textus doctor`. Returns an array of issue hashes `{code, level, subject, message, fix}` that merge into the doctor report. Timeouts and exceptions surface as `doctor_check.*` issues; they do not abort the doctor run.
+See SPEC.md §5.10 for the full contract.
 
-Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8 and §5.11.
+Schemas (`.textus/schemas/<name>.yaml`) declare field shapes, per-field `maintained_by:` ownership, and an `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). Full contract in SPEC §5.8.
 
 ## Examples