tina4ruby 3.13.145 → 3.13.147

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fdd61b88184de108dd6f4daefae312d7d26eab819ec084b88f5f257fce98167f
-  data.tar.gz: 336322ba4f2b6521d74af052391a0c1464310330935dd507c6a4ab2bfb5add11
+  metadata.gz: e9a60268ad13cea010f5fc994563e37b77d62c93bf73a67d075cd8086b4fa431
+  data.tar.gz: 740402d29d856535fe82468ce329ea754760a180f24436b22ae36f1d16fc25b8
 SHA512:
-  metadata.gz: e71cd5ffa73b75f87542f96e32fa4c503b38dacad2ea7444e381bd67ca94764be6a5c24f585e5cb1c4d4589b066303b02cef915effc1a8b8c92bd1b597176e6d
-  data.tar.gz: d0389a5a87a2911f7130647e12ee7f7b9c8476e75f8dcd824659d9f72c0099b640687a2a778f385ea322afb66dd8d62e435cd84467b788a9616868c1aa62d75d
+  metadata.gz: 0a63f77fa42d0b2dfb1ce82a6c600c0b83b3336a68826302e27179dd92eb0bb79d57f0d4b5c183b279178d0d600fbac33a4f97ae0a1c415cae09cab3e2eaa2c5
+  data.tar.gz: 6bbd112086e7b380d4a9748ae96192fba1721b17bd7b57cff1a682e60c062c308b817e5053ee3d1fb7293f1a27e9f448857a526f1d4fd7fe72889308bbf56643

data/CHANGELOG.md

@@ -6,6 +6,26 @@ 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.147 — 2026-10-05
+
+### Dev MCP tools (fixes #271)
+- `database_columns` reads schema metadata so an empty table returns its columns; a missing table returns a clear `table not found` error.
+- Tool argument validation returns an actionable `missing/unknown argument` error instead of a raw Ruby error; `api_method` now populates `params` and `return`.
+- `route_list` entries include each route's `middleware`.
+- A new route file added at runtime surfaces a signal.
+- Developer skill corrected: per-language hot-reload reality, and `api_method` shown with argument names.
+
+## 3.13.146 — 2026-10-04
+
+### AI skills
+- Every skill now opens with a content list (table of contents) and a degrees-of-freedom legend (what is inviolable, what is a default, what is judgement).
+- New `tina4-cli` skill documents every `tina4` command and flag and the scaffolding discipline.
+- `tina4-maintainer` gains task checklists (PR review, release, installer signing, parity sweep); `tina4-design` split into focused reference files.
+- Skills installer now supports one-level-nested references; `install-skills.ps1` re-signed.
+
+### Framework
+- No framework code changes - the version bump carries the skills release across all four frameworks at parity.
+
 ## 3.13.145 — 2026-10-03
 
 Two fixes land together. The Api client no longer carries an application-configured header onto a different origin: credentials travel under many names (`X-Api-Key`, a custom bearer header), so on a cross-origin redirect only content-negotiation and transport headers cross, and every configured or per-call header is bound to the origin it was meant for; a same-origin redirect keeps them. And `tina4ruby migrate` now exits 1 when there is no usable database (unreachable or misconfigured), so CI no longer reads a failed migration as success. Both are proven against real dependencies, no mocks. No runtime gems.

data/lib/tina4/docs.rb

@@ -432,6 +432,7 @@ module Tina4
           private_flag = visibility != "public" || underscored
 
           summary, doc = split_doc(pending_doc)
+          returns = pending_doc.join(" ")[/@return\s+\[([^\]]+)\]/, 1].to_s
           method_fqn = if is_static
             "#{current_class[:fqn]}.#{mname}"
           else
@@ -446,6 +447,7 @@ module Tina4
             class_fqn:   current_class[:fqn],
             class:       current_class[:fqn],
             signature:   signature,
+            returns:     returns,
             summary:     summary,
             docstring:   doc,
             file:        rel_file,
@@ -620,11 +622,54 @@ module Tina4
         static:     entry[:static] || false,
         source:     entry[:source],
         version:    entry[:version],
-        params:     [],
-        return:     "",
+        params:     params_from_signature(entry[:signature]),
+        return:     entry[:returns].to_s,
       }
     end
 
+    # Structured params parsed from a Ruby signature such as
+    # "fetch(sql, params = [], limit: 100, **opts)" -- same shape Python
+    # reports: [{name, type, required, default}]. Ruby has no inline type
+    # annotations, so type is "" unless the docblock says otherwise.
+    def params_from_signature(signature)
+      inner = signature.to_s[/\A[^(]*\((.*)\)\z/m, 1]
+      return [] if inner.nil? || inner.strip.empty?
+
+      split_top_level_commas(inner).map { |piece| param_entry(piece.strip) }
+    end
+
+    def param_entry(piece)
+      prefix = piece[/\A(\*\*|\*|&)/, 1]
+      return { name: piece, type: "", required: false, default: nil } if prefix
+
+      keyword = piece.match(/\A([A-Za-z_]\w*):\s*(.*)\z/m)
+      if keyword
+        default = keyword[2].strip
+        return { name: keyword[1], type: "", required: default.empty?, default: default.empty? ? nil : default }
+      end
+
+      name, default = piece.split(/\s*=\s*/, 2)
+      { name: name.strip, type: "", required: default.nil?, default: default&.strip }
+    end
+
+    def split_top_level_commas(text)
+      pieces = []
+      depth = 0
+      current = +""
+      text.each_char do |ch|
+        depth += 1 if "([{".include?(ch)
+        depth -= 1 if ")]}".include?(ch)
+        if ch == "," && depth.zero?
+          pieces << current
+          current = +""
+        else
+          current << ch
+        end
+      end
+      pieces << current unless current.strip.empty?
+      pieces
+    end
+
     # ── Sync writer ──────────────────────────────────────────────────
 
     def render_generated_block

data/lib/tina4/mcp.rb

@@ -139,6 +139,17 @@ module Tina4
     schema
   end
 
+  # Readable name for one attached route middleware (class, instance, string
+  # spec or lambda) -- what route_list reports under "middleware".
+  def self.middleware_label(attached)
+    case attached
+    when ::String then attached
+    when ::Module then attached.name || attached.inspect
+    when ::Proc, ::Method then "proc"
+    else attached.class.name || attached.inspect
+    end
+  end
+
   # Informational only — whether the CONFIGURED host looks local.
   #
   # NOT the security gate. This reads TINA4_HOST_NAME (the configured bind
@@ -510,22 +521,47 @@ module Tina4
       raise ArgumentError, "Unknown tool: #{tool_name}" if tool.nil?
 
       arguments = params.fetch("arguments", {})
+      arguments = {} if arguments.nil?
       handler   = tool["handler"]
 
+      # Validate against the tool's input schema BEFORE invoking, so a missing
+      # or unknown argument is an actionable message, never a raw Ruby
+      # ArgumentError. Python parity (tina4_python.mcp).
+      argument_error = validate_tool_arguments(tool_name, tool["inputSchema"], arguments)
+      return mcp_text_content(argument_error) if argument_error
+
       # Call the handler -- support both keyword and positional args
       result = _invoke_handler(handler, arguments)
 
-      # Format result as MCP content
-      content = case result
-                when String
-                  [{ "type" => "text", "text" => result }]
-                when Hash, Array
-                  [{ "type" => "text", "text" => JSON.pretty_generate(result) }]
-                else
-                  [{ "type" => "text", "text" => result.to_s }]
-                end
+      mcp_text_content(result)
+    end
+
+    # Format a tool result as MCP content.
+    def mcp_text_content(result)
+      text = case result
+             when String then result
+             when Hash, Array then JSON.pretty_generate(result)
+             else result.to_s
+             end
+      { "content" => [{ "type" => "text", "text" => text }] }
+    end
+
+    # Returns nil when the arguments satisfy the schema, else an
+    # { "error" => "missing required argument 'p' (tool takes p1, p2)" } hash
+    # (or "unknown argument ..." with the same shape).
+    def validate_tool_arguments(tool_name, schema, arguments)
+      return { "error" => "arguments for #{tool_name} must be an object" } unless arguments.is_a?(Hash)
 
-      { "content" => content }
+      properties = (schema || {}).fetch("properties", {}).keys
+      takes = "(#{tool_name} takes #{properties.join(', ')})"
+
+      missing = (schema || {}).fetch("required", []).find { |name| !arguments.key?(name) }
+      return { "error" => "missing required argument '#{missing}' #{takes}" } if missing
+
+      unknown = arguments.keys.map(&:to_s).find { |name| !properties.include?(name) }
+      return { "error" => "unknown argument '#{unknown}' #{takes}" } if unknown
+
+      nil
     end
 
     def _handle_resources_list(_params)
@@ -888,7 +924,13 @@ module Tina4
         unless table.to_s =~ /\A[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?\z/
           return { "error" => "Invalid table name" }
         end
-        db.columns(table)
+        # Schema metadata (PRAGMA / information_schema), never the first row, so
+        # an EMPTY table still reports its columns. A table that does not exist
+        # has no columns: say so rather than answering [].
+        columns = db.columns(table)
+        next { "error" => "table not found: #{table}" } if columns.nil? || columns.empty?
+
+        columns
       }, "Get column definitions for a table")
 
       # ── Route Tools ───────────────────────────────────
@@ -899,7 +941,8 @@ module Tina4
           {
             "method"        => route.method.to_s,
             "path"          => route.path.to_s,
-            "auth_required" => route.auth_required ? true : false
+            "auth_required" => route.auth_required ? true : false,
+            "middleware"    => route.middleware.map { |attached| Tina4.middleware_label(attached) }
           }
         end
       }, "List all registered routes")
@@ -1458,9 +1501,14 @@ module Tina4
         Tina4::Docs.cached(project_root).class_spec(name.to_s)
       }, "Full class reflection (methods, file, line) from the live API index")
 
-      server.register_tool("api_method", lambda { |class_name:, name:|
-        Tina4::Docs.cached(project_root).method_spec(class_name.to_s, name.to_s)
-      }, "Single method spec (signature, summary, file, line) from the live API index")
+      server.register_tool("api_method", lambda { |name:, **rest|
+        class_name = rest[:class].to_s
+        Tina4::Docs.cached(project_root).method_spec(class_name, name.to_s) ||
+          { "error" => "method not found: #{class_name}.#{name}" }
+      }, "Single method spec (signature, params, return, file, line) from the live API index",
+         { "type" => "object",
+           "properties" => { "class" => { "type" => "string" }, "name" => { "type" => "string" } },
+           "required" => %w[class name] })
 
       # ── Code/doc grounding (semantic FTS over this repo's source) ──
       # code_search is the fuzzy DUAL of the structural api_* tools:

data/lib/tina4/version.rb

@@ -7,5 +7,5 @@
 
 
 module Tina4
-  VERSION = "3.13.145"
+  VERSION = "3.13.147"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.145
+  version: 3.13.147
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-03 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sqlite3