RubyGems - textus - Versions diffs - 0.2.0 → 0.4.0 - Mend

textus 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (18) hide show

checksums.yaml +4 -4
data/CHANGELOG.md +30 -0
data/README.md +80 -97
data/SPEC.md +46 -26
data/lib/textus/{builtin_fetchers.rb → builtin_actions.rb} +11 -6
data/lib/textus/cli.rb +55 -11
data/lib/textus/doctor.rb +41 -1
data/lib/textus/extension_registry.rb +22 -9
data/lib/textus/extensions.rb +6 -2
data/lib/textus/init.rb +5 -4
data/lib/textus/intro.rb +9 -7
data/lib/textus/manifest.rb +10 -4
data/lib/textus/refresh.rb +14 -13
data/lib/textus/store.rb +14 -4
data/lib/textus/store_view.rb +11 -2
data/lib/textus/version.rb +1 -1
data/lib/textus.rb +1 -1
metadata +2 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '092917d22f25afea72145540f4dc8ce32e5a4f6c65889564f54e258e52eab7df'
-  data.tar.gz: 163d891ea50b7c651740f499ffe7ba5191aba0c2c327afbf058a1bf1fc019942
+  metadata.gz: 98c2ce5525bbf9c05ebdb5eeaacde8e208253ee878d7d0722ff192435168f69f
+  data.tar.gz: c16cd5657396884c646331912d988838e0f8ed2002fc76d47cc54383dc434f19
 SHA512:
-  metadata.gz: 1fa336c3387f503c7ac846fea1f7d1de92a9633ea0104d4c0882d48951bf6abbbb1366e0a9028abac1a138f048fe2b90c018228c7b9a19725eb251c835f43b6c
-  data.tar.gz: 2f99647d031c7f0004d4b0264c51a616f8da03bcb72a68f4e12c0e483b5865ee3d826786f7d519bb4d7aac2a8ec9d4f9a1092220ce376a226e1436e9c1e5affc
+  metadata.gz: 7478459f9672474c32f37b59a7134309cf12f6a7455a808c24b6ac717820ff8c8aad5a5187a6dbe5e0c73f98c04296ce95eff2cac8ea75144f559df8cea3fe80
+  data.tar.gz: '08a29e9090f6558a010009e3562a7ec8d6ddf73454bb09b10b5aeaf3def24d9d11905078d62807b8e1f0936b00889a66df8c55d68b7dfc411addd90e60ae1a93'

data/CHANGELOG.md CHANGED Viewed

@@ -10,6 +10,36 @@ is additive within a major; a new major would change the wire string.
 ## [Unreleased]
+## 0.4.0 — Extension API redesign (breaking)
+- **Breaking:** `Textus.fetcher` removed. Use `Textus.action` instead. The block signature changes from `|config:, store:|` to `|config:, store:, args:|`.
+- **Breaking:** Manifest field `source.fetcher` renamed to `source.action`. Legacy field is rejected with a migration error.
+- **Breaking:** CLI flag `textus put --fetcher=NAME` renamed to `textus put --action=NAME`.
+- **Breaking:** `BuiltinFetchers` module renamed to `BuiltinActions`.
+- **Breaking:** Synthesized frontmatter key `fetched_with` renamed to `actioned_with` on `put --action`.
+- **New:** `Textus.action` works in three invocation modes — intake refresh, the new `textus action NAME` verb, and `put --action`. See SPEC §5.11.
+- **New:** `Textus.doctor_check(:name) { |store:| ... }` primitive; contributed checks merge into the doctor report.
+- **New:** `textus action NAME [--key=val ...] [--as=ROLE]` CLI verb for invoking actions in verb mode.
+- **New:** `StoreView` gains a writable mode (`writable: true, as: ROLE`); intake and verb-mode actions receive a writable view bound to the calling role.
+- **New:** `extensions list` enumerates actions and doctor_checks.
+Migration: in every `.textus/extensions/*.rb`, rename `Textus.fetcher(:x)` to `Textus.action(:x)` and add `args:` to the block signature. In every manifest, rename `source.fetcher:` to `source.action:`. In CI/scripts using `textus put --fetcher=`, switch to `--action=`.
+## [0.3.0] — 2026-05-20 — Configurable store root
+### Added
+- `--root <path>` CLI flag and `TEXTUS_ROOT` environment variable for store
+  discovery. `Textus::Store.discover` now accepts an optional `root:` kwarg.
+  Unblocks embedding a textus store at non-default paths (e.g. nested under a
+  plugin directory like `plugins/<name>/.textus/`) where walking up from cwd
+  to find `.textus/` is undesirable or ambiguous.
+### Documentation
+- SPEC.md §3.1 documents the new store-location precedence:
+  1. `--root` / `root:` kwarg, 2. `TEXTUS_ROOT`, 3. cwd walk.
 ## [0.2.0] — 2026-05-20 — Storage rewrite, agent surface, extension DSL (BREAKING)
 This release reshapes textus from a markdown-only frontmatter store into a

data/README.md CHANGED Viewed

@@ -1,8 +1,13 @@
 # textus
-Reference Ruby implementation of the **textus/1** protocol — a storage convention and JSON wire protocol for agent-readable project memory: addressable dotted keys, schema-validated entries (markdown, JSON, YAML, or text per entry), role-gated writes, declarative compute, and copy-based publish targets.
+[![CI](https://github.com/patrick204nqh/textus/actions/workflows/ci.yml/badge.svg)](https://github.com/patrick204nqh/textus/actions/workflows/ci.yml)
+[![Gem Version](https://img.shields.io/gem/v/textus.svg)](https://rubygems.org/gems/textus)
+[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.3-CC342D.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
-See [`SPEC.md`](SPEC.md) for the protocol. Implementation notes live in [`docs/`](docs/).
+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/).
 ## Versioning
@@ -11,12 +16,12 @@ 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`.
-Envelope payloads carry the `protocol` field; the gem version is irrelevant to the wire format.
+Envelope payloads carry the `protocol` field. The gem version is irrelevant to the wire format.
 ## Install
 ```sh
-gem install textus     # when published
+gem install textus
 ```
 Or from this repo:
@@ -28,141 +33,133 @@ bundle exec exe/textus --help
 ## Quick start
-Bootstrap a fresh tree:
 ```sh
-bundle exec exe/textus init
+textus init
 ```
-This scaffolds `.textus/` with a starter manifest, the five zone directories, baseline schemas, and an empty audit log. The resulting layout:
+You get `.textus/` with all five zone directories, baseline schemas, an empty audit log, and a starter manifest:
 ```
 .textus/
-  manifest.yaml
-  audit.log
-  role
-  schemas/
-  templates/
-  extensions/
+  manifest.yaml       # zone declarations + key-to-path mapping
+  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
+  sentinels/          # publish bookkeeping
   zones/
-    canon/       # human-only
-    working/     # human, ai, script
-    intake/      # script (declared external inputs)
-    pending/     # ai (proposals awaiting accept)
-    derived/     # build only (computed outputs)
+    canon/            # human-only — identity, voice, decisions
+    working/          # human / ai / script — day-to-day catalog
+    intake/           # script — declared external inputs (actions)
+    pending/          # ai + human — proposals awaiting accept
+    derived/          # build only — computed outputs
 ```
-A minimal `manifest.yaml`:
-```yaml
-version: textus/1
-zones:
-  - { name: canon,   writable_by: [human] }
-  - { name: working, writable_by: [human, ai, script] }
-  - { name: intake,  writable_by: [script] }
-  - { name: pending, writable_by: [ai] }
-  - { name: derived, writable_by: [build] }
-entries:
-  - key: canon.identity
-    path: canon/identity.md
-    zone: canon
-    schema: identity
-  - key: working.network.org
-    path: working/network/org
-    zone: working
-    schema: person
-    owner: textus:network
-    nested: true
-```
-Manifest `path:` fields are relative to `.textus/zones/` — implementations prepend `zones/` when resolving. So `working.network.org.jane` lives at `.textus/zones/working/network/org/jane.md`.
+Manifest `path:` fields are relative to `.textus/zones/`. So `working.network.org.jane` lives at `.textus/zones/working/network/org/jane.md`.
 Read and write:
 ```sh
 textus get working.network.org.jane --format=json
 textus list --zone=working --format=json
-echo '{"frontmatter":{"name":"bob","relationship":"peer","org":"acme"},"body":"hi\n"}' \
+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
 ```
+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
+- **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 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 migrate-keys --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.
+- **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.
 ## CLI verbs
-All verbs accept `--format=json` and emit the envelope defined in SPEC §8. Write verbs require `--as=<role>` (subject to role-resolution order, §5.1).
+All verbs accept `--format=json` and return the envelope defined in SPEC §8. Write verbs require `--as=<role>` (role resolution: `--as` → `TEXTUS_ROLE` env → `.textus/role` file → default `human`).
-**Read verbs (no role required):**
+**Read:**
 | Verb | Purpose |
 |---|---|
-| `list [--prefix=K] [--zone=Z] [--stale]` | Enumerate keys, optionally filtered |
+| `intro` | Store orientation: zones, entries, extensions, write flows, CLI map |
+| `list [--prefix=K] [--zone=Z]` | Enumerate keys |
 | `where K` | Resolve a key to its filesystem path |
-| `get K` | Return the full envelope |
-| `schema K` | Return the schema bound to an entry |
-| `stale [--prefix=K] [--zone=Z] [--strict]` | List stale derived/intake entries |
-| `deps K` / `rdeps K` | Forward/reverse projection dependencies |
+| `get K` | Full envelope (frontmatter, body, uid, etag, format) |
+| `schema K` | Schema bound to an entry |
+| `stale [--prefix=K] [--zone=Z]` | List stale derived/intake entries |
+| `deps K` / `rdeps K` | Forward / reverse projection dependencies |
 | `published` | List `publish_to:` targets and their backing keys |
-| `validate-all` | Validate every entry against its schema (incl. `maintained_by`) |
-| `extensions list [--kind=K]` | Enumerate registered fetchers, reducers, and declared hooks |
+| `validate-all` | Validate every entry against its schema |
+| `extensions list [--kind=K]` | Registered actions, reducers, hooks, doctor_checks |
-**Write verbs (role-gated per zone):**
+**Write:**
 | Verb | Role |
 |---|---|
-| `put K --stdin --as=R [--fetcher=NAME]` | per zone |
+| `put K --stdin --as=R [--action=NAME]` | per zone |
+| `action NAME [--key=val] [--as=R]` | per zone written (invoke a registered action) |
 | `delete K --if-etag=E --as=R` | per zone |
 | `refresh K --as=script` | per zone (typically `script`) |
+| `mv old new --as=R [--dry-run]` | per zone (same-zone moves; uid preserved) |
 | `build [--prefix=K] [--dry-run]` | `build` |
 | `accept K --as=human` | `human` only |
+**Health & maintenance:**
+| Verb | Purpose |
+|---|---|
+| `doctor` | 8 health checks; `ok: true` when clean |
+| `migrate-keys [--dry-run]` | Rename files whose basenames violate the strict key grammar |
 **Scaffolding (human-only):**
 | Verb | Purpose |
 |---|---|
-| `init` | Scaffold a fresh `.textus/` tree |
-| `schema-init NAME` | Write a stub schema |
-| `schema-diff NAME` | Compare on-disk schema against entries claiming it |
+| `init` | Scaffold a fresh `.textus/` |
+| `schema-init NAME` | Stub a schema |
+| `schema-diff NAME` | Compare a schema against entries that claim it |
 | `schema-migrate NAME [--rename=OLD:NEW]` | Rewrite frontmatter keys across affected entries |
 ## Zones and roles
 | Zone | `writable_by` | Purpose |
 |---|---|---|
-| `canon` | `[human]` | Identity, voice, immutable principles |
-| `working` | `[human, ai, script]` | Active project state — notes, decisions, network |
-| `intake` | `[script]` | Declared external inputs (calendar, feeds, scraped pages) |
-| `pending` | `[ai]` | AI proposals awaiting `textus accept` |
+| `canon` | `[human]` | Identity, voice, decisions — slow-changing |
+| `working` | `[human, ai, script]` | Active project state |
+| `intake` | `[script]` | Declared external inputs (actions) |
+| `pending` | `[ai, human]` | AI proposals; humans run `textus accept` to apply |
 | `derived` | `[build]` | Computed outputs from `textus build` |
-The effective role for any CLI call is resolved in order: `--as` flag, then `TEXTUS_ROLE` env, then `.textus/role`, then default `human`. Mismatches return `write_forbidden`. Every write records the resolved role in `.textus/audit.log`.
-## Compute layer
+Mismatches return `write_forbidden` with a hint naming the role that *would* be allowed. Every write records the resolved role in `.textus/audit.log`.
-Derived entries are not authored by hand. Each declares a `projection:` block (select prefixes, pluck fields, optional sort/limit/transform) and optionally a Mustache template under `.textus/templates/`. textus implements a deliberately restricted Mustache subset (variables, sections, inverted sections, comments — no partials, no lambdas, no HTML escaping). Results are bounded at 1000 rows; template recursion at depth 8.
+## Compute and publish
-Derived entries may declare `format:` to be `markdown` (default), `json`, `yaml`, or `text`. The in-store file is the consumer-shaped artifact — `cat .textus/zones/derived/marketplace.json` returns valid JSON without going through textus. `publish_to:` then performs a byte-for-byte file copy of that artifact to each destination, alongside a `.textus-managed.json` sentinel. See SPEC §5.2, §5.3, and §5.12.
+Derived entries declare a `projection:` (`select`, `pluck`, `sort_by`, `limit`, optional `reducer`) and either a template under `.textus/templates/` (markdown/text) or a templateless path that lets a reducer shape the output directly (json/yaml). Projections cap at 1000 rows; the vendored Mustache subset caps at depth 8. No partials, no lambdas, no HTML escaping.
-## Extension points
+`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.
-Three DSL verbs:
+## Extensions
-- **`Textus.fetcher(:name) do |config:, store:|`** — pulls data into an intake entry. Returns one of `{ frontmatter:, body: }`, `{ content: }` (for `format: json|yaml` entries), or `{ body: }` (raw bytes); the store normalizes all three. Configured via `source.fetcher` in the manifest. Five built-ins ship out of the box: `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`.
-- **`Textus.hook(:event, :name) do |kwargs|`** — reacts to a lifecycle event. Five events: `:put`, `:delete`, `:refresh`, `:build`, `:accept`.
+Four DSL verbs, registered in `.textus/extensions/*.rb`. Each `Store` gets its own registry — no global state.
-Extension files live in `.textus/extensions/*.rb` (one per registration, by convention). Each Store instance gets its own registry; no global state.
+- **`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.11 for the full contract.
-Schema fields may also declare `maintained_by:` and a top-level `evolution:` block (`added_in`, `deprecated_at`, `migrate_from`). SPEC §5.8.
+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.
 ## Examples
-- [`examples/claude-plugin/`](examples/claude-plugin/) — full tour: fetcher, reducer, lifecycle events, schema ownership, and a `derived.claude.root` entry published to `CLAUDE.md`.
-- [`examples/mcp-server/`](examples/mcp-server/) — 50-line MCP server wrapping `textus get/put` as tools.
+[`examples/claude-plugin/`](examples/claude-plugin/) — a Claude Code plugin (`voice-tools`) whose entire content surface — agents, skills, commands, `CLAUDE.md`, `plugin.json`, `marketplace.json` — is textus-managed. Demonstrates per-entry formats, `publish_each`, intake actions, in-process reducers and hooks, the AI-propose / human-accept loop, and the `inject_intro:` flag that puts an orientation preamble at the top of `CLAUDE.md`.
 ## Tests
@@ -170,7 +167,7 @@ Schema fields may also declare `maintained_by:` and a top-level `evolution:` blo
 bundle exec rspec
 ```
-Runs the full suite, including conformance fixtures A–I from SPEC §12.
+240 examples; includes conformance fixtures A–I from SPEC §12.
 ## Code quality
@@ -179,21 +176,7 @@ bundle exec rubocop      # lint
 bundle exec rubocop -A   # lint + autocorrect
 ```
-Git hooks via [Lefthook](https://github.com/evilmartians/lefthook):
-```sh
-brew bundle install      # installs lefthook (see Brewfile)
-lefthook install         # writes .git/hooks/{pre-commit,pre-push}
-```
-Git hooks (defined in `lefthook.yml`):
-- `pre-commit` — runs `rubocop` on staged Ruby files.
-- `pre-push` — runs the full `rspec` suite and `rubocop` over the tree.
-Bypass with `LEFTHOOK=0 git commit ...` when needed.
-CI runs `rspec` (Ruby 3.3 / 3.4) and `rubocop` via GitHub Actions
-([`.github/workflows/ci.yml`](.github/workflows/ci.yml)).
+Lefthook hooks (`brew bundle install` then `lefthook install`) run rubocop on `pre-commit` and `rspec + rubocop` on `pre-push`. Bypass with `LEFTHOOK=0 git commit ...` when needed. CI runs `rspec` (Ruby 3.3 / 3.4) and `rubocop` via GitHub Actions.
 ## License

data/SPEC.md CHANGED Viewed

@@ -46,7 +46,7 @@ textus is organized as five composable layers. Each layer has a single responsib
 - Not a sync protocol. Single-writer per file, ETag-checked.
 - Not a transport. Spawn the CLI or wrap it in MCP/HTTP downstream.
 - Not a UI. Filesystem + CLI. Viewers ship elsewhere.
-- Not a fetcher. textus declares sources; external runners fetch them.
+- Not a fetcher. textus declares sources; external runners invoke actions to materialize them.
 - Not an executor. textus computes pure projections but never spawns shell commands.
 ## 3. Storage layout
@@ -75,6 +75,16 @@ Zone directories under `zones/` are conventional; their write semantics are decl
 `.textus/audit.log` is an append-only NDJSON file written under a file lock by every successful `put`, `delete`, `accept`, and `build`. `.textus/role` (one line containing a role name) is optional and participates in the role-resolution order (§5).
+### 3.1 Store location precedence (v0.3)
+Implementations MUST resolve the store root in this order; the first match wins:
+1. `--root <path>` flag passed to the CLI (or `root:` kwarg to `Store.discover`).
+2. `TEXTUS_ROOT` environment variable.
+3. Walk up from cwd looking for a `.textus/` directory containing `manifest.yaml`.
+When (1) or (2) names a path that has no `manifest.yaml`, the CLI exits with `io_error` and a message naming the resolved absolute path. When (3) reaches the filesystem root without finding a store, the CLI exits with `io_error` naming the search start point.
 ## 4. Manifest
 The manifest declares: (a) which zones exist and which roles may write to each, (b) the key-to-subtree mapping, (c) the schema applied to entries in each subtree, and (d) the owner string recorded in writes.
@@ -240,38 +250,38 @@ A sentinel is written for each published file at `<store_root>/sentinels/<target
 **Per-leaf publishing.** A nested entry MAY declare `publish_each:` instead of `publish_to:` (see §4). When the build runs, every leaf reachable under the nested entry is byte-copied to the path produced by substituting `{leaf}` / `{basename}` / `{key}` / `{ext}` in the template, with a sentinel written under `<store_root>/sentinels/` at the mirrored target path. The build envelope grows a `published_leaves` array — one row per leaf, with `key`, `source`, and `target` — alongside the existing `built` array. Targets that would resolve outside the repo root are refused.
-### 5.4 Intake (declared, refreshed via registered fetcher)
+### 5.4 Intake (declared, refreshed via registered action)
-Intake entries declare an external source by naming a **fetcher** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: a fetcher only runs when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
+Intake entries declare an external source by naming an **action** — a registered, named function that pulls data into the entry. textus itself still makes no implicit network calls: an action only runs in intake mode when explicitly invoked by `textus refresh KEY --as=script`. The declaration is data only:
 ```yaml
 - key: intake.calendar.events
   zone: intake
   source:
-    fetcher: ical-events
+    action: ical-events
     config:
       url: "https://calendar.google.com/.../basic.ics"
     ttl: 6h
 ```
-`fetcher` names a registered fetcher; `config` is an opaque hash handed to the fetcher; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from` and `source.parse` with a clear usage error.
+`action` names a registered action; `config` is an opaque hash handed to the action; `ttl` is the staleness budget. Implementations MUST reject legacy `source.from`, `source.parse`, and `source.fetcher` with a clear usage error.
-**Fetcher contract.** A fetcher is registered via `Textus.fetcher(:name) do |config:, store:| ... end` and MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
+**Action contract (intake mode).** An action is registered via `Textus.action(:name) do |config:, store:, args:| ... end`. In intake mode the action MUST return one of three shapes, all normalized by the store into its internal `{frontmatter, body, content}` representation (§5.12):
-- `{ frontmatter:, body: }` — markdown-friendly (current shape).
+- `{ frontmatter:, body: }` — markdown-friendly.
 - `{ content: }` — for `format: json|yaml` entries; the parsed object becomes the entry's content.
 - `{ body: }` — raw bytes for `text` or for any format that prefers verbatim writes; the store re-parses and validates per `format:`.
-The `store:` argument is a read-only `Textus::StoreView` (§5.11). Every fetcher call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
+The `store:` argument is a writable `Textus::StoreView` (§5.11) bound to the calling role; the `args:` argument is `{}` in intake mode (it carries CLI flags in verb mode — §5.11). Every action call is wrapped in `Timeout.timeout(2)`; exceptions and timeouts surface as `usage` errors that abort the refresh.
-**Built-in fetchers.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer fetcher) is responsible for supplying bytes.
+**Built-in actions.** `json`, `csv`, `markdown-links`, `ical-events`, `rss` are always available. They expect raw bytes in `config["bytes"]` and produce structured frontmatter/body. Built-ins do not perform I/O themselves — the caller (or an outer action) is responsible for supplying bytes.
 **Refresh paths.** Two are supported:
-1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.fetcher`, invokes it with `(config:, store:)`, and writes the result under role `script`.
+1. **In-process** — `textus refresh KEY --as=script` resolves the entry's `source.action`, invokes it with `(config:, store:, args: {})`, and writes the result under role `script`.
 2. **External runner** — a cron job or agent harness reads `textus list --zone=intake --stale --format=json`, fetches the source out of band, and pipes bytes back through `textus put KEY --as=script --stdin`.
-Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied fetchers live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
+Both paths share the same role gate, audit-log entry, and `:refresh` event (§5.10). User-supplied actions live in `.textus/extensions/*.rb` and auto-load at `Store#initialize` (§5.11).
 ### 5.5 Pending / accept workflow
@@ -409,29 +419,39 @@ Textus does NOT invoke these — they surface only through `textus extensions li
 **Removed.** The v1.1 `on_stale` event is removed in 0.2. Staleness is a poll, surfaced by `textus stale`. The `on_`-prefix convention from v1.1 is gone; events are bare symbols.
-### 5.11 Extension surface (v1.2)
+### 5.11 Extension surface (v1.3)
-Three DSL verbs cover all user-supplied code:
+Four DSL verbs cover all user-supplied code:
 ```
-Textus.fetcher(:name)       do |config:, store:|   ... end   # returns {frontmatter:, body:} | {content:} | {body:}
-Textus.reducer(:name)       do |rows:, config:|    ... end   # returns rows
-Textus.hook(:event, :name)  do |**kwargs|          ... end   # side effects; return ignored
+Textus.action(:name)         do |config:, store:, args:|  ... end   # intake mode: returns content; verb mode: writes via store.put
+Textus.reducer(:name)        do |rows:, config:|          ... end   # returns rows
+Textus.hook(:event, :name)   do |**kwargs|                ... end   # side effects; return ignored
+Textus.doctor_check(:name)   do |store:|                  ... end   # returns array of issue hashes
 ```
 Files in `.textus/extensions/*.rb` are loaded at `Store#initialize`, in lexical order, with the registry installed as the current registry for that store. Registries are per-Store: two Store instances in the same process do not share state.
-Failure modes:
+**Action invocation modes.**
+| Mode    | Invoked by                | `config:`              | `store:`               | `args:`              | Return                                  |
+|---------|---------------------------|------------------------|------------------------|----------------------|------------------------------------------|
+| intake  | `textus refresh KEY`      | manifest `source.config` | writable view (role from `--as`) | `{}`                | required; normalized into entry write    |
+| verb    | `textus action NAME ...`  | `{}`                   | writable view (role from `--as`) | parsed CLI kv hash   | ignored                                  |
+| put-fetch | `textus put K --action=N --stdin` | `{ "bytes" => stdin }` | read-only view         | `{}`                 | required; merged into the put payload    |
+**Failure modes:**
-| Surface  | Timeout    | Exception                                   | Bad return |
-|----------|------------|---------------------------------------------|------------|
-| fetcher  | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
-| reducer  | aborts op  | aborts op                                   | aborts op  |
-| hook     | logged     | logged (audit `event_error` row)            | n/a        |
+| Surface         | Timeout    | Exception                                   | Bad return |
+|-----------------|------------|---------------------------------------------|------------|
+| action          | aborts op  | aborts op (wrapped as `UsageError`)         | aborts op  |
+| reducer         | aborts op  | aborts op                                   | aborts op  |
+| hook            | logged     | logged (audit `event_error` row)            | n/a        |
+| doctor_check    | reported as `doctor_check.timeout` issue | reported as `doctor_check.failed` issue | reported as `doctor_check.bad_return` |
-Fetchers and reducers are pure transforms; return values flow into the store. Hooks are side effects; return values are discarded.
+Actions and reducers are pure transforms in modes where their return matters; their return values flow into the store. Hooks and doctor_checks shape side outputs (event chain, doctor report) — only doctor_check return values are merged.
-The `store:` argument is always a `Textus::StoreView` — a read-only proxy exposing `get`, `list`, `where`, `schema_envelope`, `deps`, `rdeps`, `published`, `stale`, `validate_all`. Write attempts raise `Textus::UsageError`.
+The `store:` argument is always a `Textus::StoreView`. In intake and verb modes it is writable and bound to the calling role; in put-fetch mode and inside doctor_checks it is read-only. Write attempts on a read-only view raise `Textus::UsageError`.
 ### 5.12 Storage formats (v1.2)
@@ -575,7 +595,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `deps K` / `rdeps K` | read | any |
 | `published` | read | any |
 | `validate-all` | read | any |
-| `put K --stdin --as=R [--fetcher=NAME]` | write | per zone |
+| `put K --stdin --as=R [--action=NAME]` | write | per zone |
 | `delete K --if-etag=E --as=R` | write | per zone |
 | `refresh K --as=script` | write | per zone (typically `script`) |
 | `build [--prefix=K] [--dry-run]` | write | `build` (default) |
@@ -585,7 +605,7 @@ All verbs accept `--format=json` and emit a canonical envelope (success or error
 | `migrate-keys [--dry-run\|--write]` | write (with `--write`) | `human` |
 | `mv OLD NEW [--as=R] [--dry-run]` | write | per zone (same-zone only) |
 | `uid K` | read | any |
-| `extensions list [--kind=fetcher\|reducer\|hook]` | read | any |
+| `extensions list [--kind=action\|reducer\|hook]` | read | any |
 | `doctor [--format=json]` | read | any |
 | `intro [--format=json]` | read | any |

data/lib/textus/{builtin_fetchers.rb → builtin_actions.rb} RENAMED Viewed

@@ -4,31 +4,35 @@ require "yaml"
 require "rexml/document"
 module Textus
-  module BuiltinFetchers
+  module BuiltinActions
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
     def self.register_all
-      Textus.fetcher(:json) do |config:, store:|
+      Textus.action(:json) do |config:, store:, args:|
         _ = store
+        _ = args
         data = JSON.parse(config["bytes"].to_s)
         { frontmatter: {}, body: YAML.dump(data) }
       end
-      Textus.fetcher(:csv) do |config:, store:|
+      Textus.action(:csv) do |config:, store:, args:|
         _ = store
+        _ = args
         rows = CSV.parse(config["bytes"].to_s, headers: true).map(&:to_h)
         { frontmatter: {}, body: YAML.dump(rows) }
       end
-      Textus.fetcher(:"markdown-links") do |config:, store:|
+      Textus.action(:"markdown-links") do |config:, store:, args:|
         _ = store
+        _ = args
         links = config["bytes"].to_s.scan(%r{\[([^\]]+)\]\((https?://[^)\s]+)\)}).map do |text, href|
           { "text" => text, "href" => href }
         end
         { frontmatter: {}, body: YAML.dump(links) }
       end
-      Textus.fetcher(:"ical-events") do |config:, store:|
+      Textus.action(:"ical-events") do |config:, store:, args:|
         _ = store
+        _ = args
         events = []
         current = nil
         config["bytes"].to_s.each_line do |line|
@@ -45,8 +49,9 @@ module Textus
         { frontmatter: {}, body: YAML.dump(events) }
       end
-      Textus.fetcher(:rss) do |config:, store:|
+      Textus.action(:rss) do |config:, store:, args:|
         _ = store
+        _ = args
         doc = REXML::Document.new(config["bytes"].to_s)
         items = doc.elements.to_a("//item").map do |item|
           {

data/lib/textus/cli.rb CHANGED Viewed

@@ -16,9 +16,13 @@ module Textus
       @stdout = stdout
       @stderr = stderr
       @cwd = cwd
+      @root_arg = nil
     end
     def run(argv) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize
+      OptionParser.new do |o|
+        o.on("--root=PATH") { |v| @root_arg = v }
+      end.order!(argv)
       verb = argv.shift
       raise UsageError.new("missing verb") if verb.nil?
@@ -40,6 +44,7 @@ module Textus
       when "schema-init"    then verb_schema_init(argv)
       when "schema-diff"    then verb_schema_diff(argv)
       when "schema-migrate" then verb_schema_migrate(argv)
+      when "action"         then verb_action(argv)
       when "refresh"        then verb_refresh(argv)
       when "extensions"     then verb_extensions(argv)
       when "migrate-keys"   then verb_migrate_keys(argv)
@@ -60,7 +65,7 @@ module Textus
     private
     def store
-      @store ||= Store.discover(@cwd)
+      @store ||= Store.discover(@cwd, root: @root_arg)
     end
     def parse_format!(argv)
@@ -129,11 +134,11 @@ module Textus
       key = argv.shift or raise UsageError.new("put requires a key")
       as_flag = nil
       use_stdin = false
-      fetcher_name = nil
+      action_name = nil
       OptionParser.new do |o|
         o.on("--stdin") { use_stdin = true }
         o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--fetcher=NAME") { |v| fetcher_name = v }
+        o.on("--action=NAME") { |v| action_name = v }
         o.on("--format=FMT") {}
       end.permute!(argv)
       raise UsageError.new("put requires --stdin in v1") unless use_stdin
@@ -142,16 +147,16 @@ module Textus
       raw = @stdin.read
       payload =
-        if fetcher_name
-          callable = store.registry.fetcher(fetcher_name)
+        if action_name
+          callable = store.registry.action(action_name)
           result =
             begin
-              Timeout.timeout(Textus::Refresh::FETCHER_TIMEOUT_SECONDS) do
-                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store))
+              Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store), args: {})
               end
             rescue Timeout::Error
               raise UsageError.new(
-                "fetcher '#{fetcher_name}' exceeded #{Textus::Refresh::FETCHER_TIMEOUT_SECONDS}s timeout",
+                "action '#{action_name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
               )
             end
           basename = key.split(".").last
@@ -159,7 +164,7 @@ module Textus
             "frontmatter" => {
               "name" => basename,
               "last_refreshed_at" => Time.now.utc.iso8601,
-              "fetched_with" => fetcher_name,
+              "actioned_with" => action_name,
             }.merge(result[:frontmatter] || result["frontmatter"] || {}),
             "body" => result[:body] || result["body"] || "",
           }
@@ -267,6 +272,43 @@ module Textus
       emit(store.accept(key, as: role))
     end
+    def verb_action(argv)
+      name = argv.shift
+      raise UsageError.new("action requires a name") if name.nil?
+      as_flag = nil
+      args = {}
+      argv.each do |tok|
+        case tok
+        when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
+        when /\A--format=/           then next
+        when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
+        else
+          raise UsageError.new("unknown arg to 'action #{name}': #{tok}")
+        end
+      end
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+      callable = store.registry.action(name)
+      view = StoreView.new(store, writable: true, as: role)
+      begin
+        Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
+          callable.call(config: {}, store: view, args: args)
+        end
+      rescue Timeout::Error
+        raise UsageError.new(
+          "action '#{name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
+        )
+      rescue Textus::Error
+        raise
+      rescue StandardError => e
+        raise UsageError.new("action '#{name}' raised: #{e.class}: #{e.message}")
+      end
+      emit({ "protocol" => Textus::PROTOCOL, "action" => name, "ok" => true })
+    end
     def verb_refresh(argv)
       key = argv.shift or raise UsageError.new("refresh requires a key")
       as_flag = nil
@@ -289,7 +331,8 @@ module Textus
       end.permute!(argv)
       rows = []
-      rows += store.registry.fetcher_names.map { |n| { "kind" => "fetcher", "name" => n.to_s } }
+      rows += store.registry.action_names.map { |n| { "kind" => "action", "name" => n.to_s } }
+      rows += store.registry.doctor_check_names.map { |n| { "kind" => "doctor_check", "name" => n.to_s } }
       rows += store.registry.reducer_names.map { |n| { "kind" => "reducer", "name" => n.to_s } }
       store.registry.hook_events.each do |evt|
         store.registry.hooks(evt).each do |h|
@@ -384,9 +427,10 @@ module Textus
           textus list [--prefix=KEY] --format=json
           textus where KEY --format=json
           textus get KEY --format=json
-          textus put KEY --stdin --format=json
+          textus put KEY --stdin [--action=NAME] --format=json
           textus schema KEY --format=json
           textus stale [--prefix=KEY] --format=json
+          textus action NAME [--key=val ...] [--as=ROLE] --format=json
       HELP
     end
   end

data/lib/textus/doctor.rb CHANGED Viewed

@@ -1,12 +1,14 @@
 require "digest"
 require "json"
+require "timeout"
 module Textus
   # Health check for a Textus store. Returns a JSON-friendly Hash envelope
   # with an `issues` array and a summary. Each issue is a Hash with
   # `code`, `level`, `subject`, `message`, and optionally `fix`.
-  module Doctor
+  module Doctor # rubocop:disable Metrics/ModuleLength -- 8 built-in checks + extension dispatch
     LEVELS = %w[error warning info].freeze
+    DOCTOR_CHECK_TIMEOUT_SECONDS = 2
     module_function
@@ -20,6 +22,7 @@ module Textus
       issues.concat(check_sentinels(store))
       issues.concat(check_audit_log(store))
       issues.concat(check_unowned_schema_fields(store))
+      issues.concat(run_registered_checks(store))
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -255,6 +258,43 @@ module Textus
       out
     end
+    def run_registered_checks(store)
+      out = []
+      view = StoreView.new(store)
+      store.registry.doctor_check_names.each do |name|
+        callable = store.registry.doctor_check(name)
+        begin
+          result = Timeout.timeout(DOCTOR_CHECK_TIMEOUT_SECONDS) { callable.call(store: view) }
+          if result.is_a?(Array)
+            out.concat(result.map { |h| h.transform_keys(&:to_s) })
+          else
+            out << fail_issue(name, code: "doctor_check.bad_return",
+                                    message: "doctor_check '#{name}' returned #{result.class} (expected Array)",
+                                    fix: "return an array of issue hashes from the doctor_check block")
+          end
+        rescue Timeout::Error
+          out << fail_issue(name, code: "doctor_check.timeout",
+                                  message: "doctor_check '#{name}' exceeded #{DOCTOR_CHECK_TIMEOUT_SECONDS}s",
+                                  fix: "shorten the check or split it into smaller checks")
+        rescue StandardError => e
+          out << fail_issue(name, code: "doctor_check.failed",
+                                  message: "#{e.class}: #{e.message}",
+                                  fix: "fix the doctor_check block in .textus/extensions/")
+        end
+      end
+      out
+    end
+    def fail_issue(name, code:, message:, fix:)
+      {
+        "code" => code,
+        "level" => "error",
+        "subject" => name.to_s,
+        "message" => message,
+        "fix" => fix,
+      }
+    end
     # --- Helpers ----------------------------------------------------------
     def leaf_path_for(store, entry)

data/lib/textus/extension_registry.rb CHANGED Viewed

@@ -3,16 +3,17 @@ module Textus
     EVENTS = %i[put delete refresh build accept].freeze
     def initialize
-      @fetchers = {}
+      @actions = {}
       @reducers = {}
       @hooks = {}
+      @doctor_checks = {}
     end
-    def register_fetcher(name, &blk)
+    def register_action(name, &blk)
       name = name.to_sym
-      raise UsageError.new("fetcher '#{name}' already registered") if @fetchers.key?(name)
+      raise UsageError.new("action '#{name}' already registered") if @actions.key?(name)
-      @fetchers[name] = blk
+      @actions[name] = blk
     end
     def register_reducer(name, &blk)
@@ -29,8 +30,15 @@ module Textus
       (@hooks[event] ||= []) << { name: name.to_sym, callable: blk }
     end
-    def fetcher(name)
-      @fetchers[name.to_sym] or raise UsageError.new("unknown fetcher: #{name}")
+    def register_doctor_check(name, &blk)
+      name = name.to_sym
+      raise UsageError.new("doctor_check '#{name}' already registered") if @doctor_checks.key?(name)
+      @doctor_checks[name] = blk
+    end
+    def action(name)
+      @actions[name.to_sym] or raise UsageError.new("unknown action: #{name}")
     end
     def reducer(name)
@@ -41,8 +49,13 @@ module Textus
       @hooks[event.to_sym] || []
     end
-    def fetcher_names = @fetchers.keys
-    def reducer_names = @reducers.keys
-    def hook_events   = @hooks.keys
+    def doctor_check(name)
+      @doctor_checks[name.to_sym] or raise UsageError.new("unknown doctor_check: #{name}")
+    end
+    def action_names        = @actions.keys
+    def reducer_names       = @reducers.keys
+    def hook_events         = @hooks.keys
+    def doctor_check_names  = @doctor_checks.keys
   end
 end

data/lib/textus/extensions.rb CHANGED Viewed

@@ -15,8 +15,8 @@ module Textus
       raise UsageError.new("no active registry; extension code must be loaded by a Store")
   end
-  def self.fetcher(name, &)
-    current_registry.register_fetcher(name, &)
+  def self.action(name, &)
+    current_registry.register_action(name, &)
   end
   def self.reducer(name, &)
@@ -26,4 +26,8 @@ module Textus
   def self.hook(event, name, &)
     current_registry.register_hook(event, name, &)
   end
+  def self.doctor_check(name, &)
+    current_registry.register_doctor_check(name, &)
+  end
 end

data/lib/textus/init.rb CHANGED Viewed

@@ -31,12 +31,13 @@ module Textus
       File.write(File.join(target_root, "extensions", "README.md"), <<~MD)
         # Extensions
-        Drop one Ruby file per extension. Three verbs are available:
+        Drop one Ruby file per extension. Four verbs are available:
         ```ruby
-        Textus.fetcher(:name)        { |config:, store:| ... }
-        Textus.reducer(:name)        { |rows:, config:| ... }
-        Textus.hook(:event, :name)   { |key:, envelope:, store:, **kw| ... }
+        Textus.action(:name)         { |config:, store:, args:| ... }
+        Textus.reducer(:name)        { |rows:, config:|         ... }
+        Textus.hook(:event, :name)   { |key:, envelope:, **kw|  ... }
+        Textus.doctor_check(:name)   { |store:|                 ... }
         ```
         Events: :put, :delete, :refresh, :build, :accept.

data/lib/textus/intro.rb CHANGED Viewed

@@ -13,7 +13,7 @@ module Textus
     ZONE_PURPOSES = {
       "canon" => "slow-changing identity; human-only writes",
       "working" => "active project state; humans, AI, and scripts share this surface",
-      "intake" => "declared external inputs; script-refreshed via fetchers",
+      "intake" => "declared external inputs; script-refreshed via actions",
       "pending" => "AI proposals awaiting human accept",
       "derived" => "build-computed outputs; never hand-edited",
     }.freeze
@@ -22,7 +22,7 @@ module Textus
       "human" => "edit files in canon/working zones, then 'textus put KEY --as=human'",
       "ai" => "propose changes by writing 'pending.*' entries with --as=ai and a 'proposal:' frontmatter block; " \
               "a human runs 'textus accept' to apply",
-      "script" => "refresh intake entries with 'textus refresh KEY --as=script' (uses the entry's declared fetcher)",
+      "script" => "refresh intake entries with 'textus refresh KEY --as=script' (uses the entry's declared action)",
       "build" => "'textus build' computes derived entries from projections; derived files are never hand-edited",
     }.freeze
@@ -40,11 +40,11 @@ module Textus
       { "name" => "mv",       "summary" => "rename a key in place; uid preserved, audit row written" },
       { "name" => "delete",   "summary" => "delete an entry; --as=<role>" },
       { "name" => "build",    "summary" => "materialize derived entries; publish_to and publish_each fan out copies" },
-      { "name" => "refresh",  "summary" => "run a fetcher for an intake entry" },
+      { "name" => "refresh",  "summary" => "run an action for an intake entry" },
       { "name" => "stale",    "summary" => "list derived/intake entries past their freshness check" },
       { "name" => "doctor",   "summary" => "health-check the store (missing schemas, illegal keys, sentinel drift, etc.)" },
       { "name" => "migrate-keys", "summary" => "rename files whose basenames violate the strict key grammar" },
-      { "name" => "extensions", "summary" => "list registered reducers/fetchers/hooks" },
+      { "name" => "extensions", "summary" => "list registered actions, reducers, doctor_checks, declared hooks" },
     ].freeze
     def self.run(store)
@@ -80,7 +80,7 @@ module Textus
           "owner" => e.owner,
           "format" => e.format,
           "derived" => derived,
-          "intake" => !e.fetcher.nil?,
+          "intake" => !e.action.nil?,
           "publish_to" => Array(e.publish_to),
           "publish_each" => e.publish_each,
         }
@@ -90,13 +90,15 @@ module Textus
     def self.extensions_for(store)
       reg = store.registry
       reducers = reg.reducer_names.map(&:to_s).sort
-      fetchers = reg.fetcher_names.map(&:to_s).sort
+      actions = reg.action_names.map(&:to_s).sort
+      doctor_checks = reg.doctor_check_names.map(&:to_s).sort
       hooks = reg.hook_events.flat_map do |evt|
         reg.hooks(evt).map { |h| { "event" => evt.to_s, "name" => h[:name].to_s } }
       end.sort_by { |h| [h["event"], h["name"]] }
       {
         "reducers" => reducers,
-        "fetchers" => fetchers,
+        "actions" => actions,
+        "doctor_checks" => doctor_checks,
         "hooks" => hooks,
       }
     end

data/lib/textus/manifest.rb CHANGED Viewed

@@ -199,7 +199,7 @@ module Textus
     PUBLISH_EACH_VAR_RE = /\{([a-z]+)\}/
     attr_reader :key, :path, :zone, :schema, :owner, :nested, :generator, :raw, :format,
-                :projection, :template, :publish_to, :publish_each, :fetcher, :fetcher_config, :ttl, :events,
+                :projection, :template, :publish_to, :publish_each, :action, :action_config, :ttl, :events,
                 :inject_intro
     def initialize(manifest, raw)
@@ -361,8 +361,8 @@ module Textus
     def parse_source!(src)
       src ||= {}
-      @fetcher = src["fetcher"]
-      @fetcher_config = src["config"] || {}
+      @action = src["action"]
+      @action_config = src["config"] || {}
       @ttl = src["ttl"]
     end
@@ -371,7 +371,13 @@ module Textus
       if src.key?("parse") || src.key?("from")
         raise UsageError.new(
           "entry '#{@key}': source.parse/source.from removed in 0.2; " \
-          "use source.fetcher (+ source.config). See SPEC §5.4.",
+          "use source.action (+ source.config). See SPEC §5.4.",
+        )
+      end
+      if src.key?("fetcher")
+        raise UsageError.new(
+          "entry '#{@key}': source.fetcher renamed to source.action in 0.4; " \
+          "rename the key. See SPEC §5.4.",
         )
       end
       if raw.key?("hooks")

data/lib/textus/refresh.rb CHANGED Viewed

@@ -2,27 +2,29 @@ require "timeout"
 module Textus
   module Refresh
-    FETCHER_TIMEOUT_SECONDS = 2
+    ACTION_TIMEOUT_SECONDS = 2
     def self.call(store, key, as:)
       mentry, path, = store.manifest.resolve(key)
-      raise UsageError.new("no fetcher declared for '#{key}'") unless mentry.fetcher
+      raise UsageError.new("no action declared for '#{key}'") unless mentry.action
       before_etag = File.exist?(path) ? Etag.for_file(path) : nil
-      callable = store.registry.fetcher(mentry.fetcher)
-      view = StoreView.new(store)
+      callable = store.registry.action(mentry.action)
+      view = StoreView.new(store, writable: true, as: as)
       result =
         begin
-          Timeout.timeout(FETCHER_TIMEOUT_SECONDS) { callable.call(config: mentry.fetcher_config, store: view) }
+          Timeout.timeout(ACTION_TIMEOUT_SECONDS) do
+            callable.call(config: mentry.action_config, store: view, args: {})
+          end
         rescue Timeout::Error
-          raise UsageError.new("fetcher '#{mentry.fetcher}' exceeded #{FETCHER_TIMEOUT_SECONDS}s timeout")
+          raise UsageError.new("action '#{mentry.action}' exceeded #{ACTION_TIMEOUT_SECONDS}s timeout")
         rescue Textus::Error
           raise
         rescue StandardError => e
-          raise UsageError.new("fetcher '#{mentry.fetcher}' raised: #{e.class}: #{e.message}")
+          raise UsageError.new("action '#{mentry.action}' raised: #{e.class}: #{e.message}")
         end
-      normalized = normalize_fetcher_result(result, format: mentry.format)
+      normalized = normalize_action_result(result, format: mentry.format)
       envelope = store.put(
         key,
         frontmatter: normalized[:frontmatter],
@@ -43,9 +45,9 @@ module Textus
       envelope
     end
-    # Normalize the three accepted fetcher return shapes into the store's
-    # internal {frontmatter, body, content} representation. See plan-1.2 §7.
-    def self.normalize_fetcher_result(res, format:)
+    # Normalize the three accepted action return shapes into the store's
+    # internal {frontmatter, body, content} representation.
+    def self.normalize_action_result(res, format:)
       res = res.transform_keys(&:to_s) if res.is_a?(Hash)
       res ||= {}
       fm      = res["frontmatter"]
@@ -62,10 +64,9 @@ module Textus
           meta = content.is_a?(Hash) && content["_meta"].is_a?(Hash) ? content["_meta"] : {}
           { frontmatter: meta, body: nil, content: content }
         elsif !body.nil?
-          # Store#put will re-parse and validate the bytes.
           { frontmatter: {}, body: body.to_s, content: nil }
         else
-          raise UsageError.new("fetcher for #{format} returned neither content nor body")
+          raise UsageError.new("action for #{format} returned neither content nor body")
         end
       else
         raise UsageError.new("unknown format #{format.inspect}")

data/lib/textus/store.rb CHANGED Viewed

@@ -17,7 +17,10 @@ module Textus
       SecureRandom.hex(8)
     end
-    def self.discover(start_dir = Dir.pwd)
+    def self.discover(start_dir = Dir.pwd, root: nil)
+      explicit = root || ENV.fetch("TEXTUS_ROOT", nil)
+      return discover_explicit(explicit) if explicit
       dir = File.expand_path(start_dir)
       loop do
         candidate = File.join(dir, ".textus")
@@ -31,6 +34,13 @@ module Textus
       raise IoError.new("no .textus directory found from #{start_dir}")
     end
+    private_class_method def self.discover_explicit(root_arg)
+      abs = File.expand_path(root_arg)
+      raise IoError.new("no textus store at #{abs}") unless File.directory?(abs) && File.exist?(File.join(abs, "manifest.yaml"))
+      new(abs)
+    end
     def initialize(root)
       @root = File.expand_path(root)
       @manifest = Manifest.load(@root)
@@ -41,7 +51,7 @@ module Textus
     def load_extensions
       Textus.with_registry(@registry) do
-        BuiltinFetchers.register_all
+        BuiltinActions.register_all
         dir = File.join(@root, "extensions")
         return unless File.directory?(dir)
@@ -286,7 +296,7 @@ module Textus
       end
       @manifest.entries.each do |mentry|
-        next unless mentry.fetcher
+        next unless mentry.action
         next if zone && mentry.zone != zone
         next if prefix && !(mentry.key == prefix || mentry.key.start_with?("#{prefix}."))
@@ -519,7 +529,7 @@ module Textus
     end
     def intake_stale_row(mentry, path, reason)
-      { "key" => mentry.key, "path" => path, "fetcher" => mentry.fetcher, "reason" => reason }
+      { "key" => mentry.key, "path" => path, "action" => mentry.action, "reason" => reason }
     end
     def stale_row(mentry, path, reason)

data/lib/textus/store_view.rb CHANGED Viewed

@@ -3,8 +3,12 @@ module Textus
     READ_METHODS  = %i[get list where schema_envelope deps rdeps published stale validate_all].freeze
     WRITE_METHODS = %i[put delete accept].freeze
-    def initialize(store)
+    def initialize(store, writable: false, as: nil)
+      raise UsageError.new("writable StoreView requires an as: role") if writable && (as.nil? || as.to_s.empty?)
       @store = store
+      @writable = writable
+      @as = as
     end
     READ_METHODS.each do |m|
@@ -12,7 +16,12 @@ module Textus
     end
     WRITE_METHODS.each do |m|
-      define_method(m) { |*_args, **_kw| raise UsageError.new("StoreView is read-only") }
+      define_method(m) do |*args, **kw|
+        raise UsageError.new("StoreView is read-only") unless @writable
+        kw[:as] = @as unless kw.key?(:as)
+        @store.public_send(m, *args, **kw)
+      end
     end
   end
 end

data/lib/textus/version.rb CHANGED Viewed

@@ -1,4 +1,4 @@
 module Textus
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
   PROTOCOL = "textus/1"
 end

data/lib/textus.rb CHANGED Viewed

@@ -19,7 +19,7 @@ require_relative "textus/store_view"
 require_relative "textus/refresh"
 require_relative "textus/mustache"
 require_relative "textus/projection"
-require_relative "textus/builtin_fetchers"
+require_relative "textus/builtin_actions"
 require_relative "textus/publisher"
 require_relative "textus/builder"
 require_relative "textus/proposal"

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: textus
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Patrick
@@ -97,7 +97,7 @@ files:
 - lib/textus.rb
 - lib/textus/audit_log.rb
 - lib/textus/builder.rb
-- lib/textus/builtin_fetchers.rb
+- lib/textus/builtin_actions.rb
 - lib/textus/cli.rb
 - lib/textus/dependencies.rb
 - lib/textus/doctor.rb