textus 0.2.0

data/lib/textus/projection.rb

@@ -0,0 +1,80 @@
+require "time"
+require "timeout"
+
+module Textus
+  class Projection
+    MAX_LIMIT = 1000
+    REDUCER_TIMEOUT_SECONDS = 2
+
+    def initialize(store, spec)
+      @store = store
+      @spec = spec || {}
+      @limit = (@spec["limit"] || MAX_LIMIT).to_i
+      raise InvalidProjection.new("limit #{@limit} exceeds max #{MAX_LIMIT}") if @limit > MAX_LIMIT
+    end
+
+    def run
+      keys = collect_keys
+      explicit_pluck = !@spec["pluck"].nil? && @spec["pluck"] != "*"
+      rows = keys.map do |key|
+        env = @store.get(key)
+        row = pluck(env["frontmatter"], env["body"])
+        explicit_pluck ? row : row.merge("_key" => key)
+      end
+      reduced = apply_reducer(rows)
+      # Reducers may return either an Array of rows (legacy / templated builds)
+      # or a Hash that becomes the structured-format payload base. In the Hash
+      # case, downstream sort/limit/position markers don't apply, and the
+      # builder owns `_meta.generated_at` so we don't stamp it here.
+      return reduced if reduced.is_a?(Hash)
+
+      rows = reduced
+      rows = sort(rows)
+      rows = rows.first(@limit)
+      mark_positions(rows)
+      { "entries" => rows, "count" => rows.length, "generated_at" => Time.now.utc.iso8601 }
+    end
+
+    private
+
+    def apply_reducer(rows)
+      name = @spec["reducer"] or return rows
+      callable = @store.registry.reducer(name)
+      Timeout.timeout(REDUCER_TIMEOUT_SECONDS) do
+        callable.call(rows: rows, config: @spec["reducer_config"] || {})
+      end
+    rescue Timeout::Error
+      raise UsageError.new("reducer '#{name}' exceeded #{REDUCER_TIMEOUT_SECONDS}s timeout")
+    end
+
+    def collect_keys
+      prefixes = Array(@spec["select"])
+      prefixes.flat_map { |p| @store.list(prefix: p).map { |row| row["key"] } }.uniq
+    end
+
+    def pluck(frontmatter, _body)
+      fields = @spec["pluck"]
+      if fields.nil? || fields == "*"
+        frontmatter
+      else
+        Array(fields).each_with_object({}) { |f, h| h[f] = frontmatter[f] if frontmatter.key?(f) }
+      end
+    end
+
+    # Adds `_first`, `_last`, and `_index` markers so templates can emit
+    # delimiters (e.g. JSON commas) via {{^_last}},{{/_last}}.
+    def mark_positions(rows)
+      last_idx = rows.length - 1
+      rows.each_with_index do |row, i|
+        row["_index"] = i
+        row["_first"] = i.zero?
+        row["_last"]  = (i == last_idx)
+      end
+    end
+
+    def sort(rows)
+      sb = @spec["sort_by"] or return rows
+      rows.sort_by { |r| r[sb].to_s }
+    end
+  end
+end

data/lib/textus/proposal.rb

@@ -0,0 +1,27 @@
+module Textus
+  module Proposal
+    def self.accept(store, pending_key, as:)
+      raise ProposalError.new("only human role can accept proposals; got '#{as}'") unless as == "human"
+
+      env = store.get(pending_key)
+      proposal = env["frontmatter"]["proposal"] or raise ProposalError.new("entry has no proposal block: #{pending_key}")
+      target = proposal["target_key"] or raise ProposalError.new("proposal missing target_key")
+      action = proposal["action"] || "put"
+
+      case action
+      when "put"
+        target_fm = env["frontmatter"]["frontmatter"] || {}
+        target_body = env["body"]
+        store.put(target, frontmatter: target_fm, body: target_body, as: "human")
+      when "delete"
+        store.delete(target, as: "human")
+      else
+        raise ProposalError.new("unknown action: #{action}")
+      end
+
+      store.delete(pending_key, as: "human")
+      store.fire_event(:accept, pending_key: pending_key, target_key: target)
+      { "protocol" => PROTOCOL, "accepted" => pending_key, "target_key" => target, "action" => action }
+    end
+  end
+end

data/lib/textus/publisher.rb

@@ -0,0 +1,71 @@
+require "json"
+require "digest"
+require "fileutils"
+
+module Textus
+  # Publishes built artifacts from the store to repo-relative consumer paths.
+  # Publish = copy + sentinel. The in-store file is already the consumer-shaped
+  # artifact; no parsing or stripping. Sentinels live under
+  # `<store_root>/sentinels/` and mirror the target's repo-relative layout so
+  # consumer directories aren't polluted with `.textus-managed.json` siblings.
+  module Publisher
+    SENTINEL_SUFFIX = ".textus-managed.json".freeze
+    SENTINEL_DIR    = "sentinels".freeze
+
+    def self.publish(source:, target:, store_root:)
+      FileUtils.mkdir_p(File.dirname(target))
+      refuse_if_unmanaged(target, store_root)
+      File.delete(target) if File.symlink?(target)
+      FileUtils.cp(source, target)
+      write_sentinel(target, store_root: store_root, source: source)
+      cleanup_legacy_sentinel(target)
+    end
+
+    def self.refuse_if_unmanaged(target, store_root)
+      return unless File.exist?(target) || File.symlink?(target)
+      return if managed?(target, store_root)
+
+      raise PublishError.new("refusing to clobber unmanaged file at #{target}", target: target)
+    end
+
+    def self.managed?(target, store_root)
+      File.exist?(sentinel_path(target, store_root)) || File.exist?(legacy_sentinel_path(target))
+    end
+
+    def self.write_sentinel(target, store_root:, source:)
+      path = sentinel_path(target, store_root)
+      FileUtils.mkdir_p(File.dirname(path))
+      File.write(path, JSON.generate(
+                         "source" => source,
+                         "target" => target,
+                         "sha256" => Digest::SHA256.hexdigest(File.binread(target)),
+                         "mode" => "copy",
+                       ))
+    end
+
+    # Sentinel layout: <store_root>/sentinels/<target_rel_to_repo>.textus-managed.json
+    # The full target extension is preserved so a marketplace.json and
+    # marketplace.yaml don't collide.
+    def self.sentinel_path(target, store_root)
+      repo_root = File.dirname(store_root)
+      rel = relative_to(target, repo_root) || File.basename(target)
+      File.join(store_root, SENTINEL_DIR, rel + SENTINEL_SUFFIX)
+    end
+
+    def self.legacy_sentinel_path(target)
+      target + SENTINEL_SUFFIX
+    end
+
+    def self.cleanup_legacy_sentinel(target)
+      FileUtils.rm_f(legacy_sentinel_path(target))
+    end
+
+    def self.relative_to(path, base)
+      path = File.expand_path(path)
+      base = File.expand_path(base)
+      return nil unless path.start_with?(base + File::SEPARATOR)
+
+      path[(base.length + 1)..]
+    end
+  end
+end

data/lib/textus/refresh.rb

@@ -0,0 +1,75 @@
+require "timeout"
+
+module Textus
+  module Refresh
+    FETCHER_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
+
+      before_etag = File.exist?(path) ? Etag.for_file(path) : nil
+      callable = store.registry.fetcher(mentry.fetcher)
+      view = StoreView.new(store)
+      result =
+        begin
+          Timeout.timeout(FETCHER_TIMEOUT_SECONDS) { callable.call(config: mentry.fetcher_config, store: view) }
+        rescue Timeout::Error
+          raise UsageError.new("fetcher '#{mentry.fetcher}' exceeded #{FETCHER_TIMEOUT_SECONDS}s timeout")
+        rescue Textus::Error
+          raise
+        rescue StandardError => e
+          raise UsageError.new("fetcher '#{mentry.fetcher}' raised: #{e.class}: #{e.message}")
+        end
+
+      normalized = normalize_fetcher_result(result, format: mentry.format)
+      envelope = store.put(
+        key,
+        frontmatter: normalized[:frontmatter],
+        body: normalized[:body],
+        content: normalized[:content],
+        as: as,
+        suppress_events: true,
+      )
+
+      change = if before_etag.nil?
+                 :created
+               elsif envelope["etag"] == before_etag
+                 :unchanged
+               else
+                 :updated
+               end
+      store.fire_event(:refresh, key: key, envelope: envelope, change: change) unless change == :unchanged
+      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:)
+      res = res.transform_keys(&:to_s) if res.is_a?(Hash)
+      res ||= {}
+      fm      = res["frontmatter"]
+      body    = res["body"]
+      content = res["content"]
+
+      case format
+      when "markdown"
+        { frontmatter: fm || {}, body: body.to_s, content: nil }
+      when "text"
+        { frontmatter: {}, body: body.to_s, content: nil }
+      when "json", "yaml"
+        if !content.nil?
+          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")
+        end
+      else
+        raise UsageError.new("unknown format #{format.inspect}")
+      end
+    end
+  end
+end

data/lib/textus/role.rb

@@ -0,0 +1,20 @@
+module Textus
+  module Role
+    PATTERN = /\A[a-z][a-z0-9_-]*\z/
+    DEFAULT = "human".freeze
+
+    def self.resolve(root:, flag: nil, env: ENV)
+      candidate = flag || env["TEXTUS_ROLE"] || read_file(root) || DEFAULT
+      raise InvalidRole.new(candidate) unless candidate.match?(PATTERN)
+
+      candidate
+    end
+
+    def self.read_file(root)
+      path = File.join(root, "role")
+      return nil unless File.exist?(path)
+
+      File.read(path).strip.then { |s| s.empty? ? nil : s }
+    end
+  end
+end

data/lib/textus/schema.rb

@@ -0,0 +1,90 @@
+require "yaml"
+
+module Textus
+  class Schema
+    attr_reader :name, :required, :optional, :fields, :raw
+
+    def self.load(path)
+      raw = YAML.safe_load_file(path, permitted_classes: [Symbol, Date, Time], aliases: false)
+      new(raw)
+    end
+
+    def initialize(raw)
+      @raw = raw || {}
+      @name = @raw["name"]
+      @required = Array(@raw["required"])
+      @optional = Array(@raw["optional"])
+      @fields = @raw["fields"] || {}
+    end
+
+    def to_h
+      @raw
+    end
+
+    def maintained_by(field)
+      meta = @fields[field] or return nil
+      meta["maintained_by"]
+    end
+
+    def evolution
+      raw = @raw["evolution"] || {}
+      raw.each_with_object({}) do |(k, v), h|
+        h[k] = v.is_a?(Date) || v.is_a?(Time) ? v.to_s : v
+      end
+    end
+
+    # Returns nil on success; raises SchemaViolation on hard failure.
+    # Unknown fields produce warnings, returned as a String[] alongside.
+    def validate!(frontmatter)
+      missing = @required - frontmatter.keys
+      raise SchemaViolation.new("missing" => missing) unless missing.empty?
+
+      known = (@required + @optional).uniq
+      frontmatter.each do |k, v|
+        next unless @fields.key?(k)
+
+        check_type!(k, v, @fields[k])
+      end
+
+      warnings = frontmatter.keys - known
+      warnings.map { |w| "unknown field: #{w}" }
+    end
+
+    private
+
+    def check_type!(field, value, spec) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      type = spec["type"]
+      case type
+      when "string"
+        bad!(field, "expected string") unless value.is_a?(String)
+        if (max = spec["max"]) && value.bytesize > max
+          bad!(field, "exceeds max #{max}")
+        end
+      when "number"
+        bad!(field, "expected number") unless value.is_a?(Numeric)
+      when "boolean"
+        bad!(field, "expected boolean") unless [true, false].include?(value)
+      when "enum"
+        values = Array(spec["values"])
+        bad!(field, "not in enum #{values.inspect}") unless values.include?(value)
+      when "array"
+        bad!(field, "expected array") unless value.is_a?(Array)
+        if (items = spec["items"])
+          value.each_with_index { |v, i| check_type!("#{field}[#{i}]", v, items) }
+        end
+      when "object"
+        bad!(field, "expected object") unless value.is_a?(Hash)
+        if (sub = spec["fields"])
+          sub.each { |fk, fspec| check_type!("#{field}.#{fk}", value[fk], fspec) if value.key?(fk) }
+        end
+      when nil
+        # untyped — no check
+        # unknown type spec — vendor extension; ignore
+      end
+    end
+
+    def bad!(field, reason)
+      raise SchemaViolation.new("field" => field, "reason" => reason)
+    end
+  end
+end

data/lib/textus/schema_tools.rb

@@ -0,0 +1,87 @@
+require "yaml"
+require "fileutils"
+
+module Textus
+  module SchemaTools
+    # textus schema-init NAME --from=KEY  → infer YAML schema from an entry's frontmatter
+    def self.init(store, name:, from:)
+      env = store.get(from)
+      fm = env["frontmatter"]
+      schema = {
+        "name" => name,
+        "required" => fm.keys,
+        "optional" => [],
+        "fields" => fm.each_with_object({}) { |(k, v), h| h[k] = { "type" => infer_type(v) } },
+      }
+      FileUtils.mkdir_p(File.join(store.root, "schemas"))
+      target = File.join(store.root, "schemas", "#{name}.yaml")
+      File.write(target, YAML.dump(schema))
+      { "protocol" => PROTOCOL, "schema_name" => name, "path" => target }
+    end
+
+    # textus schema-diff NAME  → list keys whose frontmatter violates the schema
+    def self.diff(store, name:)
+      schema = load_schema(store, name)
+      drift = []
+      store.manifest.enumerate.each do |row|
+        env = store.get(row[:key])
+        begin
+          schema.validate!(env["frontmatter"])
+        rescue SchemaViolation => e
+          drift << { "key" => row[:key], "details" => e.details }
+        end
+      end
+      { "protocol" => PROTOCOL, "schema_name" => name, "drift" => drift }
+    end
+
+    # textus schema-migrate NAME --rename=OLD:NEW → rewrites frontmatter across affected entries
+    # If --rename is omitted, falls back to schema.evolution.migrate_from.
+    def self.migrate(store, name:, rename: nil)
+      renames =
+        if rename
+          old_field, new_field = rename.split(":", 2)
+          raise UsageError.new("--rename=OLD:NEW") unless old_field && new_field && !new_field.empty?
+
+          { old_field => new_field }
+        else
+          load_schema(store, name).evolution["migrate_from"] || {}
+        end
+      raise UsageError.new("schema-migrate needs --rename=OLD:NEW or schema.evolution.migrate_from") if renames.empty?
+
+      touched = []
+      store.manifest.enumerate.each do |row|
+        env = store.get(row[:key])
+        fm = env["frontmatter"]
+        changed = false
+        renames.each do |old, new|
+          if fm.key?(old)
+            fm[new] = fm.delete(old)
+            changed = true
+          end
+        end
+        next unless changed
+
+        store.put(row[:key], frontmatter: fm, body: env["body"], as: "human")
+        touched << row[:key]
+      end
+      { "protocol" => PROTOCOL, "migrated" => touched, "renames" => renames }
+    end
+
+    def self.infer_type(value)
+      case value
+      when String  then "string"
+      when Numeric then "number"
+      when true, false then "boolean"
+      when Array   then "array"
+      when Hash    then "object"
+      else "string"
+      end
+    end
+
+    def self.load_schema(store, name)
+      store.schema_for(name)
+    rescue IoError
+      raise UsageError.new("schema not found: #{name}")
+    end
+  end
+end