tina4ruby 3.13.119 → 3.13.121

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af7514098ead4805ac18f09d61f1e816ed27dd28b0a37162f4f579ffea87ecca
-  data.tar.gz: b6742dd30606e26f5d473bf3768dbd68a33286f1f95934aaa63720069d0a0430
+  metadata.gz: 5432ec631264ef420f357f5b662a67ae7d8a22d8f32dfc719dc568e2713f0320
+  data.tar.gz: 0bfad1aff49e4b87548dc0d2ec13b27671295205189404252615810a245b89eb
 SHA512:
-  metadata.gz: fb0d3ba8a09a83d1d207e716ebc97a79e7d142ccfeaaa5c862fa59ba338df98af9f1114d696c2dc7f15f144a63b2f0896607d317b0bf7b49332f01c1a02e56d1
-  data.tar.gz: d86833f86c8e9a90a1510140486b2688d6df712b5d3db281f5dd57d1a6bea02bf4a73a63a5bb03b8f0078fd27b6d3d57ee1cf88eab7679eeb820c95846d2dc32
+  metadata.gz: 8a2875da36ab669f4504833a97c65f85b0f37b48bd622ce692c92f567e3b65bf778950a80167b1e18df1e6617fa9bd4c39008f5efa5d0a6c624ef499789931d2
+  data.tar.gz: d090ea23d3fc4a07e1f0d249970e06300e76718464357ea815937136699b4da9daec59d4d37f425a9a0daa9e2e76698b3eea7d17ebfc6f24ebd1a8d77cb3a2d2

data/lib/tina4/cli.rb

@@ -4,6 +4,8 @@ require "optparse"
 require "fileutils"
 require "set"
 require "json"
+require "tmpdir"    # Dir.mktmpdir — used by the ADR-0063 sandbox edit-hint scan
+require "stringio"  # StringIO — captures generator stdout during the sandbox run
 require_relative "port_takeover"
 
 module Tina4
@@ -289,6 +291,128 @@ module Tina4
     # created_at. The first write then failed with "no such column: name".
     DEFAULT_FIELDS = [["name", "string"]].freeze
 
+    # ADR-0063 (scaffolding envelope v1.1): `# tina4:edit <label>` in a generated
+    # Ruby file, `-- tina4:edit <label>` in a generated SQL file, or
+    # `{# tina4:edit <label> #}` in a generated Twig template marks a
+    # first-edit spot for a developer / coding agent to fill in. The scanner
+    # surfaces every match as an `edit_hints` entry in the `generate_v1_1`
+    # envelope AND under "Edit these lines:" in the human stderr block.
+    #
+    # One regex covers all three comment styles - `//`-style (Ruby `#`), SQL
+    # (`--`), and Twig (`{# ... #}`) - so the same scanner drives
+    # model / migration / middleware / route AND the form + view Twig
+    # generators (ADR-0063 twig-scanner parity, 3.13.121). The optional
+    # `(?:\s*#\})?` tail strips the Twig closing sequence so the captured
+    # label stays clean ("add fields here", not "add fields here #}").
+    # Ported verbatim from tina4-php's `collectEditHintsFromContent`.
+    EDIT_MARKER_RE = %r{(?://|#|--|\{\#)\s*tina4:edit[ \t]+(.+?)(?:\s*\#\})?\s*$}.freeze
+
+    # ADR-0063 next-step catalogue: 5 short actionable lines per resolution-aware
+    # verb. Rendered under "Next:" in the human block AND surfaced as
+    # `resolution.next[]` in the envelope. Each entry is a `Proc` that consumes
+    # the resolution so paths / class names substitute correctly. Curated (not
+    # generated) so a caller sees consistent, sensible next steps.
+    NEXT_STEPS = {
+      "model" => lambda do |res|
+        table = res["table_name"] || "resource"
+        class_name = res["class_name"] || "Model"
+        file_path = res["file_path"] || "src/orm/#{table}.rb"
+        route = (res["routes"] || []).first || "/#{table}"
+        [
+          "Edit #{file_path} to add fields beyond the default 'name'",
+          "Apply the migration:   tina4ruby migrate",
+          "Try it:                tina4ruby serve  ->  curl http://localhost:7147#{route}",
+          "Add CRUD scaffolding:  tina4ruby generate crud #{class_name} --skip-model",
+          "Seed sample data:      tina4ruby generate seeder #{class_name} && tina4ruby seed",
+        ]
+      end,
+      "route" => lambda do |res|
+        file_path = res["file_path"] || "src/routes/resource.rb"
+        route = (res["routes"] || []).first || "/api/resource"
+        test_path = (res["test_paths"] || []).first || "spec/routes/resource_spec.rb"
+        [
+          "Edit #{file_path} to customise the response",
+          "Try it:                tina4ruby serve  ->  curl http://localhost:7147#{route}",
+          "Add real assertions:   #{test_path}",
+          "Bearer-gate is on:     writes require a Bearer token (rerun with --public to open)",
+          "Browse the API:        tina4ruby serve  ->  http://localhost:7147/swagger",
+        ]
+      end,
+      "migration" => lambda do |res|
+        file_path = res["file_path"] || "migrations/new_migration.sql"
+        down_path = file_path.sub(/\.sql$/, ".down.sql")
+        [
+          "Edit #{file_path} to add columns beyond id + created_at",
+          "Mirror the change in:  #{down_path}",
+          "Apply it:              tina4ruby migrate",
+          "Check status:          tina4ruby migrate status",
+          "Rollback if wrong:     tina4ruby migrate rollback",
+        ]
+      end,
+      "middleware" => lambda do |res|
+        class_name = res["class_name"] || "Middleware"
+        file_path = res["file_path"] || "src/middleware/middleware.rb"
+        [
+          "Edit #{file_path} to guard the request or shape the response",
+          "Wire it into a route: middleware: [#{class_name}] on Tina4.get/post/...",
+          "Wire it globally:     Tina4::Router.use(#{class_name})",
+          "Prove the gate:       add a real spec covering allow + deny",
+          "Chain more:           order in the middleware: [] list is registration order",
+        ]
+      end,
+      "form" => lambda do |res|
+        class_name = res["class_name"] || "Form"
+        file_path = res["file_path"] || "src/templates/forms/form.twig"
+        route = (res["routes"] || []).first || "/#{to_snake_case_static(class_name)}"
+        [
+          "Edit #{file_path} to restyle / add fields to the form",
+          "Render it:             response.render(\"forms/#{File.basename(file_path)}\", { item: item })",
+          "Wire it to a route:    tina4ruby generate route #{class_name}",
+          "Add a matching model:  tina4ruby generate model #{class_name}",
+          "Try it:                tina4ruby serve  ->  http://localhost:7147#{route}",
+        ]
+      end,
+      "view" => lambda do |res|
+        class_name = res["class_name"] || "View"
+        list_path = res["file_path"] || "src/templates/pages/list.twig"
+        detail_path = (res["transformations"] || []).find { |t| t["kind"] == "detail_view" }
+        detail_path = detail_path ? detail_path["to"] : list_path.sub(/list\.twig$/, "detail.twig")
+        route = (res["routes"] || []).first || "/#{to_snake_case_static(class_name)}"
+        [
+          "Edit #{list_path} for the list view (add sort / filter / pagination)",
+          "Edit #{detail_path} for the detail view (add related records / actions)",
+          "Wire it to a route:    tina4ruby generate route #{class_name}",
+          "Add a matching model:  tina4ruby generate model #{class_name}",
+          "Try it:                tina4ruby serve  ->  http://localhost:7147#{route}",
+        ]
+      end,
+    }.freeze
+
+    # Static helper for the NEXT_STEPS lambdas above - avoids reaching for the
+    # per-instance to_snake_case when only the class name is known.
+    def self.to_snake_case_static(name)
+      s = name.to_s
+      s.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+       .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+       .downcase
+    end
+
+    # ADR-0063: freeze `Time.now` for the duration of one `cmd_generate` call.
+    # Both the resolution builders (`build_migration_resolution`,
+    # `build_model_resolution`) and the actual generator (`generate_migration`)
+    # embed a timestamp in the migration filename. If they call `Time.now`
+    # independently, the sandbox pre-run (which drives edit_hints for dry-run
+    # mode) and the real run can pick different seconds, and the envelope's
+    # `file_path` would drift from the file that actually gets written. One
+    # memoised timestamp per command run fixes that.
+    def generate_timestamp
+      @generate_timestamp ||= Time.now
+    end
+
+    def reset_generate_timestamp!
+      @generate_timestamp = nil
+    end
+
     # Parsed --fields, or the default single `name` column when none given.
     def fields_or_default(fields_str)
       parsed = parse_fields(fields_str)
@@ -331,7 +455,11 @@ module Tina4
       bar = "─" * 60
       head = "#{indent}# ─── AI-FILL: #{fn} "
       head += "─" * [4, 66 - head.length].max
-      lines = [head, "#{indent}# Intent:  #{intent}"]
+      # ADR-0063: prepend a `# tina4:edit <label>` machine-readable pointer so a
+      # tool can surface WHERE this stub needs custom logic without parsing the
+      # AI-FILL banner. `intent` is the developer-facing TODO — reuse it as the
+      # label (short, actionable, no period).
+      lines = ["#{indent}# tina4:edit  #{intent}", head, "#{indent}# Intent:  #{intent}"]
       lines << "#{indent}# Given:   #{given}" if given
       lines << "#{indent}# Use:     #{use}"
       lines << "#{indent}# Return:  #{ret}" if ret
@@ -348,7 +476,10 @@ module Tina4
     def extend_marker(note, hint = "", indent: "  ")
       head = "#{indent}# ─── EXTEND: #{note} "
       head += "─" * [4, 66 - head.length].max
-      out = head + "\n"
+      # ADR-0063: `# tina4:edit <label>` is the machine-readable partner of the
+      # ─── EXTEND banner. `note` is the human-shaped TODO — reuse it verbatim.
+      out = "#{indent}# tina4:edit  #{note}\n"
+      out += head + "\n"
       out += "#{indent}# #{hint}\n" unless hint.to_s.empty?
       out
     end
@@ -602,22 +733,52 @@ module Tina4
 
     # ── 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)`).
+    # Create a new timestamped migration file (UP .sql + .down.sql). The
+    # description can be human prose ("add users table") — it is slugified into
+    # a snake_case name ("add_users_table") and then handed to the SAME
+    # resolution-aware generator that backs `tina4ruby generate migration`, so
+    # both CLI paths emit the ADR-0063 `generate_v1_1` envelope with matching
+    # `edit_hints[]`, `next[]`, human resolution block, and the same
+    # `# tina4:edit` markers in the generated .sql files. The only intentional
+    # difference is `emit_test: false` — `migrate:create` never co-emits a
+    # test file, preserving its "just a migration" semantics. CHEAP +
+    # database-free: it never boots the app, opens a DB, or writes a tracking
+    # row.
+    #
+    # Accepts `--json` and `--dry-run` (same as `generate migration`); anything
+    # else is treated as description tokens joined with a space (parity with
+    # Python's `" ".join(args)`).
     def cmd_migrate_create(argv)
-      description = (argv || []).join(" ").strip
+      argv = argv || []
+      flags, positional = parse_flags(argv)
+      json_mode = flags.delete("json") ? true : false
+      dry_run   = flags.delete("dry-run") ? true : false
+
+      description = positional.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}"
+      # Slugify the human description into a snake_case migration NAME so the
+      # filename matches what `generate migration <name>` would produce, and
+      # so the generator's `create_X` schema-awareness fires when the
+      # description starts with "create <thing>". Regex + downcase mirrors the
+      # Python master's `re.sub(r'[^a-z0-9]+', '_', desc, flags=re.I).lower()`
+      # convention that the four frameworks share for migration filenames.
+      name = description.gsub(/[^a-z0-9]+/i, "_").downcase.gsub(/^_|_$/, "")
+
+      # Fresh timestamp per command run so the sandbox pre-run (edit_hints)
+      # and the real generator agree on the same second — ADR-0063.
+      reset_generate_timestamp!
+
+      run_resolution_aware_generator(
+        "migration", name, flags,
+        json_mode: json_mode,
+        dry_run: dry_run,
+        gen_spec: GENERATORS["migration"],
+        generator_kwargs: { emit_test: false, description: description }
+      )
     end
 
     # ── migrate:status ─────────────────────────────────────────────────────
@@ -1117,6 +1278,10 @@ module Tina4
     # will produce before it runs.
 
     def cmd_generate(argv)
+      # ADR-0063: fresh timestamp per command run so the sandbox pre-run + the
+      # real generator both agree on the migration filename.
+      reset_generate_timestamp!
+
       what = argv.shift
       all = GENERATORS.keys.join(", ")  # single source: the GENERATORS registry
 
@@ -1126,7 +1291,7 @@ module Tina4
         puts '  Options:    --fields "name:string,price:float"  --model ModelName'
         puts '              --public                  open a route'"'"'s writes (default: secure)'
         puts '              --every 5m | --cron "..."  service schedule'
-        puts '              --json                    emit the generate_v1 resolution envelope'
+        puts '              --json                    emit the generate_v1_1 resolution envelope'
         puts '              --dry-run                 plan the scaffold; write no files'
         exit 1
       end
@@ -1155,18 +1320,49 @@ module Tina4
         exit 1
       end
 
-      # Only the four resolution-aware targets emit a resolution + JSON envelope;
+      # Only the resolution-aware targets emit a resolution + JSON envelope;
       # every other generator keeps its existing behaviour so nothing regresses.
-      resolution_aware = %w[model route migration middleware]
+      # ADR-0063 (3.13.121): form + view joined so their baked `{# tina4:edit ... #}`
+      # markers surface in resolution.edit_hints[] under the same v1.1 envelope.
+      resolution_aware = %w[model route migration middleware form view]
       if !resolution_aware.include?(what)
         send(gen_spec[:handler], name, flags)
         return
       end
 
+      run_resolution_aware_generator(
+        what, name, flags,
+        json_mode: json_mode, dry_run: dry_run, gen_spec: gen_spec
+      )
+    end
+
+    # Shared entry point for the four resolution-aware generators (model,
+    # route, migration, middleware) — used by BOTH `cmd_generate` and by
+    # `cmd_migrate_create`, so both CLI paths emit the SAME ADR-0063 envelope
+    # (`edit_hints[]`, `next[]`, human resolution block, `# tina4:edit`
+    # markers). `generator_kwargs` are forwarded verbatim to the generator
+    # method — that is how `cmd_migrate_create` passes `emit_test: false` and
+    # `description:` without duplicating the whole envelope-emission path.
+    def run_resolution_aware_generator(what, name, flags,
+                                       json_mode:, dry_run:,
+                                       gen_spec: nil,
+                                       generator_kwargs: {})
+      gen_spec ||= GENERATORS[what]
+
       resolution = build_generate_resolution(what, name, flags)
+      # ADR-0063 additive v1.1 keys: curated next-steps (pure fn of resolution)
+      # and edit_hints (scan of generated files for `# tina4:edit <label>`).
+      resolution["next"] = build_next_steps(what, resolution)
+      resolution["edit_hints"] =
+        collect_edit_hints_via_sandbox(gen_spec, name, flags, **generator_kwargs)
 
       if json_mode
-        actions_taken = dry_run ? [] : run_generator_capturing_actions(gen_spec, name, flags)
+        actions_taken =
+          if dry_run
+            []
+          else
+            run_generator_capturing_actions(gen_spec, name, flags, **generator_kwargs)
+          end
         envelope = build_generate_envelope(what, name, flags, resolution, actions_taken, dry_run)
         puts JSON.pretty_generate(envelope)
         return
@@ -1179,8 +1375,84 @@ module Tina4
       if dry_run
         $stderr.puts "  (dry-run — no files written)"
       else
-        send(gen_spec[:handler], name, flags)
+        send(gen_spec[:handler], name, flags, **generator_kwargs)
+      end
+    end
+
+    # ADR-0063 helpers ────────────────────────────────────────────────────────
+
+    # Curated per-verb next-step list. Pure function of the resolution; never
+    # scans the filesystem, so it works identically in dry-run and real-run.
+    def build_next_steps(target, resolution)
+      builder = NEXT_STEPS[target]
+      return [] unless builder
+      Array(builder.call(resolution))
+    end
+
+    # Scan a list of files for `# tina4:edit <label>` (Ruby) or
+    # `-- tina4:edit <label>` (SQL) lines. Returns `[{file, line, label}]` in
+    # the same order the files were passed. Missing / unreadable files are
+    # skipped silently (a scaffold that already exists on disk simply produces
+    # no hint for that path — that is the intended behaviour).
+    def scan_edit_hints_from_files(paths)
+      hints = []
+      paths.each do |path|
+        next unless path
+        next unless File.file?(path)
+        begin
+          content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace)
+        rescue SystemCallError
+          next
+        end
+        content.each_line.with_index(1) do |line, lineno|
+          next unless (m = line.match(EDIT_MARKER_RE))
+          hints << { "file" => path, "line" => lineno, "label" => m[1].strip }
+        end
+      end
+      hints
+    end
+
+    # Run the generator inside a throw-away tmpdir with `$stdout` captured, then
+    # walk every written file and scan for `# tina4:edit` / `-- tina4:edit`
+    # markers. Used for BOTH dry-run and real-run modes so the envelope always
+    # ships accurate `edit_hints` before any live-cwd write happens (preserves
+    # the "Ctrl-C between plan and write" contract of the human block).
+    #
+    # `generate_timestamp` is shared with the real run so a migration file
+    # sandboxed here has the SAME timestamped basename as the file that lands
+    # in the developer's cwd - the hint's `file` field matches disk verbatim.
+    # `generator_kwargs` are forwarded verbatim to the generator method so the
+    # sandbox pre-run produces the same files (and therefore the same edit
+    # markers) as the real run — used by `cmd_migrate_create` to thread
+    # `emit_test: false` + `description:` through without a bespoke sandbox.
+    def collect_edit_hints_via_sandbox(gen_spec, name, flags, **generator_kwargs)
+      hints = []
+      Dir.mktmpdir("tina4_edit_hints") do |sandbox|
+        # Block-form Dir.chdir composes cleanly under an outer block-form
+        # Dir.chdir (Ruby 3.x warns on nested non-block chdir). No `ensure`
+        # cwd-restore needed - the block form guarantees it.
+        Dir.chdir(sandbox) do
+          buffer = StringIO.new
+          original_stdout = $stdout
+          $stdout = buffer
+          begin
+            # A generator failure inside the sandbox must never break the caller's
+            # real run - rescue everything, return whatever hints we managed to
+            # gather. The real run will error the same way if it is going to.
+            send(gen_spec[:handler], name, flags.dup, **generator_kwargs)
+          rescue StandardError, LoadError, ScriptError
+            # swallow - the sandbox is best-effort
+          ensure
+            $stdout = original_stdout
+          end
+          Dir.glob("**/*", File::FNM_DOTMATCH).sort.each do |rel_path|
+            next if [".", ".."].include?(File.basename(rel_path))
+            next unless File.file?(rel_path)
+            hints.concat(scan_edit_hints_from_files([rel_path]))
+          end
+        end
       end
+      hints
     end
 
     # ── generate resolution helpers ────────────────────────────────────────
@@ -1200,6 +1472,8 @@ module Tina4
       when "route"      then build_route_resolution(name, flags)
       when "migration"  then build_migration_resolution(name, flags)
       when "middleware" then build_middleware_resolution(name, flags)
+      when "form"       then build_form_resolution(name, flags)
+      when "view"       then build_view_resolution(name, flags)
       else
         { "class_name" => name.to_s, "table_name" => nil, "file_path" => nil,
           "migration_path" => nil, "transformations" => [],
@@ -1227,7 +1501,10 @@ module Tina4
       # The migration filename embeds a timestamp; predict it deterministically
       # so a `--dry-run` and the real run agree on the same second. Two
       # generations within the same second collide anyway (existing behaviour).
-      timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+      # ADR-0063: `generate_timestamp` memoises `Time.now` per `cmd_generate`
+      # call so the sandbox pre-run + real run share one second, and the
+      # envelope's `migration_path` matches the file that actually lands.
+      timestamp = generate_timestamp.strftime("%Y%m%d%H%M%S")
       {
         "class_name"     => name.to_s,
         "table_name"     => table,
@@ -1253,7 +1530,8 @@ module Tina4
     end
 
     def build_migration_resolution(name, _flags)
-      timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+      # ADR-0063: shared memoised timestamp (see `generate_timestamp`).
+      timestamp = generate_timestamp.strftime("%Y%m%d%H%M%S")
       base = name.to_s.sub(/^create_/, "").sub(/^add_/, "").sub(/^drop_/, "")
       snake_base = to_snake_case(base)
       path = "migrations/#{timestamp}_#{name}.sql"
@@ -1281,6 +1559,54 @@ module Tina4
       }
     end
 
+    # Form generator writes ONE Twig template in src/templates/forms/<snake>.twig.
+    # `file_path` names that primary file; the scanner walks every generated
+    # file in the sandbox, so the twig `{# tina4:edit ... #}` marker landing
+    # inside it flows into resolution.edit_hints[] regardless.
+    def build_form_resolution(name, _flags)
+      snake = to_snake_case(name)
+      route_name = to_route_name(name)
+      {
+        "class_name"      => name.to_s,
+        "table_name"      => nil,
+        "file_path"       => "src/templates/forms/#{snake}.twig",
+        "migration_path"  => nil,
+        "transformations" => [],
+        "routes"          => ["/api/#{route_name}"],
+        "test_paths"      => []
+      }
+    end
+
+    # View generator writes TWO Twig templates: a list view keyed by the
+    # (plural) route name and a detail view keyed by the (singular) class
+    # snake. `file_path` names the list (the primary entry point); the
+    # detail path is surfaced under `transformations` so a caller / NEXT_STEPS
+    # lambda / human block can find it without re-deriving. Scanner picks up
+    # both files from the sandbox walk regardless of these fields.
+    def build_view_resolution(name, _flags)
+      snake = to_snake_case(name)
+      route_name = to_route_name(name)
+      list_path = "src/templates/pages/#{route_name}.twig"
+      detail_path = "src/templates/pages/#{snake}.twig"
+      {
+        "class_name"      => name.to_s,
+        "table_name"      => nil,
+        "file_path"       => list_path,
+        "migration_path"  => nil,
+        "transformations" => [
+          {
+            "kind"     => "detail_view",
+            "from"     => name.to_s,
+            "to"       => detail_path,
+            "reason"   => "list view is #{route_name}.twig; detail view keyed by the singular class snake",
+            "override" => nil
+          }
+        ],
+        "routes"          => ["/#{route_name}", "/#{route_name}/{id}"],
+        "test_paths"      => []
+      }
+    end
+
     def build_generate_envelope(target, name, flags, resolution, actions_taken, dry_run)
       {
         "command"       => "generate",
@@ -1313,12 +1639,33 @@ module Tina4
       if resolution["migration_path"] && resolution["migration_path"] != resolution["file_path"]
         lines << "  migration  #{resolution['migration_path']}"
       end
+      # ADR-0063: surface the pre-existing test_paths (v1 field, only now printed
+      # in the human block) alongside the two new sections.
+      if resolution["test_paths"] && !resolution["test_paths"].empty?
+        lines << "  tests      #{resolution['test_paths'].join(', ')}"
+      end
       pluralized = resolution["transformations"].find { |t| t["kind"] == "reserved_word_pluralize" }
       if pluralized
         lines << ""
         lines << "  To keep the raw name '#{pluralized['from']}' as the table:"
         lines << "    tina4ruby generate #{target} #{name} --table #{pluralized['from']} --quote  (opt-in, ADR-0062 forthcoming)"
       end
+      # ADR-0063 v1.1: surface `edit_hints[]` under "Edit these lines:" and
+      # `next[]` under "Next:" — both additive; missing / empty arrays elide
+      # cleanly. The `file:line  label` shape is grep-friendly for humans and
+      # machine-parseable for tools.
+      if resolution["edit_hints"] && !resolution["edit_hints"].empty?
+        lines << ""
+        lines << "  Edit these lines:"
+        resolution["edit_hints"].each do |h|
+          lines << "    #{h['file']}:#{h['line']}  #{h['label']}"
+        end
+      end
+      if resolution["next"] && !resolution["next"].empty?
+        lines << ""
+        lines << "  Next:"
+        resolution["next"].each { |step| lines << "    #{step}" }
+      end
       lines.join("\n")
     end
 
@@ -1326,14 +1673,17 @@ module Tina4
     # `actions_taken` list from the "  Created <path>" lines the generators
     # emit. Machine callers get one clean JSON envelope on stdout; the
     # generator's own log stays discoverable via the returned list.
-    def run_generator_capturing_actions(gen_spec, name, flags)
+    # `generator_kwargs` are forwarded verbatim to the generator method so
+    # callers (e.g. `cmd_migrate_create`) can pass overrides like
+    # `emit_test: false` without duplicating the envelope-emission path.
+    def run_generator_capturing_actions(gen_spec, name, flags, **generator_kwargs)
       require "stringio"
       require "json"
       buffer = StringIO.new
       original = $stdout
       $stdout = buffer
       begin
-        send(gen_spec[:handler], name, flags)
+        send(gen_spec[:handler], name, flags, **generator_kwargs)
       ensure
         $stdout = original
       end
@@ -1371,6 +1721,7 @@ module Tina4
         class #{name} < Tina4::ORM
           table_name "#{table}"
 
+          # tina4:edit  add fields beyond the default 'name'
         #{field_lines.join("\n")}
         end
       RUBY
@@ -1627,12 +1978,25 @@ module Tina4
 
     # ── Generator: migration ─────────────────────────────────────────────
 
-    def generate_migration(name, flags = {}, fields_override: nil, table_override: nil, emit_test: true)
-      now = Time.now
+    def generate_migration(name, flags = {}, fields_override: nil, table_override: nil,
+                           emit_test: true, description: nil)
+      # ADR-0063: `generate_timestamp` is the shared memoised `Time.now` for
+      # this cmd_generate run; the resolution's `migration_path` uses the SAME
+      # value, so envelope and disk agree.
+      now = generate_timestamp
       timestamp = now.strftime("%Y%m%d%H%M%S")
       dir = "migrations"
       FileUtils.mkdir_p(dir)
 
+      # `description` (when supplied by `cmd_migrate_create`) keeps the raw
+      # human prose that appears in the file HEADER — the filename still uses
+      # the snake_case `name`, so the two CLI paths write matching filenames
+      # while the delegating path preserves the readable "add users table"
+      # comment inside the file. Falls back to `name` when no description was
+      # supplied (the `tina4ruby generate migration` path, where `name` is
+      # already snake_case).
+      header_text = description || name
+
       # Determine table name
       if table_override
         table = table_override
@@ -1661,11 +2025,18 @@ module Tina4
         end
         col_lines << "    created_at TEXT DEFAULT CURRENT_TIMESTAMP"
 
-        up_sql = "CREATE TABLE IF NOT EXISTS #{table} (\n#{col_lines.join(",\n")}\n);"
-        down_sql = "DROP TABLE IF EXISTS #{table};"
+        # ADR-0063: `-- tina4:edit` marker for the SQL scanner (mirrors `# tina4:edit`
+        # in Ruby files). The scanner regex accepts both comment prefixes.
+        up_sql = "CREATE TABLE IF NOT EXISTS #{table} (\n" \
+                 "    -- tina4:edit  add columns beyond id + created_at\n" \
+                 "#{col_lines.join(",\n")}\n);"
+        down_sql = "-- tina4:edit  mirror the CREATE's added columns in the rollback\n" \
+                   "DROP TABLE IF EXISTS #{table};"
       else
-        up_sql = "-- Write your UP migration SQL here\n-- Example: ALTER TABLE #{table} ADD COLUMN new_col TEXT DEFAULT '';"
-        down_sql = "-- Write your DOWN rollback SQL here\n-- Example: ALTER TABLE #{table} DROP COLUMN new_col;"
+        up_sql = "-- tina4:edit  write your UP migration SQL here\n" \
+                 "-- Example: ALTER TABLE #{table} ADD COLUMN new_col TEXT DEFAULT '';"
+        down_sql = "-- tina4:edit  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
@@ -1674,7 +2045,7 @@ module Tina4
       # rollback SQL lives solely in the sibling .down.sql. Matches the Python
       # master (tina4_python/cli/__init__.py).
       content = <<~SQL
-        -- Migration: #{name}
+        -- Migration: #{header_text}
         -- Created: #{now.strftime("%Y-%m-%d %H:%M:%S")}
 
         #{up_sql}
@@ -1687,7 +2058,7 @@ module Tina4
       down_filename = "#{timestamp}_#{name}.down.sql"
       down_path = File.join(dir, down_filename)
       down_content = <<~SQL
-        -- Rollback: #{name}
+        -- Rollback: #{header_text}
         -- Created: #{now.strftime("%Y-%m-%d %H:%M:%S")}
 
         #{down_sql}
@@ -1727,12 +2098,14 @@ module Tina4
             # Runs before the route handler.
             # Return [request, response] to continue, or
             # return [request, response.json({ error: "Unauthorized" }, 401)] to block.
+            # tina4:edit  guard the request here
             Tina4::Log.info("#{name}: \#{request.method} \#{request.path}")
             [request, response]
           end
 
           def self.after_#{snake}(request, response)
             # Runs after the route handler.
+            # tina4:edit  post-process the response here
             [request, response]
           end
         end
@@ -1836,6 +2209,7 @@ module Tina4
           # Tests for #{name} CRUD operations
           RSpec.describe "#{model}" do
             before(:each) do
+              # tina4:edit  seed real fixtures for a real DB
               # Set up test fixtures
             end
 
@@ -1844,7 +2218,7 @@ module Tina4
             end
 
             it "lists #{snake}" do
-              # TODO: implement
+              # tina4:edit  replace the tautology with a real assertion
               expect(true).to be true
             end
 
@@ -1875,6 +2249,7 @@ module Tina4
           # Tests for #{name}
           RSpec.describe "#{class_name}" do
             before(:each) do
+              # tina4:edit  seed real fixtures for a real DB
               # Set up test fixtures
             end
 
@@ -1883,7 +2258,7 @@ module Tina4
             end
 
             it "works as expected" do
-              # TODO: replace with real tests
+              # tina4:edit  replace the tautology with a real assertion
               expect(true).to be true
             end
           end
@@ -1955,6 +2330,7 @@ module Tina4
       end
 
       content = <<~HTML
+        {# tina4:edit  restyle the form beyond the scaffolded defaults #}
         {% extends "base.twig" %}
         {% block title %}#{name} {% if item.id %}Edit{% else %}Create{% endif %}{% endblock %}
         {% block content %}
@@ -1994,6 +2370,7 @@ module Tina4
         td = cols.map { |c| "<td>{{ item.#{c} }}</td>" }.join("\n                ")
 
         list_content = <<~HTML
+          {# tina4:edit  add sort / filter / pagination controls to the list #}
           {% extends "base.twig" %}
           {% block title %}#{name}s{% endblock %}
           {% block content %}
@@ -2044,6 +2421,7 @@ module Tina4
         end.join("\n")
 
         detail_content = <<~HTML
+          {# tina4:edit  extend the detail view with related records or actions #}
           {% extends "base.twig" %}
           {% block title %}#{name} Detail{% endblock %}
           {% block content %}
@@ -2087,6 +2465,7 @@ module Tina4
           # clears the router's auth_required).
           Tina4.post "/api/auth/register", auth: false do |request, response|
             # Register a new user
+            # tina4:edit  harden the register flow (rate limit / captcha / password rules)
             email = request.body["email"].to_s
             password = request.body["password"].to_s
 
@@ -2112,6 +2491,7 @@ module Tina4
           # PUBLIC: login mints the token — clear BOTH write gates (see register).
           Tina4.post "/api/auth/login", auth: false do |request, response|
             # Login with email and password
+            # tina4:edit  harden the login flow (rate limit / lockout after N failures)
             email = request.body["email"].to_s
             password = request.body["password"].to_s
 
@@ -3146,7 +3526,12 @@ module Tina4
         # KNOW the envelope shape before it invokes generate (see cmd_generate).
         # Bump `version` when the envelope shape changes; add a new envelope
         # name rather than mutating the existing one.
-        "resolution_contract" => { "version" => "1", "envelope" => "generate_v1" }
+        # ADR-0063: v1.1 adds two additive keys to `resolution` — `edit_hints[]`
+        # (grep of every `# tina4:edit <label>` / `-- tina4:edit <label>` line
+        # in the generated files) and `next[]` (curated actionable steps). Every
+        # v1 key is preserved untouched, so a v1 caller reading v1.1 output
+        # keeps working.
+        "resolution_contract" => { "version" => "1.1", "envelope" => "generate_v1_1" }
       }
     end
 

data/lib/tina4/dev_admin.rb

@@ -7,6 +7,8 @@ require "net/http"
 require "uri"
 require "fileutils"
 require "shellwords"
+require "rbconfig" # RbConfig.ruby for scaffold_run's Open3.capture3 call to exe/tina4ruby
+require "open3"    # scaffold_run shells to exe/tina4ruby generate <kind> <name>
 require_relative "metrics"
 
 module Tina4
@@ -2294,38 +2296,53 @@ module Tina4
         ] }
       end
 
+      # scaffold_run — shells to `exe/tina4ruby generate <kind> <name>` so the
+      # dev-admin endpoint emits the ADR-0063 resolution envelope through the
+      # SAME code path the CLI + MCP go through, instead of the old inline
+      # File.write branches that skipped every marker + envelope. Mirrors PHP
+      # (Tina4/DevAdmin.php:2506-2520, shell_exec 'php bin/tina4php generate ...')
+      # and Node (packages/core/src/devAdmin.ts:handleScaffoldRun, execFileSync
+      # 'npx tina4nodejs generate ...'). The captured stdout+stderr is returned
+      # as `output`, matching PHP/Node's shape.
+      #
+      # ADR-0063: the four resolution-aware verbs (route / model / migration /
+      # middleware) are the whitelist here — the same set the CLI declares in
+      # cli.rb's `resolution_aware`. An unknown kind returns {ok:false,error}
+      # instead of shelling to the CLI with an invalid subcommand.
+      SCAFFOLD_ALLOWED_KINDS = %w[route model migration middleware].freeze
+
       def scaffold_run(body)
-        kind = body["kind"].to_s
+        require "open3"
+
+        kind = body["kind"].to_s.strip.downcase
         name = body["name"].to_s.strip
+
         return { ok: false, error: "kind + name required" } if kind.empty? || name.empty?
-        project = Dir.pwd
-        case kind
-        when "route"
-          target = File.join(project, "src", "routes", "#{name}.rb")
-          FileUtils.mkdir_p(File.dirname(target))
-          File.write(target, "# #{name} routes\nTina4::Router.get(\"/api/#{name}\") do |req, res|\n  res.call({ hello: \"#{name}\" })\nend\n") unless File.exist?(target)
-          { ok: true, created: target.sub("#{project}/", "") }
-        when "model"
-          target = File.join(project, "src", "orm", "#{name}.rb")
-          FileUtils.mkdir_p(File.dirname(target))
-          cls = name.to_s.split(/[_-]/).map(&:capitalize).join
-          File.write(target, "class #{cls} < Tina4::ORM\n  integer_field :id, primary_key: true, auto_increment: true\n  string_field :name\nend\n") unless File.exist?(target)
-          { ok: true, created: target.sub("#{project}/", "") }
-        when "migration"
-          ts = Time.now.strftime("%Y%m%d%H%M%S")
-          target = File.join(project, "migrations", "#{ts}_#{name}.sql")
-          FileUtils.mkdir_p(File.dirname(target))
-          File.write(target, "-- migration: #{name}\n")
-          { ok: true, created: target.sub("#{project}/", "") }
-        when "middleware"
-          target = File.join(project, "src", "app", "#{name}.rb")
-          FileUtils.mkdir_p(File.dirname(target))
-          cls = name.to_s.split(/[_-]/).map(&:capitalize).join
-          File.write(target, "class #{cls}\n  def self.before_check(req, res); [req, res]; end\nend\n") unless File.exist?(target)
-          { ok: true, created: target.sub("#{project}/", "") }
-        else
-          { ok: false, error: "unknown kind: #{kind}" }
+        unless SCAFFOLD_ALLOWED_KINDS.include?(kind)
+          return { ok: false, error: "unknown kind: #{kind}" }
+        end
+        # Same name validation the PHP + Node dev-admin endpoints apply —
+        # keeps a shell-metacharacter payload out of the generator arg.
+        unless name =~ /\A[A-Za-z][\w]*\z/
+          return { ok: false, error: "name must match [A-Za-z][A-Za-z0-9_]*" }
         end
+
+        project = Dir.pwd
+        exe = File.join(project, "exe", "tina4ruby")
+
+        stdout, stderr, status = Open3.capture3(
+          RbConfig.ruby, exe, "generate", kind, name,
+          chdir: project
+        )
+
+        ok = status.exitstatus == 0
+        {
+          ok: ok,
+          kind: kind,
+          name: name,
+          output: stdout.to_s + stderr.to_s,
+          error: (ok ? nil : (stderr.to_s.strip.empty? ? "generate exited #{status.exitstatus}" : stderr.to_s.strip))
+        }.compact
       end
 
       # ── Live Docs (Live API RAG) ─────────────────────────────────

data/lib/tina4/mcp.rb

@@ -1015,11 +1015,104 @@ module Tina4
         migration.respond_to?(:status) ? migration.status : { "info" => "Migration status not available" }
       }, "List pending and completed migrations")
 
+      # migration_create — delegates to the SAME resolution-aware helper that
+      # backs `tina4ruby migrate:create` + `tina4ruby generate migration`, so the
+      # MCP tool emits the ADR-0063 `generate_v1_1` envelope (edit_hints[],
+      # next[], `-- tina4:edit` markers baked into the UP+DOWN files) alongside
+      # the pre-existing `{created}` contract. Duplicate-slug guard mirrors the
+      # PHP + Python MCPs: if a migration file for the same slug already lives
+      # under migrations/, refuse (the AI should edit the existing one instead
+      # of spawning a second migration for the same schema change).
       server.register_tool("migration_create", lambda { |description:|
-        migration = Tina4::Migration.new(nil)
-        filename = migration.create(description)
-        { "created" => filename }
-      }, "Create a new migration file")
+        require "fileutils"
+        require_relative "cli"
+
+        desc = (description || "").to_s
+        slug = desc.gsub(/[^a-z0-9]+/i, "_").downcase.gsub(/^_|_$/, "")
+
+        # Duplicate-slug guard — walks migrations/ and compares against the
+        # slugified basename (stripping the leading 14-digit timestamp + the
+        # .sql / .down.sql extension). Handles the "create_orders_table" vs
+        # "create_orders" equivalence PHP + Python already recognise.
+        mig_dir = File.join(Dir.pwd, "migrations")
+        if slug != "" && File.directory?(mig_dir)
+          existing = []
+          Dir.glob(File.join(mig_dir, "*.sql")).sort.each do |path|
+            base = File.basename(path)
+            after = base.sub(/\A\d{14}_/, "").sub(/\.(down\.)?sql\z/, "")
+            existing_slug = after.gsub(/[^a-z0-9]+/i, "_").downcase.gsub(/^_|_$/, "")
+            if existing_slug == slug ||
+               existing_slug == "#{slug}_table" ||
+               slug == "#{existing_slug}_table"
+              existing << path.sub("#{Dir.pwd}/", "")
+            end
+          end
+          unless existing.empty?
+            next {
+              "ok" => false,
+              "error" => "Migration for #{desc.inspect} already exists: #{existing.first}. " \
+                         "Edit it with file_patch / file_write instead of creating a duplicate.",
+              "existing" => existing
+            }
+          end
+        end
+
+        # Delegate through the SHARED resolution-aware helper (the same entry
+        # point cmd_migrate_create uses since 1f09a31), so the envelope shape
+        # here is byte-for-byte the same as `tina4ruby migrate:create <desc>
+        # --json`. Human-mode output is captured and discarded — the MCP tool
+        # returns structured JSON only.
+        cli = Tina4::CLI.new
+        # `reset_generate_timestamp!` and `run_resolution_aware_generator` are
+        # private-by-declaration in cli.rb (everything below `private` at
+        # cli.rb:175). They are the SHARED entry points cmd_generate +
+        # cmd_migrate_create use, so calling them through #send here is the
+        # deliberate re-use path — not a boundary crossing.
+        cli.send(:reset_generate_timestamp!)
+
+        name = slug
+
+        require "stringio"
+        old_stdout = $stdout
+        old_stderr = $stderr
+        stdout_buf = StringIO.new
+        stderr_buf = StringIO.new
+        envelope = nil
+        begin
+          $stdout = stdout_buf
+          $stderr = stderr_buf
+          # json_mode: true → run_resolution_aware_generator prints the
+          # envelope to stdout (captured here); dry_run: false → the migration
+          # files are really written under migrations/ in Dir.pwd.
+          cli.send(
+            :run_resolution_aware_generator,
+            "migration", name, {},
+            json_mode: true,
+            dry_run: false,
+            gen_spec: Tina4::CLI::GENERATORS["migration"],
+            generator_kwargs: { emit_test: false, description: desc }
+          )
+          envelope = JSON.parse(stdout_buf.string)
+        ensure
+          $stdout = old_stdout
+          $stderr = old_stderr
+        end
+
+        # actions_taken carries "wrote migrations/<ts>_<name>.sql" lines; the
+        # first .sql (never .down.sql) is the canonical `created` filename that
+        # earlier callers of migration_create relied on.
+        actions = envelope["actions_taken"] || []
+        created = actions.map { |a| a.to_s.sub(/\Awrote\s+/, "") }
+                         .find { |p| p.end_with?(".sql") && !p.end_with?(".down.sql") }
+        created ||= (envelope.dig("resolution", "file_path"))
+
+        {
+          "ok" => true,
+          "created" => created,
+          "resolution" => envelope["resolution"],
+          "actions_taken" => actions
+        }
+      }, "Create a new migration file (emits ADR-0063 resolution envelope)")
 
       server.register_tool("migration_run", lambda {
         db = Tina4.database

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.119"
+  VERSION = "3.13.121"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.119
+  version: 3.13.121
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-26 00:00:00.000000000 Z
+date: 2026-08-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack