Module: Textus::Intro

Defined in:
lib/textus/intro.rb

Overview

Read-only “what’s in this store and how do I use it” envelope. A single call gives an agent the working model of a textus-managed project: zones and their write authority, entries and their flags, registered extensions, write flows, and the CLI verb catalog.

Intro is side-effect-free.

Constant Summary collapse

PROTOCOL_ID = 
PROTOCOL
ZONE_PURPOSES =

Conventional zone purposes. Unknown zones (declared in the manifest but not listed here) get no ‘purpose` field.

{
  "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 actions",
  "pending" => "AI proposals awaiting human accept",
  "derived" => "build-computed outputs; never hand-edited",
}.freeze
WRITE_FLOWS = 
{
  "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 action)",
  "build" => "'textus build' computes derived entries from projections; derived files are never hand-edited",
}.freeze
CLI_VERBS =

The CLI verb catalog. Truth lives here; do not derive dynamically. Agents that read intro should see a stable shape regardless of how verb implementations evolve.

[
  { "name" => "intro",    "summary" => "this output — orientation for agents and tools" },
  { "name" => "list",     "summary" => "enumerate keys (optional --prefix)" },
  { "name" => "get",      "summary" => "read an entry; envelope with _meta, body, uid, etag" },
  { "name" => "where",    "summary" => "resolve a key to its zone and path without reading" },
  { "name" => "schema",   "summary" => "field shape for a key family" },
  { "name" => "put",      "summary" => "write an entry; --as=<role>, --stdin payload" },
  { "name" => "accept",   "summary" => "apply a pending.* proposal; --as=human only" },
  { "name" => "key",      "summary" => "key operations: 'key mv', 'key uid', 'key migrate'" },
  { "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 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" => "hook",
    "summary" => "list and run registered hooks: 'hook list', 'hook run NAME'" },
].freeze

Class Method Summary collapse

Class Method Details

.entries_for(store) ⇒ Object 



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
 
# File 'lib/textus/intro.rb', line 72

def self.entries_for(store)
  store.manifest.entries.map do |e|
    derived = store.manifest.zone_writers(e.zone).include?("build")
    {
      "key" => e.key,
      "zone" => e.zone,
      "schema" => e.schema,
      "nested" => e.nested ? true : false,
      "owner" => e.owner,
      "format" => e.format,
      "derived" => derived,
      "intake" => !e.fetch.nil?,
      "publish_to" => Array(e.publish_to),
      "publish_each" => e.publish_each,
    }
  end
end

.extensions_for(store) ⇒ Object 



90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/textus/intro.rb', line 90

def self.extensions_for(store)
  reg = store.registry
  sections = {}
  Hooks::Registry::EVENTS.each do |event, spec|
    case spec[:mode]
    when :rpc
      sections[event.to_s] = reg.rpc_names(event).map(&:to_s).sort
    when :pubsub
      sections[event.to_s] = reg.pubsub_handlers(event).map { |h| h[:name].to_s }.sort
    end
  end
  sections
end

.run(store) ⇒ Object 



50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/textus/intro.rb', line 50

def self.run(store)
  {
    "protocol" => PROTOCOL_ID,
    "store_root" => store.root,
    "zones" => zones_for(store),
    "entries" => entries_for(store),
    "extensions" => extensions_for(store),
    "write_flows" => WRITE_FLOWS.dup,
    "cli_verbs" => CLI_VERBS.map(&:dup),
    "docs" => { "spec" => "SPEC.md", "example" => "examples/claude-plugin/" },
  }
end

.zones_for(store) ⇒ Object 



63
64
65
66
67
68
69
70
 
# File 'lib/textus/intro.rb', line 63

def self.zones_for(store)
  store.manifest.zones.map do |name, writers|
    row = { "name" => name, "writers" => Array(writers) }
    purpose = ZONE_PURPOSES[name]
    row["purpose"] = purpose if purpose
    row
  end
end