tina4ruby 3.13.116 → 3.13.117

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f87f8715c8f265ae840f6f060d9d31be518c45120cd83881be55c9bfa54ddee
-  data.tar.gz: 1435132552d0d98a2feecd3da65e1674cc5dce8753f56661a20c2d955c7187c0
+  metadata.gz: 37edf07ae6df58c20f28ceae195925afd87d2cb2386264725aeadfc642606de0
+  data.tar.gz: 45a45a99a2147c18ac8d6eb40d46148e87ce759b14971d6137ac39c902dd04dc
 SHA512:
-  metadata.gz: a3dab7c63858f731fb06d8cd35a01497da574a528f32f602c2234a4ca43cfcd29612ed500a60d303d21f64bbaa3fa58e27622d921fb40cd4ca564ceccd8003d1
-  data.tar.gz: 40cc64acd13b62b74472aea5fcfe6557533ab61d1e6ba4d9c49d332882b388717966f54a475a0cc24e6d333def06da1f02abaa39b99ff0396ed0da180fbfd806
+  metadata.gz: 2b2c4307bd83d533ae01e29108170853168bf1829275a527c036c81d98dd06930a0db8d39291bb0b257c8902d25f38c8593892666392ab9073d94e868ccdfb93
+  data.tar.gz: 3f06a521e5904739120c5721b2419601308a5295dc53dba5180e6d24853c2f7f0fe33fbd29dc368eefc60fc815ac8f5d7a178d722b29bd8b22bdcc200b464522

data/CHANGELOG.md

@@ -6,6 +6,66 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.117
+
+Agent-experience release. Two paired features (import-hint fallback +
+generate-resolution transparency) attack the same defect class: the
+framework silently transforming input, then failing downstream with a
+message that never names the transformation. See ADR-0062.
+
+### Import-hint fallback (Tina4::Routr -> Tina4::Router)
+
+- New `lib/tina4/import_helper.rb`: two hooks in Ruby's namespace.
+  `Tina4.const_missing(name)` catches `Tina4::<Anything>` lookups
+  that Ruby could not resolve, walks `Tina4.constants` recursively
+  with `DidYouMean::SpellChecker` for the close match, raises
+  `NameError` with the suggestion. A `Kernel#require` wrap catches
+  `LoadError` for paths prefixed `tina4/`, walks `lib/tina4/*.rb`
+  for close matches, re-raises with the suggestion.
+- Bounded to the `Tina4::*` and `tina4/*` surfaces. Everything else
+  passes through untouched.
+- Installed from `lib/tina4.rb` at the end of the require chain.
+  Idempotent.
+- 8 real-subprocess spec examples cover positive-happy, negative-hint
+  (const + require), negative-no-match, masking-gate, and a live
+  mutation-gate example that stashes/restores the helper to prove
+  the hint text is genuinely dependent on the finder.
+
+### Generate-command resolution transparency
+
+- `tina4ruby generate model|route|migration|middleware --json` emits
+  a versioned envelope on stdout, matching the `generate_v1`
+  contract advertised in `commands --json`.
+- `--dry-run` computes resolution WITHOUT writing files. Composable
+  with `--json`.
+- Bare invocation prints a human-readable resolution block to stderr
+  naming every transformation, path and warning; files are written
+  as before.
+- Introduced `SQL_RESERVED_TABLE_NAMES` in `lib/tina4/cli.rb` mirroring
+  the Python master. `generate model Order` now surfaces the
+  "auto-pluralized" transformation and names the `--table X --quote`
+  override flag (parsed; the quoted-identifier ORM mode it opts into
+  is tracked at tina4-python#123 for a follow-up).
+- `commands --json` gains `"resolution_contract" => {"version" => "1",
+  "envelope" => "generate_v1"}`.
+- 6 real-subprocess spec examples covering json+dry_run,
+  reserved-word transformation, bare stderr, reserved-name stderr,
+  manifest advertisement.
+
+Side-fixes surfaced by the new reserved-word policy:
+
+- `generate crud/form/view` had a pre-existing `"#{table}s"` bug
+  that only appeared once reserved-word tables started pluralising
+  (Order -> orders -> orderss). Introduced `to_route_name` that
+  always pluralises from the class-name snake. `Category` was
+  ALREADY producing `categorys` (wrong); now correctly `categories`.
+- Detail-view path collision (`#{table}.twig` collided with the
+  list view for reserved-word classes; both `orders.twig`). Fixed
+  by keying detail on `to_snake_case(name)`.
+
+Parity: tina4-python, tina4-php, tina4-nodejs ship the same two
+features in 3.13.117 through their language-native mechanisms.
+
 ## 3.13.116
 
 Cooperative service-runner shutdown + version-contract test hardening.

data/lib/tina4/cli.rb

@@ -2,6 +2,8 @@
 
 require "optparse"
 require "fileutils"
+require "set"
+require "json"
 require_relative "port_takeover"
 
 module Tina4
@@ -228,9 +230,54 @@ module Tina4
           .downcase
     end
 
-    # Class name -> singular table name: Product -> product
+    # Table names that collide with SQL reserved words. `CREATE TABLE order (...)`
+    # is a syntax error on every engine, and the ORM interpolates table names
+    # into SQL unquoted (and hands the raw name to driver insert/update/delete),
+    # so the safe fix is to never GENERATE one. The plural form is not reserved
+    # and reads naturally as a table name. Mirrored from the Python master
+    # (tina4-python/tina4_python/cli/__init__.py:62-75) so a `generate model`
+    # in any framework picks the same table name for the same class.
+    SQL_RESERVED_TABLE_NAMES = %w[
+      order group user table select from where index
+      key values column constraint check default primary
+      foreign references unique join union having limit
+      offset desc asc case when then else end and
+      or not null insert update delete create drop
+      alter grant revoke commit rollback view trigger
+      procedure function database schema session set into
+      as on by inner outer left right full natural
+      using with distinct between exists like in is
+      all any cross add row rows range current to
+    ].to_set.freeze
+
+    # Simple English plural, used to escape a reserved table name.
+    # Mirrors `_pluralize_table` in tina4-python/tina4_python/cli/__init__.py:76.
+    def pluralize_table(name)
+      return "#{name[0..-2]}ies" if name.end_with?("y") &&
+                                    !name.end_with?("ay", "ey", "iy", "oy", "uy")
+      return "#{name}es"          if name.end_with?("s", "x", "z", "ch", "sh")
+
+      "#{name}s"
+    end
+
+    # Class name -> singular table name: Product -> product.
+    # A name colliding with a SQL reserved word is pluralised instead
+    # (Order -> orders). Every generator routes through here, so the model's
+    # `table_name`, the migration DDL, the routes and the tests all agree.
     def to_table_name(name)
-      to_snake_case(name)
+      table = to_snake_case(name)
+      SQL_RESERVED_TABLE_NAMES.include?(table) ? pluralize_table(table) : table
+    end
+
+    # Class name -> plural route/resource segment: Product -> products,
+    # Order -> orders, Category -> categories. Used by generate_crud /
+    # generate_form / generate_view for the URL path and the plural view
+    # filename. Naive `"#{table}s"` doubled the `s` when `table` was ALREADY
+    # plural from the reserved-word pluralize (Order -> orders -> orderss)
+    # and produced the wrong plural for `y`-ending / sibilant-ending names
+    # (Category -> categorys). This routes both through `pluralize_table`.
+    def to_route_name(name)
+      pluralize_table(to_snake_case(name))
     end
 
     # Called without --fields, the generators fall back to a single `name`
@@ -328,7 +375,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 once]
+      boolean_flags = %w[no-browser no-reload production managed all clear dev json public no-migration once dry-run]
 
       flags = {}
       positional = []
@@ -1060,6 +1107,14 @@ module Tina4
     end
 
     # ── generate ────────────────────────────────────────────────────────
+    #
+    # The generate command has two OUTPUT modes: human (default) and JSON
+    # (`--json`). A `--dry-run` short-circuits the file writes but still
+    # emits the resolution so a caller can PLAN a scaffold without touching
+    # the working tree. This is `resolution_contract.envelope = generate_v1`
+    # (see `commands_manifest`) — one machine-readable answer, per target,
+    # for AI agents that need to know exactly what a `generate model Order`
+    # will produce before it runs.
 
     def cmd_generate(argv)
       what = argv.shift
@@ -1071,6 +1126,8 @@ 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 '              --dry-run                 plan the scaffold; write no files'
         exit 1
       end
 
@@ -1086,16 +1143,204 @@ module Tina4
       name = no_name_generators.include?(what) ? "" : argv.shift
       flags, _positional = parse_flags(argv)
 
+      json_mode = flags.delete("json") ? true : false
+      dry_run   = flags.delete("dry-run") ? true : false
+
       # 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
+      unless gen_spec
         puts "Unknown generator: #{what}"
         puts "  Available: #{all}"
         exit 1
       end
+
+      # Only the four 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]
+      if !resolution_aware.include?(what)
+        send(gen_spec[:handler], name, flags)
+        return
+      end
+
+      resolution = build_generate_resolution(what, name, flags)
+
+      if json_mode
+        actions_taken = dry_run ? [] : run_generator_capturing_actions(gen_spec, name, flags)
+        envelope = build_generate_envelope(what, name, flags, resolution, actions_taken, dry_run)
+        puts JSON.pretty_generate(envelope)
+        return
+      end
+
+      # Human mode: print the resolution block to STDERR BEFORE writing files,
+      # so a caller can Ctrl-C between the plan and the write.
+      $stderr.puts format_generate_resolution_block(what, name, resolution)
+
+      if dry_run
+        $stderr.puts "  (dry-run — no files written)"
+      else
+        send(gen_spec[:handler], name, flags)
+      end
+    end
+
+    # ── generate resolution helpers ────────────────────────────────────────
+
+    # One `resolution` per target, with the SAME KEY SET so a caller can
+    # rely on the envelope shape regardless of what they generated:
+    #
+    #   class_name, table_name, file_path, migration_path,
+    #   transformations, routes, test_paths
+    #
+    # Fields that don't apply to a target (a middleware has no table_name;
+    # a migration is defined by its migration_path) are `nil` rather than
+    # missing — a stable envelope beats a compact one for machine callers.
+    def build_generate_resolution(target, name, flags)
+      case target
+      when "model"      then build_model_resolution(name, flags)
+      when "route"      then build_route_resolution(name, flags)
+      when "migration"  then build_migration_resolution(name, flags)
+      when "middleware" then build_middleware_resolution(name, flags)
+      else
+        { "class_name" => name.to_s, "table_name" => nil, "file_path" => nil,
+          "migration_path" => nil, "transformations" => [],
+          "routes" => [], "test_paths" => [] }
+      end
+    end
+
+    def build_model_resolution(name, flags)
+      raw = to_snake_case(name)
+      transformations = []
+      table =
+        if SQL_RESERVED_TABLE_NAMES.include?(raw)
+          plural = pluralize_table(raw)
+          transformations << {
+            "kind"     => "reserved_word_pluralize",
+            "from"     => raw,
+            "to"       => plural,
+            "reason"   => "SQL reserved word '#{raw}' would break CREATE TABLE",
+            "override" => "--table #{raw} --quote (requires quoted-identifier mode, not yet implemented)"
+          }
+          plural
+        else
+          raw
+        end
+      # 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")
+      {
+        "class_name"     => name.to_s,
+        "table_name"     => table,
+        "file_path"      => "src/orm/#{raw}.rb",
+        "migration_path" => "migrations/#{timestamp}_create_#{table}.sql",
+        "transformations" => transformations,
+        "routes"         => ["/#{table}", "/#{table}/{id}"],
+        "test_paths"     => ["spec/#{raw}_spec.rb"]
+      }
+    end
+
+    def build_route_resolution(name, flags)
+      route_path = name.to_s.sub(%r{^/}, "")
+      {
+        "class_name"      => nil,
+        "table_name"      => nil,
+        "file_path"       => "src/routes/#{route_path}.rb",
+        "migration_path"  => nil,
+        "transformations" => [],
+        "routes"          => ["/api/#{route_path}", "/api/#{route_path}/{id}"],
+        "test_paths"      => ["spec/routes/#{route_path}_spec.rb"]
+      }
+    end
+
+    def build_migration_resolution(name, _flags)
+      timestamp = Time.now.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"
+      {
+        "class_name"      => nil,
+        "table_name"      => snake_base,
+        "file_path"       => path,
+        "migration_path"  => path,
+        "transformations" => [],
+        "routes"          => [],
+        "test_paths"      => []
+      }
+    end
+
+    def build_middleware_resolution(name, _flags)
+      snake = to_snake_case(name)
+      {
+        "class_name"      => name.to_s,
+        "table_name"      => nil,
+        "file_path"       => "src/middleware/#{snake}.rb",
+        "migration_path"  => nil,
+        "transformations" => [],
+        "routes"          => [],
+        "test_paths"      => []
+      }
+    end
+
+    def build_generate_envelope(target, name, flags, resolution, actions_taken, dry_run)
+      {
+        "command"       => "generate",
+        "target"        => target,
+        "input"         => { "name" => name.to_s, "fields" => flags["fields"] },
+        "resolution"    => resolution,
+        "actions_taken" => actions_taken,
+        "dry_run"       => dry_run
+      }
+    end
+
+    # Human-readable resolution block emitted to STDERR before a bare
+    # `generate model Order` writes files. Only shows the "keep raw name"
+    # hint when a reserved-word pluralize actually fired.
+    def format_generate_resolution_block(target, name, resolution)
+      lines = ["Generated #{target} #{name}"]
+      if resolution["class_name"]
+        lines << "  class      #{resolution['class_name']}  (in #{resolution['file_path']})"
+      elsif resolution["file_path"]
+        lines << "  file       #{resolution['file_path']}"
+      end
+      if resolution["table_name"]
+        pluralized = resolution["transformations"].find { |t| t["kind"] == "reserved_word_pluralize" }
+        note = pluralized ? "  (auto-pluralized: '#{pluralized['from']}' is a SQL reserved word)" : ""
+        lines << "  table      #{resolution['table_name']}#{note}"
+      end
+      if resolution["routes"] && !resolution["routes"].empty?
+        lines << "  routes     #{resolution['routes'].join(', ')}"
+      end
+      if resolution["migration_path"] && resolution["migration_path"] != resolution["file_path"]
+        lines << "  migration  #{resolution['migration_path']}"
+      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
+      lines.join("\n")
+    end
+
+    # Run a generator with its usual stdout output CAPTURED, and derive an
+    # `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)
+      require "stringio"
+      require "json"
+      buffer = StringIO.new
+      original = $stdout
+      $stdout = buffer
+      begin
+        send(gen_spec[:handler], name, flags)
+      ensure
+        $stdout = original
+      end
+      buffer.string.each_line
+            .map(&:strip)
+            .select { |line| line.start_with?("Created ") }
+            .map { |line| "wrote #{line.sub(/^Created\s+/, '')}" }
     end
 
     # ── Generator: model ─────────────────────────────────────────────────
@@ -1348,7 +1593,11 @@ module Tina4
 
     def generate_crud(name, flags)
       table = to_table_name(name)
-      route_name = "#{table}s"
+      # Always derive the plural route from the CLASS NAME, not by appending
+      # "s" to the table — otherwise a reserved-word table (already plural,
+      # Order -> orders) becomes orderss, and a `y`-ending class (Category)
+      # becomes categorys instead of categories.
+      route_name = to_route_name(name)
       is_public = flags["public"] ? true : false
 
       puts "\n  Generating CRUD for #{name}...\n"
@@ -1649,7 +1898,7 @@ module Tina4
     def generate_form(name, flags = {})
       fields = fields_or_default(flags["fields"])
       table = to_table_name(name)
-      route_name = "#{table}s"
+      route_name = to_route_name(name)
 
       # Input type mapping
       input_types = {
@@ -1662,7 +1911,11 @@ module Tina4
 
       dir = "src/templates/forms"
       FileUtils.mkdir_p(dir)
-      path = File.join(dir, "#{table}.twig")
+      # Form template is for creating/editing ONE record, so the filename is
+      # keyed by the singular class snake (order.twig), never by the plural
+      # table (which for a reserved-word class Order would be orders.twig
+      # and read wrong for a form).
+      path = File.join(dir, "#{to_snake_case(name)}.twig")
       if File.exist?(path)
         puts "  File already exists: #{path}"
         return
@@ -1727,7 +1980,7 @@ module Tina4
     def generate_view(name, flags = {})
       fields = fields_or_default(flags["fields"])
       table = to_table_name(name)
-      route_name = "#{table}s"
+      route_name = to_route_name(name)
 
       cols = fields.map { |f, _| f }
 
@@ -1778,8 +2031,13 @@ module Tina4
         puts "  Created #{list_path}"
       end
 
-      # Detail view
-      detail_path = File.join(dir, "#{table}.twig")
+      # Detail view — file named by the singular CLASS NAME (snake_case), not
+      # the table name. When the class is a SQL reserved word the table has
+      # been pluralised (Order -> orders), and reusing that name would
+      # collide with the list view path just above. The class-name snake
+      # (order.twig) is the natural detail-page filename and matches the
+      # pre-reserved-word behaviour for every non-reserved class.
+      detail_path = File.join(dir, "#{to_snake_case(name)}.twig")
       unless File.exist?(detail_path)
         detail_fields = cols.map do |c|
           "    <div class=\"mb-3\"><strong>#{c.tr('_', ' ').split.map(&:capitalize).join(' ')}:</strong> {{ item.#{c} }}</div>"
@@ -2880,7 +3138,16 @@ module Tina4
         entry["args"] = spec[:args].dup if spec[:args]
         entry
       end
-      { "framework" => "ruby", "version" => Tina4::VERSION, "commands" => commands }
+      {
+        "framework" => "ruby",
+        "version"   => Tina4::VERSION,
+        "commands"  => commands,
+        # Contract for the `generate --json` envelope so a machine caller can
+        # 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" }
+      }
     end
 
     # Emit the CLI's own command surface — the self-describing manifest.

data/lib/tina4/import_helper.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# lib/tina4/import_helper.rb
+#
+# AI-agent experience: fail LOUD with an actionable hint when a wrong Tina4
+# import is guessed. Two bounded hooks, installed once at framework boot from
+# `lib/tina4.rb`:
+#
+#   1. `Tina4.const_missing(:Route)` -> "uninitialized constant Tina4::Route.
+#      Did you mean Tina4::Router?" (using stdlib DidYouMean; Levenshtein
+#      fallback if unavailable).
+#
+#   2. `require "tina4/route"` (unknown framework file) -> "cannot load such
+#      file -- tina4/route. Did you mean tina4/router?" — walks the real files
+#      that ship in `lib/tina4/*.rb` for close matches.
+#
+# BOTH hooks are BOUNDED: the constant hook only fires for `Tina4::*`, and the
+# require hook only intervenes when the requested path starts with `tina4/`
+# AND the resulting LoadError is about that exact path. Anything else passes
+# through unchanged — a genuinely missing gem must surface as its own real
+# error, not be masked by our hint (`spec/import_helper_spec.rb` locks that in
+# with the "broken_module" masking gate).
+#
+# The hint is a suggestion, never a truth claim: the raised class stays
+# NameError / LoadError, so callers who rescue those still work.
+
+module Tina4
+  module ImportHelper
+    # The directory that holds the real framework files (lib/tina4/*.rb).
+    # Computed from this file's own location so it survives being loaded from
+    # a gem install path, a git checkout, or a worktree alike.
+    FRAMEWORK_DIR = File.expand_path(__dir__).freeze
+
+    class << self
+      # Install both hooks. Idempotent: safe to call more than once (extra
+      # calls no-op). The framework boot in `lib/tina4.rb` calls this exactly
+      # once at the end of its own require chain.
+      def install
+        return if @installed
+
+        # Load DidYouMean once, quietly. It ships with Ruby 3.1+ (the
+        # framework's minimum), but never *fail* boot if it happens to be
+        # absent: the close_matches Levenshtein fallback covers that case.
+        begin
+          require "did_you_mean"
+        rescue LoadError
+          # fall through to the Levenshtein path in close_matches
+        end
+
+        Tina4.singleton_class.prepend(ConstMissing)
+        Kernel.prepend(RequireHook)
+        @installed = true
+      end
+
+      def installed?
+        @installed == true
+      end
+
+      # Return up to `max` close-match strings from `dictionary` for `word`.
+      # Uses stdlib DidYouMean::SpellChecker where available (Ruby 3.1+ ships
+      # it), and falls back to a small Levenshtein implementation otherwise.
+      #
+      # Never raises: an empty dictionary or a blank word returns [].
+      def close_matches(word, dictionary, max: 3)
+        list = Array(dictionary).map(&:to_s)
+        return [] if list.empty? || word.to_s.empty?
+
+        if defined?(DidYouMean::SpellChecker)
+          suggestions = DidYouMean::SpellChecker.new(dictionary: list).correct(word.to_s)
+          return suggestions.first(max) unless suggestions.nil? || suggestions.empty?
+        end
+
+        # Levenshtein fallback: rank by edit distance, keep the closest few
+        # within a reasonable threshold so a truly wrong guess still returns [].
+        scored = list.map { |candidate| [candidate, levenshtein(word.to_s, candidate)] }
+        threshold = [(word.to_s.length / 3.0).ceil, 3].max
+        scored.select { |_, distance| distance <= threshold }
+              .sort_by { |candidate, distance| [distance, candidate] }
+              .first(max)
+              .map(&:first)
+      end
+
+      # A short, ordered sample of real Tina4 constants — used when nothing
+      # was close enough to suggest, so the reader still leaves with something
+      # to try.
+      def some_tina4_constants(limit = 5)
+        Tina4.constants.map(&:to_s).sort.first(limit)
+      end
+
+      private
+
+      # Iterative two-row Levenshtein: O(a.length * b.length) time,
+      # O(b.length) space. Pure logic, no allocations of intermediate strings.
+      def levenshtein(a, b)
+        return b.length if a.empty?
+        return a.length if b.empty?
+
+        prev = (0..b.length).to_a
+        (1..a.length).each do |i|
+          curr = Array.new(b.length + 1, 0)
+          curr[0] = i
+          (1..b.length).each do |j|
+            cost = a[i - 1] == b[j - 1] ? 0 : 1
+            curr[j] = [
+              curr[j - 1] + 1,
+              prev[j] + 1,
+              prev[j - 1] + cost
+            ].min
+          end
+          prev = curr
+        end
+        prev[b.length]
+      end
+    end
+
+    # Hook 1 -- Tina4::<Missing>. Only fires when a bare `Tina4::<Name>`
+    # constant is asked for and does not exist. Ruby dispatches
+    # `const_missing` on the module itself (via its singleton class), so a
+    # prepended `ConstMissing#const_missing` runs first and re-raises with a
+    # helpful hint.
+    module ConstMissing
+      def const_missing(name)
+        real = Tina4.constants.map(&:to_s)
+        matches = Tina4::ImportHelper.close_matches(name.to_s, real)
+
+        message =
+          if matches.any?
+            "uninitialized constant Tina4::#{name}. Did you mean Tina4::#{matches.first}?"
+          else
+            examples = Tina4::ImportHelper.some_tina4_constants
+            hint =
+              if examples.any?
+                " Real Tina4 constants include: #{examples.map { |c| "Tina4::#{c}" }.join(', ')}."
+              else
+                ""
+              end
+            "uninitialized constant Tina4::#{name}.#{hint}"
+          end
+
+        # NameError.new(msg, name) records the missing constant symbol, so
+        # code doing `rescue NameError => e; e.name` still works.
+        raise NameError.new(message, name)
+      end
+    end
+
+    # Hook 2 -- require "tina4/<something>". Runs BEFORE the real
+    # Kernel#require via `Module#prepend`. On success, indistinguishable from
+    # plain require. On failure, only rewrites the LoadError when:
+    #
+    #   * the requested path starts with "tina4/", AND
+    #   * the LoadError's own #path is nil or equal to that requested path.
+    #
+    # The second condition is the masking gate: a nested `require
+    # "definitely_missing_gem"` inside a loaded tina4/*.rb raises a LoadError
+    # whose #path is that inner name — we MUST propagate it unchanged, not
+    # replace it with a spurious "did you mean tina4/router?" hint.
+    module RequireHook
+      def require(path)
+        super
+      rescue LoadError => e
+        raise unless path.is_a?(String) && path.start_with?("tina4/")
+
+        offending = e.respond_to?(:path) ? e.path : nil
+        raise unless offending.nil? || offending == path
+
+        base = path.sub(%r{\Atina4/}, "")
+        real = Dir.glob(File.join(Tina4::ImportHelper::FRAMEWORK_DIR, "*.rb"))
+                  .map { |file| File.basename(file, ".rb") }
+        matches = Tina4::ImportHelper.close_matches(base, real)
+
+        if matches.any?
+          suggestion = matches.first
+          raise LoadError, "cannot load such file -- #{path}. Did you mean tina4/#{suggestion}?"
+        else
+          raise LoadError, "cannot load such file -- #{path}. No close match under tina4/*."
+        end
+      end
+
+      # Preserve Kernel#require's private visibility: prepending a module that
+      # publicly defines `require` would otherwise leak `some_obj.require(...)`
+      # as a public method. Keep the surface identical.
+      private :require
+    end
+  end
+end

data/lib/tina4/version.rb

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

data/lib/tina4.rb

@@ -59,6 +59,12 @@ require_relative "tina4/context"
 require_relative "tina4/mcp"
 require_relative "tina4/realtime"
 
+# AI-agent experience: install the constant-lookup and require-path hint hooks
+# LAST, once every real Tina4::* constant and every lib/tina4/*.rb file is
+# discoverable. Idempotent — safe to load lib/tina4 more than once.
+require_relative "tina4/import_helper"
+Tina4::ImportHelper.install
+
 module Tina4
   # Bind address, with the framework name winning over the bare one.
   #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.116
+  version: 3.13.117
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-24 00:00:00.000000000 Z
+date: 2026-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -389,6 +389,7 @@ files:
 - lib/tina4/graphql.rb
 - lib/tina4/health.rb
 - lib/tina4/html_element.rb
+- lib/tina4/import_helper.rb
 - lib/tina4/job.rb
 - lib/tina4/localization.rb
 - lib/tina4/log.rb