textus 0.2.0

data/lib/textus/entry/json.rb

@@ -0,0 +1,41 @@
+require "json"
+
+module Textus
+  module Entry
+    # JSON entry storage. Top-level must be an object so we can carry _meta.
+    module Json
+      def self.parse(raw, path: nil)
+        raw = raw.dup.force_encoding(Encoding::UTF_8)
+        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
+
+        begin
+          parsed = ::JSON.parse(raw)
+        rescue ::JSON::ParserError => e
+          raise BadFrontmatter.new(path, "JSON parse failed: #{e.message}")
+        end
+        raise BadFrontmatter.new(path, "JSON top-level must be an object") unless parsed.is_a?(Hash)
+
+        meta = parsed["_meta"]
+        fm = meta.is_a?(Hash) ? meta : {}
+        { "frontmatter" => fm, "body" => raw, "content" => parsed }
+      end
+
+      def self.serialize(frontmatter:, body:, content: nil)
+        _ = frontmatter
+        if content.is_a?(Hash)
+          out = ::JSON.pretty_generate(content)
+          out += "\n" unless out.end_with?("\n")
+          out
+        elsif body && !body.to_s.empty?
+          b = body.to_s
+          b += "\n" unless b.end_with?("\n")
+          b
+        else
+          raise UsageError.new("json serialize requires :content or :body")
+        end
+      end
+
+      def self.extensions = [".json"]
+    end
+  end
+end

data/lib/textus/entry/markdown.rb

@@ -0,0 +1,39 @@
+require "yaml"
+
+module Textus
+  module Entry
+    # Markdown with YAML frontmatter. Original Entry implementation.
+    module Markdown
+      def self.parse(raw, path: nil)
+        raw = raw.dup.force_encoding(Encoding::UTF_8)
+        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
+        return { "frontmatter" => {}, "body" => raw, "content" => nil } unless raw.start_with?("---\n") || raw.start_with?("---\r\n")
+
+        lines = raw.split(/\r?\n/, -1)
+        close_idx = lines[1..].index("---")
+        raise BadFrontmatter.new(path, "frontmatter not terminated") unless close_idx
+
+        close_idx += 1
+        fm_yaml = lines[1...close_idx].join("\n")
+        body = lines[(close_idx + 1)..].join("\n")
+        begin
+          fm = fm_yaml.strip.empty? ? {} : ::YAML.safe_load(fm_yaml, permitted_classes: [Date, Time], aliases: false)
+        rescue Psych::SyntaxError => e
+          raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
+        end
+        fm = {} unless fm.is_a?(Hash)
+        { "frontmatter" => fm, "body" => body, "content" => nil }
+      end
+
+      def self.serialize(frontmatter:, body:, content: nil)
+        _ = content # markdown ignores content
+        fm_yaml = frontmatter.empty? ? "" : ::YAML.dump(frontmatter).sub(/\A---\n/, "")
+        body = body.to_s
+        body += "\n" unless body.empty? || body.end_with?("\n")
+        "---\n#{fm_yaml}---\n#{body}"
+      end
+
+      def self.extensions = [".md"]
+    end
+  end
+end

data/lib/textus/entry/text.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Entry
+    # Plain-text entry storage. No frontmatter or structured content.
+    module Text
+      def self.parse(raw, path: nil)
+        raw = raw.dup.force_encoding(Encoding::UTF_8)
+        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
+
+        { "frontmatter" => {}, "body" => raw, "content" => nil }
+      end
+
+      def self.serialize(frontmatter:, body:, content: nil)
+        _ = frontmatter
+        _ = content
+        b = body.to_s
+        b += "\n" unless b.empty? || b.end_with?("\n")
+        b
+      end
+
+      def self.extensions = [".txt"]
+    end
+  end
+end

data/lib/textus/entry/yaml.rb

@@ -0,0 +1,39 @@
+require "yaml"
+
+module Textus
+  module Entry
+    # YAML entry storage. Top-level must be a mapping so we can carry _meta.
+    module Yaml
+      def self.parse(raw, path: nil)
+        raw = raw.dup.force_encoding(Encoding::UTF_8)
+        raise BadFrontmatter.new(path, "entry is not valid UTF-8") unless raw.valid_encoding?
+
+        begin
+          parsed = ::YAML.safe_load(raw, permitted_classes: [Date, Time], aliases: false)
+        rescue Psych::SyntaxError, Psych::AliasesNotEnabled, Psych::DisallowedClass => e
+          raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
+        end
+        raise BadFrontmatter.new(path, "YAML top-level must be a mapping") unless parsed.is_a?(Hash)
+
+        meta = parsed["_meta"]
+        fm = meta.is_a?(Hash) ? meta : {}
+        { "frontmatter" => fm, "body" => raw, "content" => parsed }
+      end
+
+      def self.serialize(frontmatter:, body:, content: nil)
+        _ = frontmatter
+        if content.is_a?(Hash)
+          ::YAML.dump(content).sub(/\A---\n/, "")
+        elsif body && !body.to_s.empty?
+          b = body.to_s
+          b += "\n" unless b.end_with?("\n")
+          b
+        else
+          raise UsageError.new("yaml serialize requires :content or :body")
+        end
+      end
+
+      def self.extensions = [".yaml", ".yml"]
+    end
+  end
+end

data/lib/textus/entry.rb

@@ -0,0 +1,30 @@
+require_relative "entry/markdown"
+require_relative "entry/json"
+require_relative "entry/yaml"
+require_relative "entry/text"
+
+module Textus
+  # Public entry-format dispatcher.
+  module Entry
+    SEP = "---".freeze
+
+    STRATEGIES = {
+      "markdown" => Markdown,
+      "json" => Json,
+      "yaml" => Yaml,
+      "text" => Text,
+    }.freeze
+
+    def self.for_format(format)
+      STRATEGIES.fetch(format.to_s) { raise UsageError.new("unknown entry format: #{format.inspect}") }
+    end
+
+    def self.parse(raw, path: nil, format: "markdown")
+      for_format(format).parse(raw, path: path)
+    end
+
+    def self.serialize(frontmatter: {}, body: "", content: nil, format: "markdown")
+      for_format(format).serialize(frontmatter: frontmatter, body: body, content: content)
+    end
+  end
+end

data/lib/textus/errors.rb

@@ -0,0 +1,168 @@
+module Textus
+  class Error < StandardError
+    attr_reader :code, :details, :exit_code, :hint
+
+    def initialize(code, message, details: {}, exit_code: 1, hint: nil)
+      super(message)
+      @code = code
+      @details = details
+      @exit_code = exit_code
+      @hint = hint
+    end
+
+    def to_envelope
+      env = {
+        "protocol" => Textus::PROTOCOL,
+        "ok" => false,
+        "code" => @code,
+        "message" => message,
+        "details" => @details,
+      }
+      env["hint"] = @hint if @hint
+      env
+    end
+  end
+
+  class UnknownKey < Error
+    attr_reader :suggestions
+
+    def initialize(key, suggestions: [])
+      @suggestions = Array(suggestions)
+      details = { "key" => key }
+      details["suggestions"] = @suggestions unless @suggestions.empty?
+      msg = "key '#{key}' does not resolve"
+      msg += "; did you mean: #{@suggestions.join(", ")}" unless @suggestions.empty?
+      hint =
+        if @suggestions.empty?
+          "run 'textus list --format=json' to see all keys"
+        else
+          "did you mean: #{@suggestions.join(", ")}"
+        end
+      super("unknown_key", msg, details: details, hint: hint)
+    end
+  end
+
+  class BadFrontmatter < Error
+    def initialize(path, m, hint: nil)
+      hint ||= default_hint_for(path, m)
+      super("bad_frontmatter", m, details: { "path" => path }, hint: hint)
+    end
+
+    private
+
+    def default_hint_for(path, m)
+      if m.is_a?(String) && (match = m.match(/frontmatter name '([^']+)' does not match basename '([^']+)'/))
+        name, basename = match.captures
+        ext = File.extname(path)
+        "rename the file to '#{name}#{ext}' or change frontmatter name: to '#{basename}'"
+      else
+        "open #{path} and check the YAML frontmatter for syntax errors"
+      end
+    end
+  end
+
+  class BadContent < Error
+    def initialize(path, m)
+      super(
+        "bad_content", m,
+        details: { "path" => path },
+        hint: "JSON/YAML parse failed; run the file through 'jq .' or 'yq .' to find the syntax error",
+      )
+    end
+  end
+
+  class SchemaViolation < Error
+    def initialize(d)
+      hint =
+        if d.is_a?(Hash) && d["missing"]
+          "add the missing field(s) to the entry's frontmatter: #{Array(d["missing"]).join(", ")}"
+        elsif d.is_a?(Hash) && d["field"]
+          "fix the field '#{d["field"]}' in the entry's frontmatter (#{d["reason"]})"
+        end
+      super("schema_violation", "schema violation", details: d, hint: hint)
+    end
+  end
+
+  class WriteForbidden < Error
+    def initialize(k, z, writers: nil)
+      writers_str =
+        if writers && !writers.empty?
+          writers.join(", ")
+        else
+          "the role(s) listed in the manifest 'writable_by:'"
+        end
+      details = { "key" => k, "zone" => z }
+      details["writers"] = writers if writers
+      super(
+        "write_forbidden",
+        "zone '#{z}' is not agent-writable for key '#{k}'",
+        details: details,
+        hint: "this zone is writable by #{writers_str}; pass --as=<role>",
+      )
+    end
+  end
+
+  class EtagMismatch < Error
+    def initialize(k, w, g)
+      super(
+        "etag_mismatch", "etag mismatch on '#{k}'",
+        details: { "key" => k, "wanted" => w, "got" => g },
+        hint: "another writer changed this key; run 'textus get #{k}' to fetch the latest etag",
+      )
+    end
+  end
+
+  class IoError < Error
+    def initialize(m) = super("io_error", m, exit_code: 64)
+  end
+
+  class UsageError < Error
+    def initialize(m, hint: nil) = super("usage", m, exit_code: 2, hint: hint)
+  end
+
+  class InvalidRole < Error
+    def initialize(r)
+      super(
+        "invalid_role", "role '#{r}' is not declared in any zone",
+        details: { "role" => r },
+        hint: "valid roles are declared in .textus/manifest.yaml under zones[].writable_by",
+      )
+    end
+  end
+
+  class InvalidProjection < Error
+    def initialize(m) = super("invalid_projection", m)
+  end
+
+  class TemplateError < Error
+    def initialize(m, template_name: nil)
+      hint =
+        ("expected at .textus/templates/#{template_name}; add the file or update the entry's template: field" if template_name)
+      super("template_error", m, hint: hint)
+    end
+  end
+
+  class BadRender < Error
+    def initialize(m, format: nil)
+      hint =
+        if format
+          "the template rendered invalid #{format}; try rendering with mock data and parsing the output before re-running build"
+        else
+          "the template rendered invalid content; try rendering with mock data and parsing the output before re-running build"
+        end
+      super("bad_render", m, hint: hint)
+    end
+  end
+
+  class PublishError < Error
+    def initialize(m, target: nil)
+      hint =
+        ("file at #{target} wasn't published by textus; back it up and delete it, or move it under .textus/zones/" if target)
+      super("publish_error", m, details: target ? { "target" => target } : {}, hint: hint)
+    end
+  end
+
+  class ProposalError < Error
+    def initialize(m) = super("proposal_error", m)
+  end
+end

data/lib/textus/etag.rb

@@ -0,0 +1,13 @@
+require "digest"
+
+module Textus
+  module Etag
+    def self.for_bytes(bytes)
+      "sha256:#{Digest::SHA256.hexdigest(bytes)}"
+    end
+
+    def self.for_file(path)
+      for_bytes(File.binread(path))
+    end
+  end
+end

data/lib/textus/extension_registry.rb

@@ -0,0 +1,48 @@
+module Textus
+  class ExtensionRegistry
+    EVENTS = %i[put delete refresh build accept].freeze
+
+    def initialize
+      @fetchers = {}
+      @reducers = {}
+      @hooks = {}
+    end
+
+    def register_fetcher(name, &blk)
+      name = name.to_sym
+      raise UsageError.new("fetcher '#{name}' already registered") if @fetchers.key?(name)
+
+      @fetchers[name] = blk
+    end
+
+    def register_reducer(name, &blk)
+      name = name.to_sym
+      raise UsageError.new("reducer '#{name}' already registered") if @reducers.key?(name)
+
+      @reducers[name] = blk
+    end
+
+    def register_hook(event, name, &blk)
+      event = event.to_sym
+      raise UsageError.new("unknown event: #{event}") unless EVENTS.include?(event)
+
+      (@hooks[event] ||= []) << { name: name.to_sym, callable: blk }
+    end
+
+    def fetcher(name)
+      @fetchers[name.to_sym] or raise UsageError.new("unknown fetcher: #{name}")
+    end
+
+    def reducer(name)
+      @reducers[name.to_sym] or raise UsageError.new("unknown reducer: #{name}")
+    end
+
+    def hooks(event)
+      @hooks[event.to_sym] || []
+    end
+
+    def fetcher_names = @fetchers.keys
+    def reducer_names = @reducers.keys
+    def hook_events   = @hooks.keys
+  end
+end

data/lib/textus/extensions.rb

@@ -0,0 +1,29 @@
+module Textus
+  THREAD_REGISTRY_KEY = :__textus_active_registry__
+  private_constant :THREAD_REGISTRY_KEY
+
+  def self.with_registry(registry)
+    prev = Thread.current[THREAD_REGISTRY_KEY]
+    Thread.current[THREAD_REGISTRY_KEY] = registry
+    yield
+  ensure
+    Thread.current[THREAD_REGISTRY_KEY] = prev
+  end
+
+  def self.current_registry
+    Thread.current[THREAD_REGISTRY_KEY] or
+      raise UsageError.new("no active registry; extension code must be loaded by a Store")
+  end
+
+  def self.fetcher(name, &)
+    current_registry.register_fetcher(name, &)
+  end
+
+  def self.reducer(name, &)
+    current_registry.register_reducer(name, &)
+  end
+
+  def self.hook(event, name, &)
+    current_registry.register_hook(event, name, &)
+  end
+end

data/lib/textus/init.rb

@@ -0,0 +1,51 @@
+require "fileutils"
+
+module Textus
+  module Init
+    ZONES = %w[canon working intake pending derived].freeze
+
+    DEFAULT_MANIFEST = <<~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, human] }
+        - { name: derived, writable_by: [build] }
+      entries:
+        - { key: canon.identity, path: canon/identity.md, zone: canon, schema: null, owner: human:self }
+        - { key: working.notes,  path: working/notes,     zone: working, schema: null, owner: human:self, nested: true }
+    YAML
+
+    def self.run(target_root)
+      raise UsageError.new(".textus/ already exists at #{target_root}") if File.directory?(target_root)
+
+      FileUtils.mkdir_p(File.join(target_root, "schemas"))
+      FileUtils.mkdir_p(File.join(target_root, "templates"))
+      FileUtils.mkdir_p(File.join(target_root, "extensions"))
+      ZONES.each do |z|
+        dir = File.join(target_root, "zones", z)
+        FileUtils.mkdir_p(dir)
+        File.write(File.join(dir, ".gitkeep"), "")
+      end
+      File.write(File.join(target_root, "extensions", "README.md"), <<~MD)
+        # Extensions
+
+        Drop one Ruby file per extension. Three verbs are available:
+
+        ```ruby
+        Textus.fetcher(:name)        { |config:, store:| ... }
+        Textus.reducer(:name)        { |rows:, config:| ... }
+        Textus.hook(:event, :name)   { |key:, envelope:, store:, **kw| ... }
+        ```
+
+        Events: :put, :delete, :refresh, :build, :accept.
+
+        See SPEC.md §5.11 for the full contract.
+      MD
+
+      File.write(File.join(target_root, "manifest.yaml"), DEFAULT_MANIFEST)
+      { "protocol" => PROTOCOL, "initialized" => target_root }
+    end
+  end
+end

data/lib/textus/intro.rb

@@ -0,0 +1,104 @@
+module Textus
+  # 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.
+  module Intro
+    PROTOCOL_ID = "textus/1".freeze
+
+    # Conventional zone purposes. Unknown zones (declared in the manifest
+    # but not listed here) get no `purpose` field.
+    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",
+      "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 fetcher)",
+      "build" => "'textus build' computes derived entries from projections; derived files are never hand-edited",
+    }.freeze
+
+    # 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.
+    CLI_VERBS = [
+      { "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 frontmatter, 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" => "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" => "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" },
+    ].freeze
+
+    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
+
+    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
+
+    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.fetcher.nil?,
+          "publish_to" => Array(e.publish_to),
+          "publish_each" => e.publish_each,
+        }
+      end
+    end
+
+    def self.extensions_for(store)
+      reg = store.registry
+      reducers = reg.reducer_names.map(&:to_s).sort
+      fetchers = reg.fetcher_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,
+        "hooks" => hooks,
+      }
+    end
+  end
+end

data/lib/textus/key_distance.rb

@@ -0,0 +1,53 @@
+module Textus
+  # Small utilities for ranking key suggestions. Bounded inputs only —
+  # Levenshtein is O(n*m) so we refuse to compute on long strings.
+  module KeyDistance
+    MAX_LEN = 200
+
+    # Length of the shared dot-separated prefix between two dotted keys.
+    def self.shared_prefix_segments(left, right)
+      asegs = left.split(".")
+      bsegs = right.split(".")
+      n = [asegs.length, bsegs.length].min
+      i = 0
+      i += 1 while i < n && asegs[i] == bsegs[i]
+      i
+    end
+
+    # Classic iterative Levenshtein with two rows. Bounded to MAX_LEN.
+    def self.levenshtein(left, right)
+      return nil if left.length > MAX_LEN || right.length > MAX_LEN
+      return right.length if left.empty?
+      return left.length if right.empty?
+
+      prev = (0..right.length).to_a
+      curr = Array.new(right.length + 1, 0)
+      (1..left.length).each do |i|
+        curr[0] = i
+        (1..right.length).each do |j|
+          cost = left[i - 1] == right[j - 1] ? 0 : 1
+          curr[j] = [
+            curr[j - 1] + 1,      # insertion
+            prev[j] + 1,          # deletion
+            prev[j - 1] + cost,   # substitution
+          ].min
+        end
+        prev, curr = curr, prev
+      end
+      prev[right.length]
+    end
+
+    # Rank candidate keys against requested. Returns up to `limit` keys.
+    # Sort: longer shared prefix first; then smaller Levenshtein distance.
+    def self.suggest(requested, candidates, limit: 5)
+      return [] if requested.nil? || requested.empty?
+
+      scored = candidates.first(200).map do |k|
+        prefix = shared_prefix_segments(requested, k)
+        dist = levenshtein(requested, k) || Float::INFINITY
+        [k, prefix, dist]
+      end
+      scored.sort_by { |(_, prefix, dist)| [-prefix, dist] }.first(limit).map(&:first)
+    end
+  end
+end