tina4ruby 3.13.120 → 3.13.121

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 95ef84b463d6357070f1f1261556d5d6dc44e7355d279ee987919789b2b11ca2
-  data.tar.gz: dd408c271fd30de5ccb6f17c16ff116f0882e39f7f60775d298570e48c201294
+  metadata.gz: 5432ec631264ef420f357f5b662a67ae7d8a22d8f32dfc719dc568e2713f0320
+  data.tar.gz: 0bfad1aff49e4b87548dc0d2ec13b27671295205189404252615810a245b89eb
 SHA512:
-  metadata.gz: e7a9dd4f5ecf64590747b052f67588194e4464d81dfe5f9455bb968132267951ed451915b6605d232688dd803c8deda7eb32f631fee4adb6672ca373acc8146e
-  data.tar.gz: 4431a908d43403601b76d82fb5bac6ad36948d532fce131847f14d0cbbc1c45f46a4b9785613cb5f3588553301f257eb42e6d5f68bd4b4473f7c24665d52dbde
+  metadata.gz: 8a2875da36ab669f4504833a97c65f85b0f37b48bd622ce692c92f567e3b65bf778950a80167b1e18df1e6617fa9bd4c39008f5efa5d0a6c624ef499789931d2
+  data.tar.gz: d090ea23d3fc4a07e1f0d249970e06300e76718464357ea815937136699b4da9daec59d4d37f425a9a0daa9e2e76698b3eea7d17ebfc6f24ebd1a8d77cb3a2d2

data/lib/tina4/cli.rb

@@ -292,14 +292,20 @@ module Tina4
     DEFAULT_FIELDS = [["name", "string"]].freeze
 
     # ADR-0063 (scaffolding envelope v1.1): `# tina4:edit <label>` in a generated
-    # Ruby file, or `-- tina4:edit <label>` in a generated SQL file, marks a
+    # 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. Any
-    # comment character (`#` or `--`) followed by `tina4:edit` and one or more
-    # spaces then the label matches — Twig `{# tina4:edit … #}` is Wave 2 and
-    # deliberately NOT matched here.
-    EDIT_MARKER_RE = /(?:#|--)\s*tina4:edit[ \t]+(.+?)\s*$/.freeze
+    # 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
@@ -354,8 +360,43 @@ module Tina4
           "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`)
@@ -692,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 ─────────────────────────────────────────────────────
@@ -1249,22 +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)
+      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
@@ -1277,7 +1375,7 @@ 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
 
@@ -1323,7 +1421,11 @@ module Tina4
     # `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.
-    def collect_edit_hints_via_sandbox(gen_spec, name, flags)
+    # `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
@@ -1337,7 +1439,7 @@ module Tina4
             # 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)
+            send(gen_spec[:handler], name, flags.dup, **generator_kwargs)
           rescue StandardError, LoadError, ScriptError
             # swallow - the sandbox is best-effort
           ensure
@@ -1370,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" => [],
@@ -1455,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",
@@ -1521,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
@@ -1823,7 +1978,8 @@ module Tina4
 
     # ── Generator: migration ─────────────────────────────────────────────
 
-    def generate_migration(name, flags = {}, fields_override: nil, table_override: nil, emit_test: true)
+    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.
@@ -1832,6 +1988,15 @@ module Tina4
       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
@@ -1880,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}
@@ -1893,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}

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.120"
+  VERSION = "3.13.121"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.120
+  version: 3.13.121
 platform: ruby
 authors:
 - Tina4 Team