tina4ruby 3.13.64 → 3.13.67

data/lib/tina4/cli.rb

@@ -5,7 +5,75 @@ require "fileutils"
 
 module Tina4
   class CLI
-    COMMANDS = %w[init start migrate migrate:status migrate:rollback seed seed:create test version routes console generate ai metrics help].freeze
+    # ── Command registries — the single source of truth ─────────────────
+    #
+    # ONE entry per command/generator drives dispatch (#run / #cmd_generate),
+    # the human help (#cmd_help), AND the machine-readable manifest
+    # (`commands --json`). Add a command in ONE place and it appears in
+    # dispatch, help, and discovery — there is no second list to sync. Ruby
+    # mirror of the Python master's COMMANDS / GENERATORS registries
+    # (tina4_python/cli/__init__.py).
+    #
+    #   GENERATORS[name] = { handler: :method_symbol, usage: str, summary: str }
+    #   COMMANDS[name]   = { handler: :method_symbol, summary: str,
+    #                        usage?: str,          # arg/flag hint for #cmd_help (human only)
+    #                        args?: [str],         # positional args for the manifest ("x?" = optional)
+    #                        subcommands?: [str] } # sub-names for the manifest (generate)
+    #
+    # Handlers are instance-method symbols dispatched via #send: GENERATORS
+    # handlers take (name, flags); COMMANDS handlers take (argv).
+
+    GENERATORS = {
+      "model"      => { handler: :generate_model,      usage: '<Name> [--fields "name:string,price:float"]', summary: "ORM model + matching migration" },
+      "route"      => { handler: :generate_route,      usage: "<name> [--model Name] [--public]",             summary: "CRUD route file, secure by default (--public opens writes)" },
+      "crud"       => { handler: :generate_crud,       usage: '<Name> [--fields "..."] [--public]',           summary: "Model + migration + routes + form + view + test" },
+      "migration"  => { handler: :generate_migration,  usage: "<description>",                                 summary: "Timestamped migration file (UP/DOWN)" },
+      "middleware" => { handler: :generate_middleware, usage: "<Name>",                                        summary: "Middleware with before/after hooks" },
+      "test"       => { handler: :generate_test,       usage: "<name> [--model Name]",                         summary: "RSpec test file" },
+      "form"       => { handler: :generate_form,       usage: '<Name> [--fields "..."]',                       summary: "Form template with inputs matching model fields" },
+      "view"       => { handler: :generate_view,       usage: '<Name> [--fields "..."]',                       summary: "List + detail view templates" },
+      "auth"       => { handler: :generate_auth,       usage: "",                                              summary: "Login/register routes + User model + templates" },
+      "service"    => { handler: :generate_service,    usage: '<Name> [--every 5m | --cron "..."]',            summary: "Scheduled ServiceRunner task (src/services/)" },
+      "queue"      => { handler: :generate_queue,      usage: "<topic>",                                       summary: "Producer + consumer worker (src/services/)" },
+      "validator"  => { handler: :generate_validator,  usage: "<Name>",                                        summary: "Request-body Validator (src/validators/)" },
+      "seeder"     => { handler: :generate_seeder,     usage: "<Model>",                                       summary: "FakeData + seed_orm seeder (seeds/)" },
+      "websocket"  => { handler: :generate_websocket,  usage: "<path>",                                        summary: "Tina4.websocket handler (src/routes/)" },
+      "listener"   => { handler: :generate_listener,   usage: "<event>",                                       summary: "Tina4::Events.on listener (src/listeners/)" },
+    }.freeze
+
+    # Sub-dispatch table for the top-level `queue` command — the SINGLE source
+    # for its subcommands (drives #cmd_queue dispatch AND the manifest's
+    # queue.subcommands). Ruby mirror of the Python master's _QUEUE_SUBCOMMANDS.
+    # Distinct from the `queue` GENERATOR, which SCAFFOLDS a consumer file.
+    QUEUE_SUBCOMMANDS = {
+      "work"  => :queue_work,
+      "stats" => :queue_stats,
+      "retry" => :queue_retry,
+      "clear" => :queue_clear,
+    }.freeze
+
+    COMMANDS = {
+      "init"             => { handler: :cmd_init,             usage: "[NAME]", args: ["name?"],           summary: "Initialize a new Tina4 project" },
+      "start"            => { handler: :cmd_start,            usage: "[options]",                          summary: "Start the Tina4 web server" },
+      "serve"            => { handler: :cmd_start,                                                         summary: "Alias for start" },
+      "migrate"          => { handler: :cmd_migrate,          usage: "[--create NAME] [--rollback N]",     summary: "Run database migrations" },
+      "migrate:create"   => { handler: :cmd_migrate_create,   usage: "<desc>", args: ["description"],      summary: "Create a new migration file" },
+      "migrate:status"   => { handler: :cmd_migrate_status,                                                summary: "Show migration status (completed and pending)" },
+      "migrate:rollback" => { handler: :cmd_migrate_rollback, usage: "[-n N]",                             summary: "Rollback the last batch of migrations" },
+      "seed"             => { handler: :cmd_seed,             usage: "[--clear]",                          summary: "Run all seed files in seeds/" },
+      "seed:create"      => { handler: :cmd_seed_create,      usage: "NAME", args: ["name"],               summary: "Create a new seed file" },
+      "test"             => { handler: :cmd_test,                                                          summary: "Run inline tests" },
+      "queue"            => { handler: :cmd_queue,            usage: "<work|stats|retry|clear> [topic]", subcommands: QUEUE_SUBCOMMANDS.keys, summary: "Run queue workers and manage jobs" },
+      "build"            => { handler: :cmd_build,            usage: "[--tag NAME] [--file PATH]",         summary: "Build the deployable Docker image" },
+      "version"          => { handler: :cmd_version,                                                       summary: "Show Tina4 version" },
+      "routes"           => { handler: :cmd_routes,                                                        summary: "List all registered routes" },
+      "console"          => { handler: :cmd_console,                                                       summary: "Start an interactive console" },
+      "generate"         => { handler: :cmd_generate,         usage: "<what> <name> [options]", subcommands: GENERATORS.keys, summary: "Generate scaffolding (see Generators below)" },
+      "ai"               => { handler: :cmd_ai,               usage: "[--all]",                            summary: "Detect AI tools and install context files" },
+      "metrics"          => { handler: :cmd_metrics,          usage: "[--top N] [--json] [--fail-on warn|error] [--path DIR]", summary: "Rank top code-quality offenders" },
+      "commands"         => { handler: :cmd_commands,         usage: "[--json]",                           summary: "List available commands (add --json for machine form)" },
+      "help"             => { handler: :cmd_help,                                                          summary: "Show this help message" },
+    }.freeze
 
     # ── Field type mapping ──────────────────────────────────────────────
     FIELD_TYPE_MAP = {
@@ -29,22 +97,14 @@ module Tina4
 
     def run(argv)
       command = argv.shift || "help"
-      case command
-      when "init"       then cmd_init(argv)
-      when "start", "serve" then cmd_start(argv)
-      when "migrate"    then cmd_migrate(argv)
-      when "migrate:status" then cmd_migrate_status(argv)
-      when "migrate:rollback" then cmd_migrate_rollback(argv)
-      when "seed"       then cmd_seed(argv)
-      when "seed:create" then cmd_seed_create(argv)
-      when "test"       then cmd_test(argv)
-      when "version"    then cmd_version
-      when "routes"     then cmd_routes
-      when "console"    then cmd_console
-      when "generate"   then cmd_generate(argv)
-      when "ai"         then cmd_ai(argv)
-      when "metrics"    then cmd_metrics(argv)
-      when "help", "-h", "--help" then cmd_help
+      command = "help" if %w[-h --help].include?(command)
+
+      # Dispatch from the single-source-of-truth COMMANDS registry. The same
+      # registry drives #cmd_help and the `commands --json` manifest, so
+      # dispatch, help, and discovery never drift.
+      spec = COMMANDS[command]
+      if spec
+        send(spec[:handler], argv)
       else
         puts "Unknown command: #{command}"
         cmd_help
@@ -148,7 +208,7 @@ module Tina4
     # Parse --key value and --flag from args. Returns [flags_hash, positional_array]
     def parse_flags(args)
       # Boolean-only flags that never take a value argument
-      boolean_flags = %w[no-browser no-reload production managed all clear dev json public no-migration]
+      boolean_flags = %w[no-browser no-reload production managed all clear dev json public no-migration once]
 
       flags = {}
       positional = []
@@ -361,6 +421,26 @@ module Tina4
       end
     end
 
+    # ── migrate:create ───────────────────────────────────────────────────
+
+    # Create a new timestamped migration file (UP .sql + .down.sql), matching
+    # the Python master `migrate:create`. CHEAP + database-free: it only writes
+    # files via the static Tina4::Migration.create_migration helper — no app
+    # boot, no DB connection, no tracking table. `description` is every arg
+    # joined with a space (parity with Python's `" ".join(args)`).
+    def cmd_migrate_create(argv)
+      description = (argv || []).join(" ").strip
+      if description.empty?
+        puts "Usage: tina4ruby migrate:create <description>"
+        exit 1
+      end
+
+      require_relative "log"
+      require_relative "migration"
+      path = Tina4::Migration.create_migration(description, migrations_dir: "migrations")
+      puts "Created: #{path}"
+    end
+
     # ── migrate:status ─────────────────────────────────────────────────────
 
     def cmd_migrate_status(_argv)
@@ -502,16 +582,304 @@ module Tina4
       exit(1) if results[:failed] > 0 || results[:errors] > 0
     end
 
+    # ── queue ─────────────────────────────────────────────────────────────
+    #
+    # Top-level `queue` command — wires straight to the real Tina4::Queue (lite
+    # /file backend by default; RabbitMQ/Kafka/MongoDB via TINA4_QUEUE_BACKEND).
+    # `stats`, `retry` and `clear` operate on the queue without starting a
+    # server; `work` runs the app's consumer for a topic. Distinct from
+    # `generate queue`, which SCAFFOLDS a consumer file. Mirrors the Python
+    # master's `queue` command.
+    #
+    #   tina4ruby queue work  [topic] [--once] [--poll N] [--services DIR]
+    #   tina4ruby queue stats [topic] [--json]
+    #   tina4ruby queue retry [topic]
+    #   tina4ruby queue clear [status] [topic]
+    def cmd_queue(argv)
+      argv ||= []
+      if argv.empty?
+        puts "Usage: tina4ruby queue <work|stats|retry|clear> [options]"
+        puts "  Subcommands: #{QUEUE_SUBCOMMANDS.keys.join(', ')}"
+        exit 1
+      end
+
+      sub = argv[0].downcase
+      handler = QUEUE_SUBCOMMANDS[sub]
+      if handler.nil?
+        puts "Unknown queue subcommand: #{sub}"
+        puts "  Available: #{QUEUE_SUBCOMMANDS.keys.join(', ')}"
+        exit 1
+      end
+      send(handler, argv[1..])
+    end
+
+    # Load the framework classes (Queue, backends, ServiceRunner) WITHOUT
+    # booting the app (no route discovery, no server, no auto-migrate), then
+    # load .env — mirrors the Python master's _load_env() before queue ops.
+    def load_queue_runtime
+      require_relative "../tina4"
+      Tina4::Env.load_env(Dir.pwd)
+    end
+
+    # Resolve the per-job handler a consumer declares for `topic`.
+    #
+    # A consumer scaffolded by `generate queue <topic>` registers a daemon
+    # service via Tina4.service(..., topic:, handle:). When its `topic` matches,
+    # `queue work` drives that per-job `handle` callable so THIS command owns the
+    # poll loop (honouring --poll / the bounded --once drain) instead of the
+    # consumer's own endless loop. Returns the callable, or nil when no consumer
+    # in `services_dir` targets this topic. Ruby parity for the Python master's
+    # _resolve_queue_handler (which reads a module-level `service` dict).
+    def resolve_queue_handler(services_dir, topic)
+      dir = File.expand_path(services_dir, Dir.pwd)
+      return nil unless Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "*.rb")).sort.each do |file|
+        next if File.basename(file).start_with?("_")
+        begin
+          load file
+        rescue StandardError, ScriptError
+          next # a broken sibling must not sink the worker
+        end
+      end
+
+      Tina4::ServiceRunner.list.each do |svc|
+        options = svc[:options] || {}
+        handle = options[:handle]
+        return handle if options[:topic].to_s == topic.to_s && handle.respond_to?(:call)
+      end
+      nil
+    end
+
+    # Run a consumer loop that pops and processes jobs on a topic.
+    #
+    #   tina4ruby queue work [topic] [--once] [--poll N] [--services DIR]
+    #
+    # Long-running by default (polls every --poll seconds, 1.0 default; Ctrl-C to
+    # stop). --once does a single-pass drain — it processes every currently
+    # available job then exits (poll interval 0). The per-job handler is resolved
+    # from the app's consumer for this topic (see #resolve_queue_handler); with no
+    # handler it drains and acks with a warning rather than inventing behaviour.
+    def queue_work(argv)
+      load_queue_runtime
+      flags, positional = parse_flags(argv)
+      topic = positional[0] || "default"
+      once = flags["once"] ? true : false
+
+      poll =
+        if once
+          0.0 # single-pass: consume() returns as soon as the topic is empty
+        else
+          poll_raw = flags["poll"].to_s.strip
+          if poll_raw.empty? || poll_raw == "true"
+            1.0
+          else
+            begin
+              Float(poll_raw)
+            rescue ArgumentError
+              1.0
+            end
+          end
+        end
+
+      services_dir = flags["services"]
+      services_dir = ENV["TINA4_SERVICE_DIR"] || "src/services" unless services_dir.is_a?(String)
+
+      handler = resolve_queue_handler(services_dir, topic)
+      queue = Tina4::Queue.new(topic: topic)
+
+      if handler.nil?
+        puts "  ⚠ No consumer handler found for topic '#{topic}' in #{services_dir}."
+        puts "    Scaffold one with: tina4ruby generate queue #{topic}"
+        puts "    Draining (consume + ack) without processing."
+      end
+
+      mode = once ? "single-pass drain" : format("polling every %gs (Ctrl-C to stop)", poll)
+      puts "  Queue worker on '#{topic}' — #{mode}..."
+
+      processed = 0
+      failed = 0
+      begin
+        queue.consume(topic, poll_interval: poll) do |job|
+          begin
+            handler.call(job.payload) unless handler.nil?
+            job.complete
+            processed += 1
+          rescue StandardError, NotImplementedError => e
+            # A bad job nacks (retry / dead-letter), the worker lives on —
+            # parity with the Python master's `except Exception`. NotImplemented-
+            # Error is a ScriptError (not a StandardError) in Ruby, so name it
+            # explicitly: an UNFILLED `generate queue` scaffold stub raises it and
+            # must nack the job, not crash the worker. Interrupt (Ctrl-C) is
+            # neither, so it still propagates to the outer stop handler.
+            job.fail(e.message)
+            failed += 1
+          end
+        end
+      rescue Interrupt
+        puts "\n  Interrupted — stopping worker."
+      end
+
+      puts "  Processed #{processed} job(s), #{failed} failed on '#{topic}'."
+    end
+
+    # Print pending / in-flight / failed / dead-letter / completed counts.
+    #
+    #   tina4ruby queue stats [topic] [--json]
+    def queue_stats(argv)
+      require "json"
+      load_queue_runtime
+      flags, positional = parse_flags(argv)
+      topic = positional[0] || "default"
+
+      queue = Tina4::Queue.new(topic: topic)
+      stats = {
+        "topic"     => topic,
+        "pending"   => queue.size(status: "pending"),      # waiting to run
+        "reserved"  => queue.size(status: "reserved"),     # popped, not yet acked
+        "failed"    => queue.failed.length,                # failed once, still retrying
+        "dead"      => queue.size(status: "dead"),         # exhausted retries (dead-letter)
+        "completed" => queue.size(status: "completed"),    # terminal-completed (0 on file backend)
+      }
+
+      if flags.key?("json")
+        puts JSON.pretty_generate(stats)
+        return
+      end
+
+      puts
+      puts "  Queue '#{topic}'"
+      puts "    pending    #{stats['pending']}"
+      puts "    reserved   #{stats['reserved']}    (in-flight)"
+      puts "    failed     #{stats['failed']}    (retrying)"
+      puts "    dead       #{stats['dead']}    (dead-letter)"
+      puts "    completed  #{stats['completed']}"
+      puts
+    end
+
+    # Re-queue failed and dead-letter jobs so they run again.
+    #
+    #   tina4ruby queue retry [topic]
+    #
+    # Revives every dead-letter job (manual override, regardless of attempt
+    # count) and re-queues any failed-but-still-eligible jobs.
+    def queue_retry(argv)
+      load_queue_runtime
+      _flags, positional = parse_flags(argv)
+      topic = positional[0] || "default"
+
+      queue = Tina4::Queue.new(topic: topic)
+
+      # max_retries: 0 => every job in the dead-letter store, whatever its
+      # attempt count (matches what stats/size("dead") reports).
+      dead = queue.dead_letters(max_retries: 0)
+      revived = dead.count { |job| queue.retry(queue_job_id(job)) }
+      # Any failed-but-retryable jobs still under the limit.
+      requeued = queue.retry_failed
+
+      total = revived + requeued
+      puts "  Re-queued #{total} job(s) on '#{topic}' (#{revived} dead-letter, #{requeued} failed)."
+    end
+
+    # Purge jobs of a given status (default: completed).
+    #
+    #   tina4ruby queue clear [status] [topic]
+    #
+    # status is one of pending / reserved / completed / failed / dead. The
+    # default 'completed' clears finished jobs; pass e.g. `queue clear pending`
+    # or `queue clear dead orders` to purge another status / topic.
+    def queue_clear(argv)
+      load_queue_runtime
+      _flags, positional = parse_flags(argv)
+      status = positional[0] || "completed"
+      topic = positional[1] || "default"
+
+      queue = Tina4::Queue.new(topic: topic)
+      removed = queue.purge(status)
+      puts "  Cleared #{removed} '#{status}' job(s) from '#{topic}'."
+    end
+
+    # Extract a job id from either a raw backend Hash or a Job object, so
+    # `queue retry` works regardless of what a backend's dead_letters returns.
+    def queue_job_id(job)
+      return job.id if job.respond_to?(:id)
+      job["id"] || job[:id]
+    end
+
+    # ── build ─────────────────────────────────────────────────────────────
+    #
+    # Build the deployable Docker image for this Tina4 app. A Tina4 app deploys
+    # as a container (`tina4ruby init` scaffolds a Dockerfile), so `build`
+    # produces THAT artifact — it shells out to the `docker` CLI (no new gem)
+    # and fails loud with guidance when there is no Dockerfile or docker is not
+    # on PATH. Mirrors the Python master's `build`.
+    #
+    #   tina4ruby build                    # docker build -t <dir>:latest .
+    #   tina4ruby build --tag myapp:1.2     # explicit image tag
+    #   tina4ruby build --file docker/Dockerfile
+    def cmd_build(argv)
+      flags, _positional = parse_flags(argv)
+
+      tag = flags["tag"]
+      unless tag.is_a?(String) && !tag.empty?
+        # Default tag: <project-folder>:latest, lower-cased (docker repo names
+        # must be lowercase). Fall back to a sane name for an unnamed cwd.
+        base = File.basename(Dir.pwd).downcase
+        base = "tina4app" if base.empty?
+        tag = "#{base}:latest"
+      end
+
+      dockerfile = flags["file"].is_a?(String) ? flags["file"] : "Dockerfile"
+      unless File.file?(dockerfile)
+        puts "  ✗ No #{dockerfile} found."
+        puts "  A Tina4 app deploys as a container. Scaffold a Dockerfile first:"
+        puts "      tina4 deploy docker        (or: tina4ruby init)"
+        exit 1
+      end
+
+      docker = which_executable("docker")
+      if docker.nil?
+        puts "  ✗ docker was not found on PATH."
+        puts "  Install Docker to build the deployable image, or build manually:"
+        puts "      docker build -t #{tag} -f #{dockerfile} ."
+        exit 1
+      end
+
+      puts "  Building image #{tag} from #{dockerfile} ..."
+      ok = system(docker, "build", "-t", tag, "-f", dockerfile, ".")
+      unless ok
+        code = ($?&.exitstatus) || 1
+        puts "  ✗ docker build failed (exit #{code})"
+        exit code
+      end
+      puts "  ✓ Built image #{tag}"
+      puts "  Run: docker run -p 7147:7147 #{tag}"
+    end
+
+    # Locate an executable on PATH — the stdlib-only equivalent of Python's
+    # shutil.which (no new gem). Honours PATHEXT on Windows.
+    def which_executable(cmd)
+      exts = ENV["PATHEXT"] ? ENV["PATHEXT"].split(File::PATH_SEPARATOR) : [""]
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        next if dir.empty?
+        exts.each do |ext|
+          candidate = File.join(dir, "#{cmd}#{ext}")
+          return candidate if File.executable?(candidate) && !File.directory?(candidate)
+        end
+      end
+      nil
+    end
+
     # ── version ───────────────────────────────────────────────────────────
 
-    def cmd_version
+    def cmd_version(_argv = nil)
       require_relative "version"
       puts "Tina4 Ruby v#{Tina4::VERSION}"
     end
 
     # ── routes ────────────────────────────────────────────────────────────
 
-    def cmd_routes
+    def cmd_routes(_argv = nil)
       require_relative "../tina4"
       Tina4.initialize!(Dir.pwd)
       load_routes(Dir.pwd)
@@ -528,7 +896,7 @@ module Tina4
 
     # ── console ───────────────────────────────────────────────────────────
 
-    def cmd_console
+    def cmd_console(_argv = nil)
       require_relative "../tina4"
       Tina4.initialize!(Dir.pwd)
       load_routes(Dir.pwd)
@@ -655,15 +1023,13 @@ module Tina4
 
     # ── generate ────────────────────────────────────────────────────────
 
-    ALL_GENERATORS = "model, route, crud, migration, middleware, test, form, view, auth, " \
-                     "service, queue, validator, seeder, websocket, listener"
-
     def cmd_generate(argv)
       what = argv.shift
+      all = GENERATORS.keys.join(", ")  # single source: the GENERATORS registry
 
       unless what
         puts "Usage: tina4ruby generate <what> <name> [options]"
-        puts "  Generators: #{ALL_GENERATORS}"
+        puts "  Generators: #{all}"
         puts '  Options:    --fields "name:string,price:float"  --model ModelName'
         puts '              --public                  open a route'"'"'s writes (default: secure)'
         puts '              --every 5m | --cron "..."  service schedule'
@@ -682,32 +1048,21 @@ module Tina4
       name = no_name_generators.include?(what) ? "" : argv.shift
       flags, _positional = parse_flags(argv)
 
-      case what
-      when "model"      then generate_model(name, flags)
-      when "route"      then generate_route(name, flags)
-      when "crud"       then generate_crud(name, flags)
-      when "migration"  then generate_migration(name, flags)
-      when "middleware"  then generate_middleware(name, flags)
-      when "test"       then generate_test(name, flags)
-      when "form"       then generate_form(name, flags)
-      when "view"       then generate_view(name, flags)
-      when "auth"       then generate_auth(name, flags)
-      when "service"    then generate_service(name, flags)
-      when "queue"      then generate_queue(name, flags)
-      when "validator"  then generate_validator(name, flags)
-      when "seeder"     then generate_seeder(name, flags)
-      when "websocket"  then generate_websocket(name, flags)
-      when "listener"   then generate_listener(name, flags)
+      # Dispatch from the GENERATORS registry (single source of truth for the
+      # generate subcommands; also feeds #cmd_help and the manifest).
+      gen_spec = GENERATORS[what]
+      if gen_spec
+        send(gen_spec[:handler], name, flags)
       else
         puts "Unknown generator: #{what}"
-        puts "  Available: #{ALL_GENERATORS}"
+        puts "  Available: #{all}"
         exit 1
       end
     end
 
     # ── Generator: model ─────────────────────────────────────────────────
 
-    def generate_model(name, flags)
+    def generate_model(name, flags, emit_test: true)
       fields = parse_fields(flags["fields"])
       table = to_table_name(name)
       snake = to_snake_case(name)
@@ -744,10 +1099,16 @@ module Tina4
       File.write(path, content)
       puts "  Created #{path}"
 
-      # Generate matching migration (unless --no-migration)
+      # Generate matching migration (unless --no-migration). The model's own
+      # co-emitted spec proves the schema through the real ORM, so the migration
+      # sub-call does NOT also co-emit a migration spec (emit_test: false).
       unless flags["no-migration"]
-        generate_migration("create_#{table}", flags, fields_override: fields, table_override: table)
+        generate_migration("create_#{table}", flags, fields_override: fields,
+                                                      table_override: table, emit_test: false)
       end
+
+      # Co-emit a real SQLite roundtrip spec next to the model.
+      emit_model_test(name, table, fields) if emit_test
     end
 
     # ── Generator: route ─────────────────────────────────────────────────
@@ -768,7 +1129,7 @@ module Tina4
     # `Tina4::Router.get/post/...` (no bearer auth_handler attached), so `.no_auth`
     # genuinely opens the write on BOTH the live server and the TestClient — the
     # same registration path AutoCrud uses.
-    def generate_route(name, flags)
+    def generate_route(name, flags, emit_test: true)
       route_path = name.sub(%r{^/}, "")
       singular = route_path.end_with?("s") ? route_path[0..-2] : route_path
       model = flags["model"]
@@ -929,6 +1290,18 @@ module Tina4
 
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real spec. A --model route is working code → reuse the
+      # secure-gate behavioural spec (reads public, writes gated) via
+      # generate_test; a no-model route's handlers are loud stubs → the
+      # Router-registration + live-stub spec.
+      if emit_test
+        if model
+          generate_test(route_path, { "model" => model, "secure_writes" => true, "public" => public_writes })
+        else
+          emit_route_stub_test(route_path)
+        end
+      end
     end
 
     # ── Generator: crud ──────────────────────────────────────────────────
@@ -940,12 +1313,14 @@ module Tina4
 
       puts "\n  Generating CRUD for #{name}...\n"
 
-      # 1. Model + migration
-      generate_model(name, flags)
+      # 1. Model + migration (emit_test: false — crud emits its own broader gate
+      #    spec at step 5, so the sub-generators stay quiet to avoid double-emit).
+      generate_model(name, flags, emit_test: false)
 
       # 2. Routes with model — secure-by-default; thread --public through so
       #    `generate crud X --public` opens the writes (mirrors AutoCrud public:).
-      generate_route(route_name, { "model" => name, "public" => is_public })
+      #    emit_test: false — the crud gate spec at step 5 targets the same file.
+      generate_route(route_name, { "model" => name, "public" => is_public }, emit_test: false)
 
       # 3. Form
       generate_form(name, flags)
@@ -963,7 +1338,7 @@ module Tina4
 
     # ── Generator: migration ─────────────────────────────────────────────
 
-    def generate_migration(name, flags = {}, fields_override: nil, table_override: nil)
+    def generate_migration(name, flags = {}, fields_override: nil, table_override: nil, emit_test: true)
       now = Time.now
       timestamp = now.strftime("%Y%m%d%H%M%S")
       dir = "migrations"
@@ -1000,22 +1375,24 @@ module Tina4
         down_sql = "-- Write your DOWN rollback SQL here\n-- Example: ALTER TABLE #{table} DROP COLUMN new_col;"
       end
 
+      # The main .sql holds ONLY the UP migration. The runner executes the WHOLE
+      # file (comments stripped), so embedding the DOWN here would CREATE then
+      # immediately DROP the table — the migration would silently no-op. The
+      # rollback SQL lives solely in the sibling .down.sql. Matches the Python
+      # master (tina4_python/cli/__init__.py).
       content = <<~SQL
         -- Migration: #{name}
         -- Created: #{now.strftime("%Y-%m-%d %H:%M:%S")}
 
-        -- UP
         #{up_sql}
-
-        -- DOWN
-        #{down_sql}
       SQL
 
       File.write(path, content)
       puts "  Created #{path}"
 
       # Also create .down.sql for the migration runner
-      down_path = File.join(dir, "#{timestamp}_#{name}.down.sql")
+      down_filename = "#{timestamp}_#{name}.down.sql"
+      down_path = File.join(dir, down_filename)
       down_content = <<~SQL
         -- Rollback: #{name}
         -- Created: #{now.strftime("%Y-%m-%d %H:%M:%S")}
@@ -1025,6 +1402,10 @@ module Tina4
 
       File.write(down_path, down_content)
       puts "  Created #{down_path}"
+
+      # Co-emit a real apply-UP/DOWN spec — only for CREATE migrations, whose UP
+      # SQL is real DDL to assert against (a placeholder ALTER has nothing yet).
+      emit_migration_test(name, table, filename, down_filename) if emit_test && is_create
     end
 
     # ── Generator: middleware ────────────────────────────────────────────
@@ -1053,7 +1434,7 @@ module Tina4
             # Runs before the route handler.
             # Return [request, response] to continue, or
             # return [request, response.json({ error: "Unauthorized" }, 401)] to block.
-            Tina4::Log.info("#{name}: \#{request.request_method} \#{request.path}")
+            Tina4::Log.info("#{name}: \#{request.method} \#{request.path}")
             [request, response]
           end
 
@@ -1066,6 +1447,10 @@ module Tina4
 
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real dispatch spec (drives the scaffold through the real
+      # server middleware dispatch — Tina4::Middleware.run_before/run_after).
+      emit_middleware_test(name, snake)
     end
 
     # ── Generator: test ──────────────────────────────────────────────────
@@ -1075,14 +1460,6 @@ module Tina4
       snake = to_snake_case(name)
       singular = snake.end_with?("s") ? snake[0..-2] : snake
 
-      dir = "spec"
-      FileUtils.mkdir_p(dir)
-      path = File.join(dir, "#{snake}_spec.rb")
-      if File.exist?(path)
-        puts "  File already exists: #{path}"
-        return
-      end
-
       # Secure-by-default CRUD spec (emitted by `generate crud`): proves the gate
       # by BEHAVIOR through the real Tina4::TestClient — reads public, writes
       # gated — instead of assuming an anonymous create returns 201. Grounded on
@@ -1157,8 +1534,7 @@ module Tina4
             #{write_examples}
           end
         RUBY
-        File.write(path, content)
-        puts "  Created #{path}"
+        write_test(snake, content)
         return
       end
 
@@ -1221,8 +1597,7 @@ module Tina4
         RUBY
       end
 
-      File.write(path, content)
-      puts "  Created #{path}"
+      write_test(snake, content)
     end
 
     # ── Generator: form ──────────────────────────────────────────────────
@@ -1394,8 +1769,9 @@ module Tina4
     def generate_auth(_name = nil, flags = {})
       puts "\n  Generating authentication scaffolding...\n"
 
-      # 1. User model + migration
-      generate_model("User", { "fields" => "email:string,password:string,role:string" })
+      # 1. User model + migration (emit_test: false — auth emits its own broader
+      #    register/login/me spec at step 5).
+      generate_model("User", { "fields" => "email:string,password:string,role:string" }, emit_test: false)
 
       # 2. Auth routes
       dir = "src/routes"
@@ -1530,8 +1906,9 @@ module Tina4
         puts "  Created #{register_path}"
       end
 
-      # 5. Auth test
-      generate_test("auth", { "model" => "User" })
+      # 5. Auth test — real register/login/me end-to-end (real Router, real Auth
+      #    JWT + PBKDF2, real SQLite). Replaces the old placeholder stub spec.
+      emit_auth_test
 
       puts "\n  Authentication scaffolding complete."
       puts "  Run: tina4ruby migrate"
@@ -1609,6 +1986,9 @@ module Tina4
       RUBY
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real ServiceRunner registration/discovery spec.
+      emit_service_test(name, snake)
     end
 
     # ── Generator: queue ──────────────────────────────────────────────────
@@ -1665,11 +2045,17 @@ module Tina4
         end
 
         # Wiring: consumer runs as a daemon service (manages its own poll loop).
-        # Discovered by Tina4::ServiceRunner.discover("src/services").
-        Tina4.service("#{topic}-consumer", daemon: true) { |context| consume_#{slug}(context) }
+        # Discovered by Tina4::ServiceRunner.discover("src/services"). The `topic`
+        # + per-job `handle` options let `tina4ruby queue work #{topic}` drive this
+        # consumer directly (own the poll loop / bounded --once drain) without
+        # wiring a ServiceRunner.
+        Tina4.service("#{topic}-consumer", daemon: true, topic: "#{topic}", handle: method(:handle_#{slug})) { |context| consume_#{slug}(context) }
       RUBY
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real file-backed Queue spec (push a real job + daemon wiring).
+      emit_queue_test(topic, slug)
     end
 
     # ── Generator: validator ──────────────────────────────────────────────
@@ -1685,15 +2071,15 @@ module Tina4
         return
       end
 
-      body = ai_fill(
-        "validate_#{snake}",
-        "declare the validation rules for a #{name} payload",
-        'validator.required("name").email("email").min_length("name", 2).integer("age")',
-        "validator:#{snake}: add the rule set",
-        given: "validator -> Tina4::Validator.new(data) (chainable)",
-        ret: "the same validator (caller checks .is_valid? / .errors)",
-        ground: 'tina4_context("validate request body with Validator", "ruby")'
-      )
+      # Ships a working starter rule (not a loud stub): a rules-less validator
+      # validates nothing, so there would be no negative case for the co-emitted
+      # valid/invalid spec to assert against. `required("name")` mirrors the model
+      # generator's default `name` field — edit it for your real payload.
+      body = extend_marker(
+        "add / adjust the rules for your #{name} payload",
+        'e.g. validator.email("email").min_length("name", 2).integer("age") · ' \
+        'ground: tina4_context("validate request body with Validator", "ruby")'
+      ) + %(  validator.required("name")\n)
       content = <<~RUBY
         # #{name} request validator.
         #
@@ -1713,6 +2099,9 @@ module Tina4
       RUBY
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real valid + invalid spec against the starter rule.
+      emit_validator_test(name, snake)
     end
 
     # ── Generator: seeder ─────────────────────────────────────────────────
@@ -1729,15 +2118,14 @@ module Tina4
         return
       end
 
-      body = ai_fill(
-        "#{table}_field_overrides",
-        "map #{name} fields to fake-data generators (only those needing a specific shape)",
-        "fake.name / fake.email / fake.integer(min: 1, max: 99) / fake.company  (Tina4::FakeData)",
-        "seeder:#{name}: return the field->value overrides Hash",
-        given: "fake -> Tina4::FakeData instance",
-        ret: '{ "email" => ->(f) { f.email }, "status" => "active" }  (Hash)',
-        ground: 'tina4_context("seed ORM model with FakeData", "ruby")'
-      )
+      # Ships working out of the box (not a loud stub): seed_orm auto-fills every
+      # field by type/name, so a zero-override seeder already seeds real rows.
+      # Return overrides only for fields that need a specific shape.
+      body = extend_marker(
+        "override #{name} fields that need a specific shape (optional)",
+        'e.g. { "email" => ->(fake) { fake.email }, "status" => "active" } · ' \
+        'ground: tina4_context("seed ORM model with FakeData", "ruby")'
+      ) + %(  {}\n)
       content = <<~RUBY
         # Seeder for #{name} — run with: tina4ruby seed
         #
@@ -1755,9 +2143,9 @@ module Tina4
         end
 
         # Wiring: seed rows via Tina4.seed_orm. Guarded on a bound database so
-        # merely LOADING this file (e.g. in a spec) does not run the unfilled
-        # placeholder — `tina4ruby seed` binds the DB first, at which point the
-        # override raises LOUD until filled.
+        # merely LOADING this file (e.g. from another script) is a no-op — only
+        # `tina4ruby seed` (which binds the DB first) actually seeds. seed_orm
+        # auto-fills every field, so this works out of the box.
         if Tina4.database
           fake = Tina4::FakeData.new
           summary = Tina4.seed_orm(#{name}, count: 20, overrides: #{table}_field_overrides(fake))
@@ -1766,6 +2154,9 @@ module Tina4
       RUBY
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real seeding spec (runs the seeder against real SQLite).
+      emit_seeder_test(name, table)
     end
 
     # ── Generator: websocket ──────────────────────────────────────────────
@@ -1820,6 +2211,9 @@ module Tina4
       RUBY
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real handler spec (Router registration + drives the handler).
+      emit_websocket_test(ws_path, base, handler)
     end
 
     # ── Generator: listener ───────────────────────────────────────────────
@@ -1865,70 +2259,604 @@ module Tina4
       RUBY
       File.write(path, content)
       puts "  Created #{path}"
+
+      # Co-emit a real event-bus spec (emit the real event, assert it ran).
+      emit_listener_test(event, slug)
+    end
+
+    # ── co-emitted tests: every code-producing generator ships a real spec ──
+    #
+    # One shared writer (#write_test) + one focused builder per generator. The
+    # builders are NOT copy-paste boilerplate — each drives a different real
+    # subsystem (real SQLite / TestClient / Router / ServiceRunner / Queue /
+    # event bus), grounded on the same real-collaborator patterns the
+    # scaffolding-first acceptance matrix already proves. CRUD-shaped scaffolds
+    # (working code) get behavioural specs; logic-shaped scaffolds (loud
+    # NotImplementedError stubs) get wiring specs + a lock-in that the
+    # placeholder fails loud. `test` itself (it IS the test generator) and
+    # form/view (template-only, no Ruby logic to run) are the only exemptions.
+    # Ruby mirror of the Python master's _write_test + _emit_* builders
+    # (tina4_python/cli/__init__.py, owner req 2026-07-10, Phase 4).
+
+    # Write a co-emitted spec to spec/<name>_spec.rb — the SINGLE place a
+    # generated spec is written (path + overwrite refusal + the "Created" line
+    # every generator prints). Generalized from #generate_test so the generators
+    # share one rule instead of a dozen copy-pasted write blocks.
+    def write_test(test_name, content)
+      dir = "spec"
+      FileUtils.mkdir_p(dir)
+      path = File.join(dir, "#{test_name}_spec.rb")
+      if File.exist?(path)
+        puts "  File already exists: #{path}"
+        return
+      end
+      File.write(path, content)
+      puts "  Created #{path}"
+    end
+
+    # snake/kebab/dotted -> PascalCase: user_created -> UserCreated.
+    def pascalize(name)
+      name.to_s.split(/[^0-9a-zA-Z]+/).reject(&:empty?).map { |part| part[0].upcase + part[1..].to_s }.join
+    end
+
+    # A source-text Ruby literal that is a valid value for a scaffolded field
+    # type (used to build a real create() payload in the model spec).
+    def sample_literal(field_type)
+      {
+        "int" => "1", "integer" => "1",
+        "float" => "1.5", "numeric" => "1.5", "decimal" => "1.5",
+        "bool" => "true", "boolean" => "true",
+        "datetime" => '"2020-01-01 00:00:00"',
+        "blob" => '"x"',
+      }.fetch((field_type || "string").to_s.downcase, '"sample"')
+    end
+
+    # model -> real SQLite roundtrip (create / read back / missing -> nil).
+    def emit_model_test(model, table, fields)
+      fields = fields.empty? ? [["name", "string"]] : fields
+      payload = fields.map { |fname, ftype| %("#{fname}" => #{sample_literal(ftype)}) }.join(", ")
+      # Assert a STRING field round-trips (type-safe); else just the id round-trips
+      # (avoids datetime/bool/float equality pitfalls on the read-back).
+      string_field = fields.find { |_f, t| %w[string str text].include?((t || "string").to_s.downcase) }
+      value_assert = string_field ? %(\n      expect(fetched.#{string_field[0]}).to eq("sample")) : ""
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real ORM roundtrip spec for #{model} — no mocks, real SQLite.
+        #
+        # Generated with src/orm/#{table}.rb by `tina4ruby generate model #{model}`.
+        # The model scaffold is working code, so this passes on generation: it
+        # binds a real on-disk SQLite database, creates the table, saves a row and
+        # reads it back.
+        require "spec_helper"
+        require "tmpdir"
+        require_relative "../src/orm/#{table}"
+
+        RSpec.describe "#{model} model (real SQLite)" do
+          before(:each) do
+            @dir = Dir.mktmpdir("#{table}_model")
+            Tina4.bind_database(Tina4::Database.new("sqlite:///" + File.join(@dir, "test.db")))
+            #{model}.create_table
+          end
+
+          after(:each) { FileUtils.rm_rf(@dir) }
+
+          it "creates a row and reads it back" do
+            row = #{model}.create({ #{payload} })
+            expect(row).not_to be_nil
+            expect(row.id).not_to be_nil
+            fetched = #{model}.find(row.id)
+            expect(fetched).not_to be_nil
+            expect(fetched.id).to eq(row.id)#{value_assert}
+          end
+
+          it "returns nil for a missing id" do
+            expect(#{model}.find(999999)).to be_nil
+          end
+        end
+      RUBY
+      write_test("#{table}_model", content)
+    end
+
+    # route (no --model) -> real Router registration + the handler is a live loud
+    # stub. (route --model reuses the secure-gate #generate_test spec instead.)
+    def emit_route_stub_test(route)
+      klass = pascalize(route)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Routing spec for #{route} — no mocks, real Router.
+        #
+        # Generated with src/routes/#{route}.rb by `tina4ruby generate route
+        # #{route}` (no --model). The handlers are AI-FILL stubs that raise until
+        # you implement them, so this tests what IS live on generation: all five
+        # routes register on the REAL Router, and the list handler fails loud until
+        # filled. Fill a handler, then assert its real response here.
+        require "spec_helper"
+
+        RSpec.describe "#{klass} routing (real Router)" do
+          before(:each) { load File.expand_path("../src/routes/#{route}.rb", __dir__) }
+
+          it "registers all five CRUD routes" do
+            paths = Tina4::Router.routes.map { |r| [r.method, r.path] }
+            expect(paths).to include(["GET", "/api/#{route}"])
+            expect(paths).to include(["GET", "/api/#{route}/{id:int}"])
+            expect(paths).to include(["POST", "/api/#{route}"])
+            expect(paths).to include(["PUT", "/api/#{route}/{id:int}"])
+            expect(paths).to include(["DELETE", "/api/#{route}/{id:int}"])
+          end
+
+          it "the list handler is a live stub (raises until filled)" do
+            route, = Tina4::Router.match("GET", "/api/#{route}")
+            expect { route.handler.call(nil, nil) }.to raise_error(NotImplementedError)
+          end
+        end
+      RUBY
+      write_test(route, content)
+    end
+
+    # middleware -> a request routed THROUGH the real server dispatch.
+    def emit_middleware_test(name, snake)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real dispatch spec for the #{name} middleware — no mocks.
+        #
+        # Generated with src/middleware/#{snake}.rb by `tina4ruby generate
+        # middleware #{name}`. Drives the middleware through the REAL server
+        # dispatch (Tina4::Middleware.run_before / run_after) with a real Request +
+        # Response — the same code path the live server runs.
+        require "spec_helper"
+        require "stringio"
+        require_relative "../src/middleware/#{snake}"
+
+        RSpec.describe "#{name} middleware (real dispatch)" do
+          before(:each) { Tina4::Middleware.clear! if Tina4::Middleware.respond_to?(:clear!) }
+
+          def build_request
+            env = {
+              "REQUEST_METHOD" => "GET", "PATH_INFO" => "/", "QUERY_STRING" => "",
+              "HTTP_HOST" => "localhost", "rack.input" => StringIO.new("")
+            }
+            Tina4::Request.new(env)
+          end
+
+          it "before_* passes the request through (does not block the handler)" do
+            response = Tina4::Response.new
+            ok = Tina4::Middleware.run_before([#{name}], build_request, response)
+            expect(ok).to be true                 # the scaffold does not halt the chain
+            expect(response.status_code).to be < 400
+          end
+
+          it "after_* runs and leaves the response intact" do
+            response = Tina4::Response.new
+            Tina4::Middleware.run_after([#{name}], build_request, response)
+            expect(response.status_code).to be < 400
+          end
+        end
+      RUBY
+      write_test(snake, content)
+    end
+
+    # service -> registrable / discoverable on the REAL ServiceRunner + loud stub.
+    def emit_service_test(name, snake)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real ServiceRunner spec for the #{name} service — no mocks.
+        #
+        # Generated with src/services/#{snake}.rb by `tina4ruby generate service
+        # #{name}`. Loading the file registers the scaffold on the REAL
+        # class-level ServiceRunner registry; the task body is an AI-FILL stub that
+        # raises until filled.
+        require "spec_helper"
+        require_relative "../src/services/#{snake}"
+
+        RSpec.describe "#{pascalize(snake)} service (real ServiceRunner)" do
+          it "registers on the ServiceRunner registry" do
+            expect(Tina4::ServiceRunner.list.any? { |s| s[:name] == "#{snake}" }).to be true
+          end
+
+          it "the task is a live stub (raises until filled)" do
+            expect { #{snake}_task(nil) }.to raise_error(NotImplementedError)
+          end
+        end
+      RUBY
+      write_test(snake, content)
+    end
+
+    # queue -> push a REAL job onto the real file-backed Queue + daemon wiring.
+    def emit_queue_test(topic, slug)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real file-backed Queue spec for the #{topic} worker — no mocks.
+        #
+        # Generated with src/services/#{slug}_consumer.rb by `tina4ruby generate
+        # queue #{topic}`. Pushes a REAL job onto the real file-backed Queue and
+        # asserts it is enqueued, and that the consumer is wired as a daemon
+        # service. handle_#{slug} is an AI-FILL stub that raises until you fill it
+        # — then assert the processed side effect here.
+        require "spec_helper"
+        require_relative "../src/services/#{slug}_consumer"
+
+        RSpec.describe "#{pascalize(slug)} queue (real file-backed Queue)" do
+          it "publish enqueues a real job" do
+            before_size = Tina4::Queue.new(topic: "#{topic}").size
+            job = publish_#{slug}({ "hello" => "world" })
+            expect(job).not_to be_nil
+            expect(job.id).not_to be_nil
+            expect(Tina4::Queue.new(topic: "#{topic}").size).to be >= before_size + 1
+          end
+
+          it "the consumer is wired as a daemon service" do
+            svc = Tina4::ServiceRunner.list.find { |s| s[:name] == "#{topic}-consumer" }
+            expect(svc).not_to be_nil
+            expect(svc[:options][:daemon]).to be true
+          end
+
+          it "handle_#{slug} is a live stub (raises until filled)" do
+            expect { handle_#{slug}({}) }.to raise_error(NotImplementedError)
+          end
+        end
+      RUBY
+      write_test(slug, content)
+    end
+
+    # validator -> run the scaffold against valid + invalid real input.
+    def emit_validator_test(name, snake)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real validation spec for validate_#{snake} — no mocks.
+        #
+        # Generated with src/validators/#{snake}.rb by `tina4ruby generate
+        # validator #{name}`. The scaffold ships a starter rule (required "name"),
+        # so this passes on generation — adjust the rules for your payload and
+        # update these cases with them.
+        require "spec_helper"
+        require_relative "../src/validators/#{snake}"
+
+        RSpec.describe "#{pascalize(snake)} validator" do
+          it "valid input passes" do
+            expect(validate_#{snake}({ "name" => "Ada" }).is_valid?).to be true
+          end
+
+          it "invalid input fails with errors" do
+            result = validate_#{snake}({})
+            expect(result.is_valid?).to be false
+            expect(result.errors).not_to be_empty
+          end
+        end
+      RUBY
+      write_test(snake, content)
+    end
+
+    # seeder -> run the scaffold against real SQLite, assert rows created.
+    def emit_seeder_test(model, table)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real seeding spec for the #{model} seeder — no mocks, real SQLite.
+        #
+        # Generated with seeds/#{table}_seeder.rb by `tina4ruby generate seeder
+        # #{model}`. Binds a real SQLite DB, creates the table, then loads the
+        # scaffolded seeder (its guarded block auto-fills every field via FakeData
+        # and seeds rows) and asserts rows were created.
+        require "spec_helper"
+        require "tmpdir"
+        require_relative "../src/orm/#{table}"
+
+        RSpec.describe "#{model} seeder (real SQLite)" do
+          before(:each) do
+            @dir = Dir.mktmpdir("#{table}_seeder")
+            Tina4.bind_database(Tina4::Database.new("sqlite:///" + File.join(@dir, "seed.db")))
+            #{model}.create_table
+          end
+
+          after(:each) { FileUtils.rm_rf(@dir) }
+
+          it "field_overrides returns a Hash" do
+            load File.expand_path("../seeds/#{table}_seeder.rb", __dir__)
+            expect(#{table}_field_overrides(Tina4::FakeData.new)).to be_a(Hash)
+          end
+
+          it "running the seeder creates rows" do
+            load File.expand_path("../seeds/#{table}_seeder.rb", __dir__)
+            expect(#{model}.count).to be >= 1
+          end
+        end
+      RUBY
+      write_test("#{table}_seeder", content)
+    end
+
+    # websocket -> real Router registration + drive the real handler (the
+    # socket-free "close" event) directly (no mock socket).
+    def emit_websocket_test(ws_path, base, _handler)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real handler spec for the #{ws_path} WebSocket route — no mocks.
+        #
+        # Generated with src/routes/ws_#{base}.rb by `tina4ruby generate websocket
+        # ...`. Confirms the handler registers on the REAL Router and drives the
+        # real handler for the :close event (no socket needed). The :message branch
+        # is an AI-FILL stub that raises until you fill it; a full RFC6455 loopback
+        # is out of scope for a unit spec, so assert its broadcast/response against
+        # a live server once implemented.
+        require "spec_helper"
+
+        RSpec.describe "#{pascalize(base)} WebSocket (real Router)" do
+          # `load` (not require) re-registers the handler after spec_helper's
+          # after(:each) Router.clear! wipes the ws routes between examples.
+          before(:each) { load File.expand_path("../src/routes/ws_#{base}.rb", __dir__) }
+
+          def ws_route
+            Tina4::Router.get_web_socket_routes.find { |r| r.path == "#{ws_path}" }
+          end
+
+          it "registers the handler on the Router ws routes" do
+            expect(ws_route).not_to be_nil
+          end
+
+          it "handles the :close event cleanly (no connection needed)" do
+            expect(ws_route.handler.call(nil, :close, nil)).to be_nil
+          end
+
+          it "the :message branch is a live stub (raises until filled)" do
+            expect { ws_route.handler.call(nil, :message, "hi") }.to raise_error(NotImplementedError)
+          end
+        end
+      RUBY
+      write_test("ws_#{base}", content)
+    end
+
+    # listener -> emit the REAL event on the real bus, assert the listener ran.
+    def emit_listener_test(event, slug)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real event-bus spec for the '#{event}' listener — no mocks.
+        #
+        # Generated with src/listeners/#{slug}.rb by `tina4ruby generate listener
+        # #{event}`. Confirms the listener binds on the REAL event bus and that
+        # emitting the event reaches it. The reaction body is an AI-FILL stub that
+        # raises until filled, so a strict emit re-raises here (proving it ran).
+        require "spec_helper"
+
+        RSpec.describe "#{pascalize(slug)} listener (real event bus)" do
+          before(:each) do
+            Tina4::Events.clear
+            load File.expand_path("../src/listeners/#{slug}.rb", __dir__)
+          end
+
+          it "binds on the event bus" do
+            expect(Tina4::Events.events).to include("#{event}")
+            expect(Tina4::Events.listeners("#{event}").length).to be >= 1
+          end
+
+          it "emitting reaches the listener (strict re-raises the stub)" do
+            expect { Tina4::Events.emit("#{event}", { "id" => 1 }, strict: true) }.to raise_error(NotImplementedError)
+          end
+        end
+      RUBY
+      write_test(slug, content)
+    end
+
+    # auth -> real register / login / me end-to-end via the real TestClient.
+    # No dynamic names (always User + /api/auth/*), so a fully-literal
+    # single-quoted heredoc keeps the emitted `#{token}` interpolation intact.
+    def emit_auth_test
+      content = <<~'RUBY'
+        # frozen_string_literal: true
+        #
+        # Real auth spec — register / login / me via the real TestClient.
+        #
+        # Generated with the auth scaffold by `tina4ruby generate auth`. No mocks:
+        # real Router, real Auth (PBKDF2 + JWT), real SQLite. register + login are
+        # public (.no_auth); the token from login authenticates /api/auth/me.
+        require "spec_helper"
+        require "tmpdir"
+        require_relative "../src/orm/user"
+
+        RSpec.describe "Auth (register / login / me via real TestClient)" do
+          let(:client) { Tina4::TestClient.new }
+
+          before(:each) do
+            @dir = Dir.mktmpdir("auth_spec")
+            # Fresh RSA key material so get_token / valid_token agree.
+            Tina4::Auth.instance_variable_set(:@private_key, nil)
+            Tina4::Auth.instance_variable_set(:@public_key, nil)
+            Tina4::Auth.instance_variable_set(:@keys_dir, nil)
+            Tina4::Auth.setup(@dir)
+            # A stray API key would authorise every request regardless of the JWT.
+            @prior_api_key = ENV.delete("TINA4_API_KEY")
+            Tina4.bind_database(Tina4::Database.new("sqlite:///" + File.join(@dir, "auth.db")))
+            User.create_table
+            # `load` (not require) re-registers the routes after spec_helper's
+            # after(:each) Router.clear! wipes them between examples.
+            load File.expand_path("../src/routes/auth.rb", __dir__)
+          end
+
+          after(:each) do
+            ENV["TINA4_API_KEY"] = @prior_api_key if @prior_api_key
+            FileUtils.rm_rf(@dir)
+          end
+
+          it "register, then duplicate 409, then login, then me with the token" do
+            reg = client.post("/api/auth/register", json: { email: "a@b.c", password: "secret12" })
+            expect(reg.status).to eq(201)
+
+            dup = client.post("/api/auth/register", json: { email: "a@b.c", password: "secret12" })
+            expect(dup.status).to eq(409)
+
+            login = client.post("/api/auth/login", json: { email: "a@b.c", password: "secret12" })
+            expect(login.status).to eq(200)
+            token = login.json["token"]
+            expect(token).not_to be_nil
+
+            me = client.get("/api/auth/me", headers: { "Authorization" => "Bearer #{token}" })
+            expect(me.status).to eq(200)
+            expect(me.json["email"]).to eq("a@b.c")
+          end
+
+          it "login with the wrong password is 401" do
+            client.post("/api/auth/register", json: { email: "x@y.z", password: "secret12" })
+            bad = client.post("/api/auth/login", json: { email: "x@y.z", password: "WRONG" })
+            expect(bad.status).to eq(401)
+          end
+
+          it "me without a token is 401" do
+            expect(client.get("/api/auth/me").status).to eq(401)
+          end
+        end
+      RUBY
+      write_test("auth", content)
+    end
+
+    # migration (create_*) -> apply UP then DOWN against real SQLite via the real
+    # Migration runner, asserting the table appears then disappears. Only for
+    # CREATE migrations — a placeholder ALTER migration has no real SQL yet.
+    def emit_migration_test(migration_name, table, _up_file, _down_file)
+      content = <<~RUBY
+        # frozen_string_literal: true
+        #
+        # Real migration spec for #{migration_name} — no mocks, real SQLite.
+        #
+        # Generated with the migration by `tina4ruby generate migration
+        # #{migration_name}`. Runs the migration through the REAL Tina4::Migration
+        # runner against a fresh real SQLite database, asserts the table exists,
+        # then rolls back and asserts it is gone — the raw UP/DOWN SQL the runner
+        # executes.
+        require "spec_helper"
+        require "tmpdir"
+
+        RSpec.describe "#{pascalize(table)} migration (real SQLite up/down)" do
+          it "UP creates the table and DOWN drops it" do
+            dir = Dir.mktmpdir("#{table}_migration")
+            db = Tina4::Database.new("sqlite:///" + File.join(dir, "mig.db"))
+            migrations_dir = File.expand_path("../migrations", __dir__)
+            migration = Tina4::Migration.new(db, migrations_dir: migrations_dir)
+
+            migration.run
+            expect(db.table_exists?("#{table}")).to be true
+
+            migration.rollback(1)
+            expect(db.table_exists?("#{table}")).to be false
+
+            db.close
+            FileUtils.rm_rf(dir)
+          end
+        end
+      RUBY
+      write_test("#{table}_migration", content)
     end
 
     # ── help ──────────────────────────────────────────────────────────────
 
-    def cmd_help
-      puts <<~HELP
-        Tina4 Ruby CLI
-
-        Usage: tina4ruby COMMAND [options]
-
-        Commands:
-          init [NAME]        Initialize a new Tina4 project
-          start              Start the Tina4 web server
-          serve              Alias for start
-          migrate            Run database migrations
-          migrate:status     Show migration status (completed and pending)
-          migrate:rollback   Rollback the last batch of migrations
-          seed               Run all seed files in seeds/
-          seed:create NAME   Create a new seed file
-          test               Run inline tests
-          version            Show Tina4 version
-          routes             List all registered routes
-          console            Start an interactive console
-          ai                 Detect AI tools and install context files
-          metrics            Rank top code-quality offenders
-          help               Show this help message
-
-        Generators:
-          generate model <Name> [--fields "name:string,price:float"]
-          generate route <name> [--model Name] [--public]   Writes secure by default; --public opens them
-          generate crud <Name> [--fields "..."] [--public]  Model + migration + routes + form + view + test
-          generate migration <description>
-          generate middleware <Name>
-          generate test <name>
-          generate form <Name> [--fields "..."]   Form template with inputs matching model fields
-          generate view <Name> [--fields "..."]   List + detail templates for viewing records
-          generate auth                           Login/register/logout routes + User model + templates
-          generate service <Name> [--every 5m | --cron "..."]   Scheduled ServiceRunner task (src/services/)
-          generate queue <topic>                  Producer + consumer worker (src/services/)
-          generate validator <Name>               Request-body Validator (src/validators/)
-          generate seeder <Model>                 FakeData + seed_orm seeder (seeds/)
-          generate websocket <path>               Tina4.websocket handler (src/routes/)
-          generate listener <event>               Tina4::Events.on listener (src/listeners/)
-
-        Scaffolding-first: logic-shaped generators (route without --model, service,
-        queue, validator, seeder, websocket, listener) emit wiring + an AI-FILL
-        placeholder (raise NotImplementedError) where the custom logic goes; CRUD-
-        shaped ones emit working code. Writes are secure by default — use --public
-        to open them.
-
-        Metrics:
-          metrics [--top N] [--json] [--fail-on warn|error] [--path DIR]
-            --top N        Show only the worst N offenders (default: 20)
-            --json         Print machine-readable JSON ({summary, offenders}) for CI
-            --fail-on      Exit 1 if any offender at/above this severity (warn|error)
-            --path DIR     Scan DIR (default: src/, auto-resolves to the framework)
-
-        Field types: string, int, float, bool, text, datetime, blob
-        Table names: singular by default (Product -> product)
-
-        https://tina4.com
-
-        Run 'tina4ruby COMMAND --help' for more information on a command.
-      HELP
+    # Print the human-readable command reference.
+    #
+    # Generated from the COMMANDS and GENERATORS registries — the SAME single
+    # source of truth that drives dispatch (#run / #cmd_generate) and the
+    # `commands --json` manifest — so the help text can never drift from what
+    # the CLI actually does.
+    def cmd_help(_argv = nil)
+      command_rows = COMMANDS.map do |name, spec|
+        ["#{name} #{spec[:usage]}".rstrip, spec[:summary]]
+      end
+      generator_rows = GENERATORS.map do |name, spec|
+        ["generate #{name} #{spec[:usage]}".rstrip, spec[:summary]]
+      end
+      # Align summaries in a column; a left cell longer than the cap overflows
+      # cleanly (2-space gap) rather than pushing every other summary out.
+      pad = [46, (command_rows + generator_rows).map { |left, _| left.length }.max].min
+
+      row = lambda do |left, summary|
+        gap = left.length <= pad ? pad : left.length
+        "  #{left.ljust(gap)}  #{summary}"
+      end
+
+      lines = ["Tina4 Ruby CLI", "", "Usage: tina4ruby COMMAND [options]", "", "Commands:"]
+      lines += command_rows.map { |left, summary| row.call(left, summary) }
+      lines += ["", "Generators:"]
+      lines += generator_rows.map { |left, summary| row.call(left, summary) }
+      lines += [
+        "",
+        "Scaffolding-first: logic-shaped generators (route without --model, service,",
+        "queue, validator, seeder, websocket, listener) emit wiring + an AI-FILL",
+        "placeholder (raise NotImplementedError) where the custom logic goes; CRUD-",
+        "shaped ones emit working code. Writes are secure by default; use --public",
+        "to open them.",
+        "",
+        "Metrics:",
+        "  metrics [--top N] [--json] [--fail-on warn|error] [--path DIR]",
+        "    --top N        Show only the worst N offenders (default: 20)",
+        "    --json         Print machine-readable JSON ({summary, offenders}) for CI",
+        "    --fail-on      Exit 1 if any offender at/above this severity (warn|error)",
+        "    --path DIR     Scan DIR (default: src/, auto-resolves to the framework)",
+        "",
+        "Field types: string, int, float, bool, text, datetime, blob",
+        "Table names: singular by default (Product -> product)",
+        "",
+        "https://tina4.com",
+        "",
+        "Run 'tina4ruby COMMAND --help' for more information on a command.",
+      ]
+      puts lines.join("\n")
+    end
+
+    # ── commands (self-describing manifest) ─────────────────────────────────
+
+    # Build the machine-readable manifest of the CLI's command surface.
+    #
+    # Pure data: reads the COMMANDS registry and the framework version — no
+    # bootstrap, no database, no migrations, no app imports. This is exactly
+    # what `commands --json` serializes and what the tina4 client consumes to
+    # discover which commands this framework supports.
+    #
+    # Shape:
+    #   { "framework" => "ruby", "version" => "<x.y.z>",
+    #     "commands" => [ { "name", "summary", "args"?, "subcommands"? }, ... ] }
+    def commands_manifest
+      require_relative "version"
+      commands = COMMANDS.map do |name, spec|
+        entry = { "name" => name, "summary" => spec[:summary] }
+        entry["args"] = spec[:args].dup if spec[:args]
+        entry["subcommands"] = spec[:subcommands].dup if spec[:subcommands]
+        entry
+      end
+      { "framework" => "ruby", "version" => Tina4::VERSION, "commands" => commands }
+    end
+
+    # Emit the CLI's own command surface — the self-describing manifest.
+    #
+    #   tina4ruby commands           human-readable list
+    #   tina4ruby commands --json    machine-readable manifest (for the tina4 client)
+    #
+    # CHEAP + side-effect-free by contract: it only prints the static COMMANDS
+    # registry plus the framework version. It MUST NOT bootstrap the framework,
+    # open a database, run migrations, or load app modules — the tina4 client
+    # calls this on `tina4 --help`, in any directory, so it must be instant and
+    # safe to run anywhere.
+    def cmd_commands(argv = nil)
+      require "json"
+      argv = argv || []
+      manifest = commands_manifest
+
+      if argv.include?("--json")
+        puts JSON.pretty_generate(manifest)
+        return
+      end
+
+      puts "\nTina4 #{manifest['framework']} - #{manifest['version']}\n\n"
+      width = manifest["commands"].map { |command| command["name"].length }.max
+      manifest["commands"].each do |command|
+        puts "  #{command['name'].ljust(width)}  #{command['summary']}"
+        if command["subcommands"]
+          puts "  #{''.ljust(width)}    #{command['subcommands'].join(', ')}"
+        end
+      end
+      puts
     end
 
     # ── config resolution ──────────────────────────────────────────────────