textus 0.5.0 → 0.8.0

data/lib/textus/cli/verb/refresh.rb

@@ -0,0 +1,15 @@
+module Textus
+  class CLI
+    class Verb
+      class Refresh < Verb
+        option :as_flag, "--as=ROLE"
+
+        def call(store)
+          key = positional.shift or raise UsageError.new("refresh requires a key")
+          role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
+          emit(Textus::Refresh.call(store, key, as: role))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/schema.rb

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Verb
+      class Schema < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("schema requires a key")
+          emit(store.schema_envelope(key))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/schema_diff.rb

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Verb
+      class SchemaDiff < Verb
+        def call(store)
+          name = positional.shift or raise UsageError.new("schema diff NAME")
+          emit(Textus::Schema::Tools.diff(store, name: name))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/schema_init.rb

@@ -0,0 +1,16 @@
+module Textus
+  class CLI
+    class Verb
+      class SchemaInit < Verb
+        option :from_key, "--from=KEY"
+
+        def call(store)
+          name = positional.shift or raise UsageError.new("schema init NAME")
+          raise UsageError.new("schema init requires --from=KEY") unless from_key
+
+          emit(Textus::Schema::Tools.init(store, name: name, from: from_key))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/schema_migrate.rb

@@ -0,0 +1,16 @@
+module Textus
+  class CLI
+    class Verb
+      class SchemaMigrate < Verb
+        option :rename, "--rename=O:N"
+
+        def call(store)
+          name = positional.shift or raise UsageError.new("schema migrate NAME")
+          raise UsageError.new("schema migrate requires --rename=OLD:NEW") unless rename
+
+          emit(Textus::Schema::Tools.migrate(store, name: name, rename: rename))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/stale.rb

@@ -0,0 +1,14 @@
+module Textus
+  class CLI
+    class Verb
+      class Stale < Verb
+        option :prefix, "--prefix=KEY"
+        option :zone, "--zone=Z"
+
+        def call(store)
+          emit(store.stale(prefix: prefix, zone: zone))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/uid.rb

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Verb
+      class Uid < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("uid requires a key")
+          emit({ "key" => key, "uid" => store.uid(key) })
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli/verb/where.rb

@@ -0,0 +1,12 @@
+module Textus
+  class CLI
+    class Verb
+      class Where < Verb
+        def call(store)
+          key = positional.shift or raise UsageError.new("where requires a key")
+          emit(store.where(key))
+        end
+      end
+    end
+  end
+end

data/lib/textus/cli.rb

@@ -6,40 +6,26 @@ module Textus
     # verb name → Verb subclass. Adding a new verb is a one-line entry here
     # plus a new file under lib/textus/cli/.
     VERBS = {
-      "accept" => Accept,
-      "action" => Action,
-      "build" => Build,
-      "delete" => Delete,
-      "deps" => Deps,
-      "doctor" => DoctorVerb,
-      "extension" => ExtensionGroup,
-      "extensions" => Extensions,
-      "get" => Get,
-      "init" => InitVerb,
-      "intro" => IntroVerb,
-      "key" => KeyGroup,
-      "list" => List,
-      "migrate" => Migrate,
-      "migrate-keys" => MigrateKeysVerb,
-      "mv" => Mv,
-      "published" => Published,
-      "put" => Put,
-      "rdeps" => Rdeps,
-      "refresh" => RefreshVerb,
-      "schema" => SchemaGroup,
-      "schema-diff" => SchemaDiff,
-      "schema-init" => SchemaInit,
-      "schema-migrate" => SchemaMigrate,
-      "stale" => Stale,
-      "uid" => Uid,
-      "where" => Where,
+      "accept" => Verb::Accept,
+      "build" => Verb::Build,
+      "delete" => Verb::Delete,
+      "deps" => Verb::Deps,
+      "doctor" => Verb::Doctor,
+      "get" => Verb::Get,
+      "hook" => Group::Hook,
+      "init" => Verb::Init,
+      "intro" => Verb::Intro,
+      "key" => Group::Key,
+      "list" => Verb::List,
+      "published" => Verb::Published,
+      "put" => Verb::Put,
+      "rdeps" => Verb::Rdeps,
+      "refresh" => Verb::Refresh,
+      "schema" => Group::Schema,
+      "stale" => Verb::Stale,
+      "where" => Verb::Where,
     }.freeze
 
-    # Flat aliases kept for backward-compat through 0.5; emit deprecation warnings.
-    DEPRECATED_ALIASES = %w[
-      mv uid migrate-keys schema-init schema-diff schema-migrate extensions action
-    ].freeze
-
     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
@@ -64,7 +50,7 @@ module Textus
                                   0
       else
         klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
-        dispatch(klass, argv, deprecated_alias: DEPRECATED_ALIASES.include?(verb))
+        dispatch(klass, argv)
       end
     rescue Textus::Error => e
       emit_error(e)
@@ -76,9 +62,8 @@ module Textus
       @store ||= Store.discover(@cwd, root: @root_arg)
     end
 
-    def dispatch(klass, argv, deprecated_alias: false)
+    def dispatch(klass, argv)
       v = klass.new(stdin: @stdin, stdout: @stdout, stderr: @stderr, cwd: @cwd)
-      v.deprecated_alias = true if deprecated_alias && v.respond_to?(:deprecated_alias=)
       v.parse(argv)
       v.call(klass.needs_store? ? store : nil)
     end
@@ -92,24 +77,20 @@ module Textus
 
     def print_help
       @stdout.puts <<~HELP
-        textus #{VERSION} — reference implementation of #{PROTOCOL} (was textus/1)
+        textus #{VERSION} — reference implementation of #{PROTOCOL}
 
         Usage (json output is the default; --format=json accepted for back-compat):
           textus list [--prefix=KEY] [--zone=Z]
           textus where KEY
           textus get KEY
-          textus put KEY --stdin [--action=NAME] --as=ROLE
+          textus put KEY --stdin [--fetch=NAME] --as=ROLE
           textus stale [--prefix=KEY] [--zone=Z]
           textus doctor
           textus intro
-          textus migrate v2
 
           textus key {mv,uid,migrate}
           textus schema {show,init,diff,migrate}
-          textus extension {list,run}
-
-        Deprecated (removed in 0.6): mv, uid, migrate-keys, schema-init,
-        schema-diff, schema-migrate, extensions, action.
+          textus hook {list,run}
       HELP
     end
   end

data/lib/textus/doctor/check/audit_log.rb

@@ -0,0 +1,50 @@
+require "json"
+
+module Textus
+  module Doctor
+    class Check
+      class AuditLog < Check
+        def call
+          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?
+
+            if stripped.start_with?("{")
+              begin
+                JSON.parse(stripped)
+              rescue JSON::ParserError => e
+                out << {
+                  "code" => "audit.parse_error",
+                  "level" => "warning",
+                  "subject" => "#{path}:#{lineno}",
+                  "message" => "audit log line #{lineno} is invalid JSON: #{e.message}",
+                  "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
+                }
+              end
+            else
+              # Legacy TSV (pre-0.5): read-only support retained for on-disk logs
+              # written by older textus versions. Never written by current code.
+              # Minimum 6 fields.
+              fields = stripped.split("\t")
+              next 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 for legacy TSV; consider migrating to NDJSON)",
+                "fix" => "inspect #{path} at line #{lineno} and remove the corrupted row",
+              }
+            end
+          end
+          out
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/hooks.rb

@@ -0,0 +1,29 @@
+module Textus
+  module Doctor
+    class Check
+      class Hooks < Check
+        def call
+          out = []
+          dir = File.join(store.root, "hooks")
+          return out unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, "*.rb")).sort.each do |f| # rubocop:disable Lint/RedundantDirGlobSort
+            registry = Textus::Hooks::Registry.new
+            Textus.with_registry(registry) do
+              load(f)
+            end
+          rescue StandardError, ScriptError => e
+            out << {
+              "code" => "hook.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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/illegal_keys.rb

@@ -0,0 +1,49 @@
+module Textus
+  module Doctor
+    class Check
+      class IllegalKeys < Check
+        def call
+          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?(Key::Grammar::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 key migrate --dry-run' then '--write' to rename to '#{proposed}'",
+              }
+            end
+          end
+          out
+        end
+
+        private
+
+        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
+  end
+end

data/lib/textus/doctor/check/manifest_files.rb

@@ -0,0 +1,38 @@
+module Textus
+  module Doctor
+    class Check
+      class ManifestFiles < Check
+        def call
+          out = []
+          store.manifest.entries.each do |entry|
+            next if entry.nested
+
+            path = leaf_path_for(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
+
+        private
+
+        def leaf_path_for(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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/schema_violations.rb

@@ -0,0 +1,22 @@
+module Textus
+  module Doctor
+    class Check
+      class SchemaViolations < Check
+        def call
+          res = store.validate_all
+          res["violations"].map do |v|
+            fix = v["expected"] &&
+                  "field '#{v["field"]}' should be written by '#{v["expected"]}' (last writer: #{v["last_writer"]})"
+            {
+              "code" => v["code"],
+              "level" => "error",
+              "subject" => v["key"],
+              "message" => v["message"] || "#{v["code"]} on #{v["key"]}",
+              "fix" => fix,
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/schemas.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Doctor
+    class Check
+      class Schemas < Check
+        def call
+          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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/sentinels.rb

@@ -0,0 +1,57 @@
+require "digest"
+require "json"
+
+module Textus
+  module Doctor
+    class Check
+      class Sentinels < Check
+        def call
+          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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/templates.rb

@@ -0,0 +1,26 @@
+module Textus
+  module Doctor
+    class Check
+      class Templates < Check
+        def call
+          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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check/unowned_schema_fields.rb

@@ -0,0 +1,34 @@
+module Textus
+  module Doctor
+    class Check
+      class UnownedSchemaFields < Check
+        def call
+          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
+      end
+    end
+  end
+end

data/lib/textus/doctor/check.rb

@@ -0,0 +1,30 @@
+module Textus
+  module Doctor
+    # Abstract base for a single doctor check. Each concrete check inspects
+    # one slice of store health and returns an array of issue hashes:
+    #   { "code" => String, "level" => "error"|"warning"|"info",
+    #     "subject" => String, "message" => String, "fix" => String (optional) }
+    class Check
+      # Snake-case name used in --checks flag and ALL_CHECKS list. Default
+      # derives from the class name; override if the SPEC name diverges.
+      def self.name_key
+        @name_key ||= name.split("::").last
+                          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                          .downcase
+      end
+
+      def initialize(store)
+        @store = store
+      end
+
+      def call
+        raise NotImplementedError.new("#{self.class.name}#call not implemented")
+      end
+
+      protected
+
+      attr_reader :store
+    end
+  end
+end