textus 0.2.0

data/lib/textus/cli.rb

@@ -0,0 +1,394 @@
+require "json"
+require "optparse"
+require "time"
+require "timeout"
+require "yaml"
+
+module Textus
+  # rubocop:disable Metrics/ClassLength
+  class CLI
+    def self.run(argv, stdin: $stdin, stdout: $stdout, stderr: $stderr, cwd: Dir.pwd)
+      new(stdin: stdin, stdout: stdout, stderr: stderr, cwd: cwd).run(argv)
+    end
+
+    def initialize(stdin:, stdout:, stderr:, cwd:)
+      @stdin = stdin
+      @stdout = stdout
+      @stderr = stderr
+      @cwd = cwd
+    end
+
+    def run(argv) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize
+      verb = argv.shift
+      raise UsageError.new("missing verb") if verb.nil?
+
+      case verb
+      when "list"   then verb_list(argv)
+      when "where"  then verb_where(argv)
+      when "get"    then verb_get(argv)
+      when "put"    then verb_put(argv)
+      when "schema" then verb_schema(argv)
+      when "stale"  then verb_stale(argv)
+      when "delete"       then verb_delete(argv)
+      when "validate-all" then verb_validate_all(argv)
+      when "build"        then verb_build(argv)
+      when "deps"         then verb_deps(argv)
+      when "rdeps"        then verb_rdeps(argv)
+      when "published"    then verb_published(argv)
+      when "accept"       then verb_accept(argv)
+      when "init"         then verb_init(argv)
+      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 "refresh"        then verb_refresh(argv)
+      when "extensions"     then verb_extensions(argv)
+      when "migrate-keys"   then verb_migrate_keys(argv)
+      when "mv"             then verb_mv(argv)
+      when "uid"            then verb_uid(argv)
+      when "doctor"         then verb_doctor(argv)
+      when "intro"          then verb_intro(argv)
+      when "--version", "-v" then @stdout.puts(VERSION)
+                                  0
+      when "--help", "-h"    then print_help
+                                  0
+      else raise UsageError.new("unknown verb: #{verb}")
+      end
+    rescue Textus::Error => e
+      emit_error(e)
+    end
+
+    private
+
+    def store
+      @store ||= Store.discover(@cwd)
+    end
+
+    def parse_format!(argv)
+      fmt = "text"
+      OptionParser.new do |o|
+        o.on("--format=FMT") { |v| fmt = v }
+      end.permute!(argv)
+      raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
+
+      fmt
+    end
+
+    def parse_prefix!(argv)
+      prefix = nil
+      OptionParser.new do |o|
+        o.on("--prefix=KEY") { |v| prefix = v }
+        o.on("--zone=Z") {}
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      prefix
+    end
+
+    def parse_prefix_and_zone!(argv)
+      prefix = nil
+      zone = nil
+      fmt = "text"
+      OptionParser.new do |o|
+        o.on("--prefix=KEY") { |v| prefix = v }
+        o.on("--zone=Z") { |v| zone = v }
+        o.on("--format=FMT") { |v| fmt = v }
+      end.permute!(argv)
+      raise UsageError.new("only --format=json is supported in v1") unless fmt == "json"
+
+      [prefix, zone]
+    end
+
+    def verb_list(argv)
+      prefix, zone = parse_prefix_and_zone!(argv)
+      emit({ "protocol" => PROTOCOL, "entries" => store.list(prefix: prefix, zone: zone) })
+    end
+
+    def verb_where(argv)
+      key = argv.shift or raise UsageError.new("where requires a key")
+      parse_format!(argv)
+      emit(store.where(key))
+    end
+
+    def verb_get(argv)
+      key = argv.shift or raise UsageError.new("get requires a key")
+      parse_format!(argv)
+      emit(store.get(key))
+    end
+
+    def verb_schema(argv)
+      key = argv.shift or raise UsageError.new("schema requires a key")
+      parse_format!(argv)
+      emit(store.schema_envelope(key))
+    end
+
+    def verb_stale(argv)
+      prefix, zone = parse_prefix_and_zone!(argv)
+      emit(store.stale(prefix: prefix, zone: zone))
+    end
+
+    def verb_put(argv) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      key = argv.shift or raise UsageError.new("put requires a key")
+      as_flag = nil
+      use_stdin = false
+      fetcher_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("--format=FMT") {}
+      end.permute!(argv)
+      raise UsageError.new("put requires --stdin in v1") unless use_stdin
+
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+
+      raw = @stdin.read
+      payload =
+        if fetcher_name
+          callable = store.registry.fetcher(fetcher_name)
+          result =
+            begin
+              Timeout.timeout(Textus::Refresh::FETCHER_TIMEOUT_SECONDS) do
+                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store))
+              end
+            rescue Timeout::Error
+              raise UsageError.new(
+                "fetcher '#{fetcher_name}' exceeded #{Textus::Refresh::FETCHER_TIMEOUT_SECONDS}s timeout",
+              )
+            end
+          basename = key.split(".").last
+          {
+            "frontmatter" => {
+              "name" => basename,
+              "last_refreshed_at" => Time.now.utc.iso8601,
+              "fetched_with" => fetcher_name,
+            }.merge(result[:frontmatter] || result["frontmatter"] || {}),
+            "body" => result[:body] || result["body"] || "",
+          }
+        else
+          JSON.parse(raw)
+        end
+
+      fm = payload["frontmatter"] || {}
+      body = payload["body"] || ""
+      if_etag = payload["if_etag"]
+      emit(store.put(key, frontmatter: fm, body: body, if_etag: if_etag, as: role))
+    end
+
+    def verb_delete(argv)
+      key = argv.shift or raise UsageError.new("delete requires a key")
+      as_flag = nil
+      if_etag = nil
+      OptionParser.new do |o|
+        o.on("--as=ROLE") { |v| as_flag = v }
+        o.on("--if-etag=E") { |v| if_etag = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+      emit(store.delete(key, if_etag: if_etag, as: role))
+    end
+
+    def verb_validate_all(argv)
+      parse_format!(argv)
+      res = store.validate_all
+      @stdout.puts(JSON.generate(res))
+      res["ok"] ? 0 : 1
+    end
+
+    def verb_build(argv)
+      prefix = nil
+      OptionParser.new do |o|
+        o.on("--prefix=K") { |v| prefix = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      res = Textus::Builder.new(store).build(prefix: prefix)
+      @stdout.puts(JSON.generate(res))
+      0
+    end
+
+    def verb_deps(argv)
+      key = argv.shift or raise UsageError.new("deps requires a key")
+      parse_format!(argv)
+      emit({ "protocol" => Textus::PROTOCOL, "key" => key, "deps" => store.deps(key) })
+    end
+
+    def verb_rdeps(argv)
+      key = argv.shift or raise UsageError.new("rdeps requires a key")
+      parse_format!(argv)
+      emit({ "protocol" => Textus::PROTOCOL, "key" => key, "rdeps" => store.rdeps(key) })
+    end
+
+    def verb_schema_init(argv)
+      name = argv.shift or raise UsageError.new("schema-init NAME")
+      from_key = nil
+      OptionParser.new do |o|
+        o.on("--from=KEY") { |v| from_key = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      raise UsageError.new("schema-init requires --from=KEY") unless from_key
+
+      emit(Textus::SchemaTools.init(store, name: name, from: from_key))
+    end
+
+    def verb_schema_diff(argv)
+      name = argv.shift or raise UsageError.new("schema-diff NAME")
+      parse_format!(argv)
+      emit(Textus::SchemaTools.diff(store, name: name))
+    end
+
+    def verb_schema_migrate(argv)
+      name = argv.shift or raise UsageError.new("schema-migrate NAME")
+      rename = nil
+      OptionParser.new do |o|
+        o.on("--rename=O:N") { |v| rename = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      raise UsageError.new("schema-migrate requires --rename=OLD:NEW") unless rename
+
+      emit(Textus::SchemaTools.migrate(store, name: name, rename: rename))
+    end
+
+    def verb_init(argv)
+      OptionParser.new do |o|
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      target = File.join(@cwd, ".textus")
+      res = Textus::Init.run(target)
+      @stdout.puts(JSON.generate(res))
+      0
+    end
+
+    def verb_accept(argv)
+      key = argv.shift or raise UsageError.new("accept requires a key")
+      as_flag = nil
+      OptionParser.new do |o|
+        o.on("--as=ROLE") { |v| as_flag = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+      emit(store.accept(key, as: role))
+    end
+
+    def verb_refresh(argv)
+      key = argv.shift or raise UsageError.new("refresh requires a key")
+      as_flag = nil
+      OptionParser.new do |o|
+        o.on("--as=ROLE") { |v| as_flag = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+      emit(Textus::Refresh.call(store, key, as: role))
+    end
+
+    def verb_extensions(argv) # rubocop:disable Metrics/AbcSize
+      subcommand = argv.shift
+      raise UsageError.new("extensions requires 'list'") unless subcommand == "list"
+
+      kind = nil
+      OptionParser.new do |o|
+        o.on("--kind=K") { |v| kind = v }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+
+      rows = []
+      rows += store.registry.fetcher_names.map { |n| { "kind" => "fetcher", "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|
+          rows << { "kind" => "hook", "event" => evt.to_s, "name" => h[:name].to_s }
+        end
+      end
+      store.manifest.entries.each do |e|
+        e.events.each do |evt, defs|
+          Array(defs).each do |defn|
+            next unless defn["exec"]
+
+            rows << {
+              "kind" => "hook", "event" => evt.to_s, "exec" => defn["exec"],
+              "key" => e.key, "as" => defn["as"] || "script"
+            }
+          end
+        end
+      end
+      rows.select! { |r| r["kind"] == kind } if kind
+
+      emit({ "protocol" => Textus::PROTOCOL, "extensions" => rows })
+    end
+
+    def verb_migrate_keys(argv)
+      write = false
+      OptionParser.new do |o|
+        o.on("--dry-run") { write = false }
+        o.on("--write")   { write = true }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      res = Textus::MigrateKeys.run(store, write: write)
+      @stdout.puts(JSON.generate(res))
+      res["ok"] ? 0 : 1
+    end
+
+    def verb_mv(argv)
+      old_key = argv.shift or raise UsageError.new("mv requires <old-key> <new-key>")
+      new_key = argv.shift or raise UsageError.new("mv requires <old-key> <new-key>")
+      as_flag = nil
+      dry_run = false
+      OptionParser.new do |o|
+        o.on("--as=ROLE") { |v| as_flag = v }
+        o.on("--dry-run") { dry_run = true }
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+      emit(store.mv(old_key, new_key, as: role, dry_run: dry_run))
+    end
+
+    def verb_uid(argv)
+      key = argv.shift or raise UsageError.new("uid requires a key")
+      parse_format!(argv)
+      emit({ "protocol" => PROTOCOL, "key" => key, "uid" => store.uid(key) })
+    end
+
+    def verb_intro(argv)
+      parse_format!(argv)
+      emit(Textus::Intro.run(store))
+    end
+
+    def verb_doctor(argv)
+      OptionParser.new do |o|
+        o.on("--format=FMT") {}
+      end.permute!(argv)
+      res = Textus::Doctor.run(store)
+      @stdout.puts(JSON.generate(res))
+      res["ok"] ? 0 : 1
+    end
+
+    def verb_published(argv)
+      parse_format!(argv)
+      emit({ "protocol" => Textus::PROTOCOL, "published" => store.published })
+    end
+
+    def emit(obj)
+      @stdout.puts(JSON.generate(obj))
+      0
+    end
+
+    def emit_error(err)
+      @stdout.puts(JSON.generate(err.to_envelope))
+      @stderr.puts("#{err.code}: #{err.message}")
+      @stderr.puts("  → #{err.hint}") if err.hint
+      err.exit_code
+    end
+
+    def print_help
+      @stdout.puts <<~HELP
+        textus #{VERSION} — reference implementation of #{PROTOCOL}
+
+        Usage:
+          textus list [--prefix=KEY] --format=json
+          textus where KEY --format=json
+          textus get KEY --format=json
+          textus put KEY --stdin --format=json
+          textus schema KEY --format=json
+          textus stale [--prefix=KEY] --format=json
+      HELP
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/textus/dependencies.rb

@@ -0,0 +1,23 @@
+module Textus
+  module Dependencies
+    def self.deps_of(manifest, key)
+      entry = manifest.entries.find { |e| e.key == key } or return []
+      result = Array(entry.projection&.fetch("select", nil)).map { |s| s }
+      Array(entry.generator&.fetch("sources", nil)).each { |s| result << s }
+      result.uniq
+    end
+
+    def self.rdeps_of(manifest, key)
+      manifest.entries.each_with_object([]) do |e, acc|
+        sources = Array(e.projection&.fetch("select", nil)) + Array(e.generator&.fetch("sources", nil))
+        acc << e.key if sources.any? { |s| s == key || key.start_with?("#{s}.") }
+      end
+    end
+
+    def self.published_of(manifest)
+      manifest.entries.reject { |e| e.publish_to.empty? }.map do |e|
+        { "key" => e.key, "publish_to" => e.publish_to }
+      end
+    end
+  end
+end

data/lib/textus/doctor.rb

@@ -0,0 +1,281 @@
+require "digest"
+require "json"
+
+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
+    LEVELS = %w[error warning info].freeze
+
+    module_function
+
+    def run(store)
+      issues = []
+      issues.concat(check_manifest_files(store))
+      issues.concat(check_schemas(store))
+      issues.concat(check_templates(store))
+      issues.concat(check_extensions(store))
+      issues.concat(check_illegal_keys(store))
+      issues.concat(check_sentinels(store))
+      issues.concat(check_audit_log(store))
+      issues.concat(check_unowned_schema_fields(store))
+
+      summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
+      {
+        "protocol" => Textus::PROTOCOL,
+        "ok" => summary["error"].zero?,
+        "issues" => issues,
+        "summary" => summary,
+      }
+    end
+
+    # --- Checks -----------------------------------------------------------
+
+    def check_manifest_files(store)
+      out = []
+      store.manifest.entries.each do |entry|
+        next if entry.nested
+
+        path = leaf_path_for(store, entry)
+        next if File.exist?(path)
+
+        out << {
+          "code" => "manifest.missing_file",
+          "level" => "info",
+          "subject" => entry.key,
+          "message" => "declared entry has no file on disk at #{path}",
+          "fix" => "create the entry with 'textus put #{entry.key} --stdin --as=<role>' " \
+                   "(or leave empty if not yet authored)",
+        }
+      end
+      out
+    end
+
+    def check_schemas(store)
+      out = []
+      store.manifest.entries.each do |entry|
+        next if entry.schema.nil?
+
+        sp = File.join(store.root, "schemas", "#{entry.schema}.yaml")
+        next if File.exist?(sp)
+
+        out << {
+          "code" => "schema.missing",
+          "level" => "error",
+          "subject" => entry.key,
+          "message" => "schema '#{entry.schema}' not found at #{sp}",
+          "fix" => "create the schema file or run 'textus schema-init #{entry.schema} --from=<key>'",
+        }
+      end
+      out
+    end
+
+    def check_templates(store)
+      out = []
+      store.manifest.entries.each do |entry|
+        next if entry.template.nil?
+
+        tp = File.join(store.root, "templates", entry.template)
+        next if File.exist?(tp)
+
+        out << {
+          "code" => "template.missing",
+          "level" => "error",
+          "subject" => entry.key,
+          "message" => "template '#{entry.template}' not found at #{tp}",
+          "fix" => "create the file at #{tp} or update the entry's template: field",
+        }
+      end
+      out
+    end
+
+    def check_extensions(store)
+      out = []
+      dir = File.join(store.root, "extensions")
+      return out unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
+        registry = ExtensionRegistry.new
+        Textus.with_registry(registry) do
+          load(f)
+        end
+      rescue StandardError, ScriptError => e
+        out << {
+          "code" => "extension.load_failed",
+          "level" => "error",
+          "subject" => File.basename(f),
+          "message" => "#{e.class}: #{e.message}",
+          "fix" => "open #{f} and fix the syntax/load error",
+        }
+      end
+      out
+    end
+
+    def check_illegal_keys(store)
+      out = []
+      store.manifest.entries.each do |entry|
+        next unless entry.nested
+
+        base = File.join(store.root, "zones", entry.path)
+        next unless File.directory?(base)
+
+        walk_nested(base) do |abs_path, is_dir|
+          basename = File.basename(abs_path)
+          stem = is_dir ? basename : basename.sub(/#{Regexp.escape(File.extname(basename))}\z/, "")
+          next if stem.match?(Manifest::KEY_SEGMENT)
+
+          proposed = Textus::MigrateKeys.normalize(stem)
+          out << {
+            "code" => "key.illegal",
+            "level" => "error",
+            "subject" => abs_path,
+            "path" => abs_path,
+            "proposed_key" => proposed,
+            "message" => "illegal key segment '#{stem}' at #{abs_path}",
+            "fix" => "run 'textus migrate-keys --dry-run' then '--write' to rename to '#{proposed}'",
+          }
+        end
+      end
+      out
+    end
+
+    def check_sentinels(store)
+      out = []
+      dir = File.join(store.root, "sentinels")
+      return out unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "**", "*.textus-managed.json")).each do |sp| # rubocop:disable Metrics/BlockLength
+        begin
+          data = JSON.parse(File.read(sp))
+        rescue JSON::ParserError => e
+          out << {
+            "code" => "sentinel.parse_error",
+            "level" => "warning",
+            "subject" => sp,
+            "message" => "sentinel is not valid JSON: #{e.message}",
+            "fix" => "delete #{sp} and re-run 'textus build' to regenerate",
+          }
+          next
+        end
+
+        target = data["target"]
+        recorded_sha = data["sha256"]
+
+        if target.nil? || !File.exist?(target)
+          out << {
+            "code" => "sentinel.orphan",
+            "level" => "warning",
+            "subject" => sp,
+            "message" => "sentinel target #{target.inspect} no longer exists",
+            "fix" => "delete #{sp} (the published file is gone) or restore the target",
+          }
+          next
+        end
+
+        current_sha = Digest::SHA256.hexdigest(File.binread(target))
+        next if recorded_sha.nil? || current_sha == recorded_sha
+
+        out << {
+          "code" => "sentinel.drift",
+          "level" => "warning",
+          "subject" => target,
+          "message" => "published file at #{target} was modified out-of-band",
+          "fix" => "re-run 'textus build' to overwrite, or copy the manual edit back into the store source",
+        }
+      end
+      out
+    end
+
+    def check_audit_log(store)
+      out = []
+      path = File.join(store.root, "audit.log")
+      return out unless File.exist?(path)
+
+      File.foreach(path).with_index(1) do |line, lineno| # rubocop:disable Metrics/BlockLength
+        stripped = line.chomp
+        next if stripped.empty?
+
+        # Audit log is TSV, not NDJSON. Treat as malformed if it doesn't have
+        # at least 6 tab-separated fields (timestamp, role, verb, key, etag_before, etag_after).
+        fields = stripped.split("\t")
+        if fields.length < 6
+          out << {
+            "code" => "audit.parse_error",
+            "level" => "warning",
+            "subject" => "#{path}:#{lineno}",
+            "message" => "audit log line #{lineno} has #{fields.length} fields (expected >=6)",
+            "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
+          }
+          next
+        end
+
+        extras = fields[6]
+        next if extras.nil? || extras.empty?
+
+        begin
+          JSON.parse(extras)
+        rescue JSON::ParserError => e
+          out << {
+            "code" => "audit.parse_error",
+            "level" => "warning",
+            "subject" => "#{path}:#{lineno}",
+            "message" => "audit log line #{lineno} extras JSON malformed: #{e.message}",
+            "fix" => "inspect #{path} at line #{lineno} and fix the JSON in the last column",
+          }
+        end
+      end
+      out
+    end
+
+    def check_unowned_schema_fields(store)
+      out = []
+      dir = File.join(store.root, "schemas")
+      return out unless File.directory?(dir)
+
+      Dir.glob(File.join(dir, "*.yaml")).sort.each do |sp| # rubocop:disable Lint/RedundantDirGlobSort
+        schema = begin
+          Schema.load(sp)
+        rescue StandardError
+          next
+        end
+        unowned = schema.fields.each_with_object([]) do |(name, spec), acc|
+          acc << name if spec.is_a?(Hash) && spec["maintained_by"].nil?
+        end
+        next if unowned.empty?
+
+        out << {
+          "code" => "schema.unowned_fields",
+          "level" => "info",
+          "subject" => schema.name || File.basename(sp, ".yaml"),
+          "message" => "schema has fields without maintained_by: #{unowned.join(", ")}",
+          "fix" => "add 'maintained_by: <role>' to each field in #{sp} (optional but recommended)",
+        }
+      end
+      out
+    end
+
+    # --- Helpers ----------------------------------------------------------
+
+    def leaf_path_for(store, entry)
+      primary_ext = Entry.for_format(entry.format).extensions.first
+      if File.extname(entry.path) == ""
+        File.join(store.root, "zones", entry.path + primary_ext)
+      else
+        File.join(store.root, "zones", entry.path)
+      end
+    end
+
+    def walk_nested(root, &block)
+      Dir.each_child(root) do |name|
+        abs = File.join(root, name)
+        if File.directory?(abs)
+          walk_nested(abs, &block)
+          yield abs, true
+        else
+          yield abs, false
+        end
+      end
+    end
+  end
+end