textus 0.4.0 → 0.5.0

data/lib/textus/cli.rb

@@ -1,12 +1,45 @@
 require "json"
 require "optparse"
-require "time"
-require "timeout"
-require "yaml"
 
 module Textus
-  # rubocop:disable Metrics/ClassLength
   class CLI
+    # 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,
+    }.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
@@ -19,44 +52,19 @@ module Textus
       @root_arg = nil
     end
 
-    def run(argv) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/AbcSize
-      OptionParser.new do |o|
-        o.on("--root=PATH") { |v| @root_arg = v }
-      end.order!(argv)
+    def run(argv)
+      OptionParser.new { |o| o.on("--root=PATH") { |v| @root_arg = v } }.order!(argv)
       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 "action"         then verb_action(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}")
+      else
+        klass = VERBS[verb] or raise UsageError.new("unknown verb: #{verb}")
+        dispatch(klass, argv, deprecated_alias: DEPRECATED_ALIASES.include?(verb))
       end
     rescue Textus::Error => e
       emit_error(e)
@@ -68,348 +76,11 @@ module Textus
       @store ||= Store.discover(@cwd, root: @root_arg)
     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
-      action_name = nil
-      OptionParser.new do |o|
-        o.on("--stdin") { use_stdin = true }
-        o.on("--as=ROLE") { |v| as_flag = v }
-        o.on("--action=NAME") { |v| action_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 action_name
-          callable = store.registry.action(action_name)
-          result =
-            begin
-              Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
-                callable.call(config: { "bytes" => raw }, store: Textus::StoreView.new(store), args: {})
-              end
-            rescue Timeout::Error
-              raise UsageError.new(
-                "action '#{action_name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
-              )
-            end
-          basename = key.split(".").last
-          {
-            "frontmatter" => {
-              "name" => basename,
-              "last_refreshed_at" => Time.now.utc.iso8601,
-              "actioned_with" => action_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_action(argv)
-      name = argv.shift
-      raise UsageError.new("action requires a name") if name.nil?
-
-      as_flag = nil
-      args = {}
-      argv.each do |tok|
-        case tok
-        when /\A--as=(.+)\z/         then as_flag = ::Regexp.last_match(1)
-        when /\A--format=/           then next
-        when /\A--([\w-]+)=(.*)\z/   then args[::Regexp.last_match(1)] = ::Regexp.last_match(2)
-        else
-          raise UsageError.new("unknown arg to 'action #{name}': #{tok}")
-        end
-      end
-
-      role = Role.resolve(flag: as_flag, env: ENV, root: store.root)
-      callable = store.registry.action(name)
-      view = StoreView.new(store, writable: true, as: role)
-
-      begin
-        Timeout.timeout(Textus::Refresh::ACTION_TIMEOUT_SECONDS) do
-          callable.call(config: {}, store: view, args: args)
-        end
-      rescue Timeout::Error
-        raise UsageError.new(
-          "action '#{name}' exceeded #{Textus::Refresh::ACTION_TIMEOUT_SECONDS}s timeout",
-        )
-      rescue Textus::Error
-        raise
-      rescue StandardError => e
-        raise UsageError.new("action '#{name}' raised: #{e.class}: #{e.message}")
-      end
-
-      emit({ "protocol" => Textus::PROTOCOL, "action" => name, "ok" => true })
-    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.action_names.map { |n| { "kind" => "action", "name" => n.to_s } }
-      rows += store.registry.doctor_check_names.map { |n| { "kind" => "doctor_check", "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
+    def dispatch(klass, argv, deprecated_alias: false)
+      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
 
     def emit_error(err)
@@ -421,18 +92,25 @@ module Textus
 
     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 [--action=NAME] --format=json
-          textus schema KEY --format=json
-          textus stale [--prefix=KEY] --format=json
-          textus action NAME [--key=val ...] [--as=ROLE] --format=json
+        textus #{VERSION} — reference implementation of #{PROTOCOL} (was textus/1)
+
+        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 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.
       HELP
     end
   end
-  # rubocop:enable Metrics/ClassLength
 end

data/lib/textus/doctor.rb

@@ -6,23 +6,27 @@ 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 # rubocop:disable Metrics/ModuleLength -- 8 built-in checks + extension dispatch
+  module Doctor # rubocop:disable Metrics/ModuleLength -- 9 built-in checks + extension dispatch
     LEVELS = %w[error warning info].freeze
     DOCTOR_CHECK_TIMEOUT_SECONDS = 2
+    ALL_CHECKS = %w[
+      manifest_files schemas templates extensions illegal_keys
+      sentinels audit_log unowned_schema_fields schema_violations
+    ].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))
-      issues.concat(run_registered_checks(store))
+    def run(store, checks: nil)
+      selected = checks ? Array(checks).map(&:to_s) : ALL_CHECKS
+      unknown = selected - ALL_CHECKS
+      unless unknown.empty?
+        raise UsageError.new(
+          "unknown doctor check: #{unknown.first}. Valid checks: #{ALL_CHECKS.join(", ")}",
+        )
+      end
+
+      issues = run_builtin_checks(store, selected)
+      issues.concat(run_registered_checks(store)) # extensions always run
 
       summary = LEVELS.to_h { |l| [l, issues.count { |i| i["level"] == l }] }
       {
@@ -33,6 +37,20 @@ module Textus
       }
     end
 
+    def run_builtin_checks(store, selected)
+      issues = []
+      issues.concat(check_manifest_files(store))        if selected.include?("manifest_files")
+      issues.concat(check_schemas(store))               if selected.include?("schemas")
+      issues.concat(check_templates(store))             if selected.include?("templates")
+      issues.concat(check_extensions(store))            if selected.include?("extensions")
+      issues.concat(check_illegal_keys(store))          if selected.include?("illegal_keys")
+      issues.concat(check_sentinels(store))             if selected.include?("sentinels")
+      issues.concat(check_audit_log(store))             if selected.include?("audit_log")
+      issues.concat(check_unowned_schema_fields(store)) if selected.include?("unowned_schema_fields")
+      issues.concat(check_schema_violations(store))     if selected.include?("schema_violations")
+      issues
+    end
+
     # --- Checks -----------------------------------------------------------
 
     def check_manifest_files(store)
@@ -199,32 +217,30 @@ module Textus
         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?
+        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: minimum 6 fields. Removed in 0.6.
+          fields = stripped.split("\t")
+          next if fields.length >= 6
 
-        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",
+            "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
@@ -258,6 +274,21 @@ module Textus
       out
     end
 
+    def check_schema_violations(store)
+      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
+
     def run_registered_checks(store)
       out = []
       view = StoreView.new(store)

data/lib/textus/entry/json.rb

@@ -17,13 +17,15 @@ module Textus
 
         meta = parsed["_meta"]
         fm = meta.is_a?(Hash) ? meta : {}
-        { "frontmatter" => fm, "body" => raw, "content" => parsed }
+        content_without_meta = parsed.except("_meta")
+        { "_meta" => fm, "body" => raw, "content" => content_without_meta }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
-        _ = frontmatter
+      def self.serialize(meta:, body:, content: nil)
         if content.is_a?(Hash)
-          out = ::JSON.pretty_generate(content)
+          # Re-inject _meta as the first key so on-disk shape is stable.
+          on_disk = meta && !meta.empty? ? { "_meta" => meta }.merge(content) : content
+          out = ::JSON.pretty_generate(on_disk)
           out += "\n" unless out.end_with?("\n")
           out
         elsif body && !body.to_s.empty?

data/lib/textus/entry/markdown.rb

@@ -7,7 +7,7 @@ module Textus
       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")
+        return { "_meta" => {}, "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("---")
@@ -22,12 +22,12 @@ module Textus
           raise BadFrontmatter.new(path, "YAML parse failed: #{e.message}")
         end
         fm = {} unless fm.is_a?(Hash)
-        { "frontmatter" => fm, "body" => body, "content" => nil }
+        { "_meta" => fm, "body" => body, "content" => nil }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
+      def self.serialize(meta:, body:, content: nil)
         _ = content # markdown ignores content
-        fm_yaml = frontmatter.empty? ? "" : ::YAML.dump(frontmatter).sub(/\A---\n/, "")
+        fm_yaml = meta.empty? ? "" : ::YAML.dump(meta).sub(/\A---\n/, "")
         body = body.to_s
         body += "\n" unless body.empty? || body.end_with?("\n")
         "---\n#{fm_yaml}---\n#{body}"

data/lib/textus/entry/text.rb

@@ -6,11 +6,11 @@ module Textus
         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 }
+        { "_meta" => {}, "body" => raw, "content" => nil }
       end
 
-      def self.serialize(frontmatter:, body:, content: nil)
-        _ = frontmatter
+      def self.serialize(meta:, body:, content: nil)
+        _ = meta
         _ = content
         b = body.to_s
         b += "\n" unless b.empty? || b.end_with?("\n")