ruact 0.0.7 → 0.0.8

data/spec/ruact/server_bucket_request_spec.rb

@@ -138,6 +138,47 @@ module ServerBucketSpecSupport
       post.valid?
       ruact_errors(post)
     end
+
+    # Story 15.0 (F6) — the injection-BYPASS case the dev warning targets:
+    # registers errors, then renders explicitly on the same branch, so
+    # `default_render` never runs and the errors vanish from the JSON body.
+    def opt_out_render
+      post = ServerBucketSpecSupport::ValidatedPost.new(title: nil)
+      post.valid?
+      ruact_errors(post)
+      render json: { "ok" => false }
+    end
+
+    # Story 15.0 (F6 guardrail a) — the documented-correct Bucket-1 pattern:
+    # register errors, render the form page again (the template binds the
+    # `ruact_errors` reader). Requested WITHOUT the function-call Accept.
+    def failed_with_page_render
+      post = ServerBucketSpecSupport::ValidatedPost.new(title: nil)
+      post.valid?
+      ruact_errors(post)
+      render :new_form
+    end
+
+    # Story 15.0 (F6 guardrail b) — register errors, then redirect (the
+    # redirect-back round-trip). Correct on BOTH buckets, must never warn.
+    def failed_with_redirect
+      post = ServerBucketSpecSupport::ValidatedPost.new(title: nil)
+      post.valid?
+      ruact_errors(post)
+      redirect_to "/posts/new"
+    end
+
+    # Story 15.0 (F6 guardrail d) — explicit render with an UNTOUCHED collector.
+    def untouched_explicit_render
+      render json: { "ok" => true }
+    end
+
+    # Story 15.5 (FR109) — a plain Rails action on a `Ruact::Server` controller:
+    # a GET that renders plain text, so it is neither a function call nor a ruact
+    # page render. The dev shape-log must stay SILENT on it (non-negotiated).
+    def plain_rails
+      render plain: "just rails"
+    end
   end
 
   # Review round 2 — an auth-style before_action that redirects on a Bucket-2
@@ -211,6 +252,15 @@ ControllerRequestSpecSupport.write_view(
   ERB
 )
 
+# Story 15.0 (F6 guardrail a) — the re-rendered form page for the documented
+# Bucket-1 `ruact_errors(record); render :new_form` pattern. No component tags
+# on purpose (the guardrail is about the warn predicate, not the pipeline).
+ControllerRequestSpecSupport.write_view(
+  "server_bucket_spec_support/bucket_server", "new_form", <<~ERB
+    <div>the form again</div>
+  ERB
+)
+
 if defined?(ControllerRequestSpecSupport) &&
    !ControllerRequestSpecSupport.instance_variable_get(:@__ruact_server_bucket_routes_appended)
   ControllerRequestSpecSupport.instance_variable_set(:@__ruact_server_bucket_routes_appended, true)
@@ -227,6 +277,15 @@ if defined?(ControllerRequestSpecSupport) &&
     post "/bucket/validated_create_invalid", to: "server_bucket_spec_support/bucket_server#validated_create_invalid"
     post "/bucket/validated_create_valid",   to: "server_bucket_spec_support/bucket_server#validated_create_valid"
     post "/bucket/stray_errors_ivar", to: "server_bucket_spec_support/bucket_server#stray_errors_ivar"
+    # Story 15.0 (F6) — the warning truth-table routes.
+    post "/bucket/opt_out_render", to: "server_bucket_spec_support/bucket_server#opt_out_render"
+    post "/bucket/failed_with_page_render",
+         to: "server_bucket_spec_support/bucket_server#failed_with_page_render"
+    post "/bucket/failed_with_redirect", to: "server_bucket_spec_support/bucket_server#failed_with_redirect"
+    post "/bucket/untouched_explicit_render",
+         to: "server_bucket_spec_support/bucket_server#untouched_explicit_render"
+    # Story 15.5 (FR109) — a plain Rails GET on a Server controller (non-negotiated).
+    get  "/bucket/plain_rails", to: "server_bucket_spec_support/bucket_server#plain_rails"
     post "/bucket/dual_redirecting", to: "server_bucket_spec_support/bucket_dual#redirecting"
     post "/bucket/protected", to: "server_bucket_spec_support/bucket_forgery#create_protected"
     get  "/bucket/csrf_token", to: "server_bucket_spec_support/bucket_forgery#csrf_token"
@@ -472,6 +531,124 @@ RSpec.describe "Story 9.2: Ruact::Server dual-bucket response negotiation", :sto
     # NON-raised 200 path above; the two contracts stay distinct.
   end
 
+  # Story 15.0 (F6) — the dev-mode injection opt-out warning truth table.
+  # Fires ONLY on: development + function-call request + touched collector +
+  # explicit host render. Silent on every documented-correct pattern.
+  describe "Story 15.0: dev-mode ruact_errors injection opt-out warning (F6)", :story_15_0 do
+    # The distinctive fragment of the F6 message (deliberately distinct from
+    # any other `[ruact]` log line, incl. the future 15.5 bucket log).
+    let(:warning_re) { /\[ruact\] .*called `ruact_errors` and then rendered explicitly/ }
+    let(:html_form_headers) do
+      { "CONTENT_TYPE" => "application/x-www-form-urlencoded", "HTTP_ACCEPT" => "text/html" }
+    end
+
+    before do
+      allow(Rails.logger).to receive(:warn)
+    end
+
+    # NOTE: the suite's default Rails.env is "development" (RAILS_ENV unset),
+    # so the dev examples stub it EXPLICITLY anyway (they must not depend on
+    # the suite default) and the non-dev example stubs a non-dev env.
+    def stub_env(name)
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new(name))
+    end
+
+    def stub_development_env
+      stub_env("development")
+    end
+
+    it "warns exactly once on an explicit render after ruact_errors on a function-call request" do
+      stub_development_env
+      post "/bucket/opt_out_render", "{}", json_headers
+
+      expect(Rails.logger).to have_received(:warn).with(
+        a_string_matching(/\[ruact\] .*BucketServerController#opt_out_render.*ruact_errors.*NOT.*injected/m)
+      ).once
+    end
+
+    it "names the fix in the message (fall through, page-render binding, or redirect)" do
+      stub_development_env
+      post "/bucket/opt_out_render", "{}", json_headers
+
+      expect(Rails.logger).to have_received(:warn).with(
+        a_string_matching(/fall.*through.*errors=\{ruact_errors\}.*redirect_to/m)
+      )
+    end
+
+    it "keeps the response byte-identical whether the warning fires or not (log-only)" do
+      stub_env("production")
+      post "/bucket/opt_out_render", "{}", json_headers
+      silent_status = last_response.status
+      silent_body   = last_response.body
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+
+      stub_development_env
+      post "/bucket/opt_out_render", "{}", json_headers
+
+      expect(Rails.logger).to have_received(:warn).with(a_string_matching(warning_re))
+      expect(last_response.status).to eq(silent_status)
+      expect(last_response.body).to eq(silent_body)
+      expect(JSON.parse(last_response.body)).to eq("ok" => false)
+    end
+
+    it "guardrail (a): silent on the documented Bucket-1 `ruact_errors(record); render :new` pattern" do
+      stub_development_env
+      post "/bucket/failed_with_page_render", "post[title]=", html_form_headers
+
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to include("the form again")
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+
+    it "guardrail (b): silent on `ruact_errors(record); redirect_to` on a function-call request" do
+      stub_development_env
+      post "/bucket/failed_with_redirect", "{}", json_headers
+
+      expect(JSON.parse(last_response.body)).to eq("$redirect" => "/posts/new")
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+
+    it "guardrail (b): silent on `ruact_errors(record); redirect_to` on a Bucket-1 request" do
+      stub_development_env
+      post "/bucket/failed_with_redirect", "post[title]=", html_form_headers
+
+      expect(last_response.status).to eq(302)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+
+    it "guardrail (c): silent on the fall-through itself (errors were injected)" do
+      stub_development_env
+      post "/bucket/validated_create_invalid", "{}", json_headers
+
+      expect(JSON.parse(last_response.body).fetch("errors")).to eq("title" => ["Title can't be blank"])
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+
+    it "guardrail (d): silent on an explicit render when the collector was never touched" do
+      stub_development_env
+      post "/bucket/untouched_explicit_render", "{}", json_headers
+
+      expect(JSON.parse(last_response.body)).to eq("ok" => true)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+
+    it "never warns outside development (the bypass case in the test env stays silent)" do
+      stub_env("test")
+      post "/bucket/opt_out_render", "{}", json_headers
+
+      expect(last_response.status).to eq(200)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+
+    it "never warns in production either" do
+      stub_env("production")
+      post "/bucket/opt_out_render", "{}", json_headers
+
+      expect(last_response.status).to eq(200)
+      expect(Rails.logger).not_to have_received(:warn).with(a_string_matching(warning_re))
+    end
+  end
+
   # Story 10.0 (AC5) — the Server-path inherits the default_render graceful
   # degradation fix. A GET is never a function call, so Server#default_render
   # delegates to super → the fixed Controller#default_render.
@@ -491,4 +668,118 @@ RSpec.describe "Story 9.2: Ruact::Server dual-bucket response negotiation", :sto
       expect(last_response.headers["Content-Type"]).to include("text/x-component")
     end
   end
+
+  # Story 15.5 (FR109) — the dev-mode response-shape legibility log. One
+  # `[ruact]` line per ruact-NEGOTIATED request naming the chosen bucket + the
+  # deciding signal. Log-only (byte-identical), dev-gated, SILENT on
+  # non-negotiated (plain Rails) responses. Mirrors the F6 warning test shape.
+  describe "Story 15.5: dev-mode response-shape log (FR109)", :story_15_5 do
+    # The distinctive fragment of the 15.5 log — deliberately distinct from the
+    # F6 warning line (which matches `called \`ruact_errors\` and then rendered`).
+    let(:shape_log_re) { /\[ruact\] .* — .* → / }
+    let(:flight_headers)   { { "HTTP_ACCEPT" => "text/x-component" } }
+    let(:html_get_headers) { { "HTTP_ACCEPT" => "*/*" } }
+
+    before do
+      # The suite default env is development (RAILS_ENV unset); dev examples
+      # still stub it explicitly so they never depend on the suite default.
+      allow(Rails.logger).to receive(:info)
+    end
+
+    def stub_env(name)
+      allow(Rails).to receive(:env).and_return(ActiveSupport::StringInquirer.new(name))
+    end
+
+    def stub_development_env
+      stub_env("development")
+    end
+
+    it "logs the function-call JSON bucket once with the deciding signal (AC2)" do
+      stub_development_env
+      post "/bucket/with_ivars", "{}", json_headers
+
+      expect(Rails.logger).to have_received(:info).with(
+        "[ruact] ServerBucketSpecSupport::BucketServerController#with_ivars — " \
+        "Accept: application/json + POST → function-call JSON"
+      ).once
+    end
+
+    it "names the 204 (no ivars) sub-shape" do
+      stub_development_env
+      post "/bucket/empty", "{}", json_headers
+
+      expect(last_response.status).to eq(204)
+      expect(Rails.logger).to have_received(:info).with(
+        a_string_matching(%r{#empty_action — Accept: application/json \+ POST → function-call JSON \(204, no ivars\)})
+      ).once
+    end
+
+    it "names the $redirect sub-shape" do
+      stub_development_env
+      post "/bucket/redirecting", "{}", json_headers
+
+      expect(JSON.parse(last_response.body)).to eq("$redirect" => "/posts/1")
+      expect(Rails.logger).to have_received(:info).with(
+        a_string_matching(%r{#redirecting — Accept: application/json \+ POST → function-call \$redirect})
+      ).once
+    end
+
+    it "logs the Flight-page bucket on a text/x-component page render (AC2)" do
+      stub_development_env
+      get "/server-implicit/show", {}, flight_headers
+
+      expect(last_response.headers["Content-Type"]).to include("text/x-component")
+      expect(Rails.logger).to have_received(:info).with(
+        "[ruact] ServerBucketSpecSupport::ServerImplicitController#show — " \
+        "Accept: text/x-component → Flight page"
+      ).once
+    end
+
+    it "logs the HTML-shell bucket on an HTML-acceptable page GET (AC2)" do
+      stub_development_env
+      get "/server-implicit/show", {}, html_get_headers
+
+      expect(last_response.headers["Content-Type"]).to include("text/html")
+      expect(Rails.logger).to have_received(:info).with(
+        "[ruact] ServerBucketSpecSupport::ServerImplicitController#show — " \
+        "HTML-acceptable Accept, no Flight header → HTML shell"
+      ).once
+    end
+
+    it "is SILENT on a plain Rails action on the same controller (non-negotiated, AC2)" do
+      stub_development_env
+      get "/bucket/plain_rails"
+
+      expect(last_response.status).to eq(200)
+      expect(last_response.body).to eq("just rails")
+      expect(Rails.logger).not_to have_received(:info).with(a_string_matching(shape_log_re))
+    end
+
+    it "is SILENT outside development and byte-identical to the dev response (log-only, AC2)",
+       :aggregate_failures do
+      stub_env("production")
+      post "/bucket/with_ivars", "{}", json_headers
+      prod_status = last_response.status
+      prod_body   = last_response.body
+      prod_ctype  = last_response.headers["Content-Type"]
+      prod_vary   = last_response.headers["Vary"]
+      expect(Rails.logger).not_to have_received(:info).with(a_string_matching(shape_log_re))
+
+      stub_development_env
+      post "/bucket/with_ivars", "{}", json_headers
+      expect(Rails.logger).to have_received(:info).with(a_string_matching(shape_log_re))
+      expect(last_response.status).to eq(prod_status)
+      expect(last_response.body).to eq(prod_body)
+      expect(last_response.headers["Content-Type"]).to eq(prod_ctype)
+      expect(last_response.headers["Vary"]).to eq(prod_vary)
+    end
+
+    it "never logs in the test environment either" do
+      stub_env("test")
+      post "/bucket/with_ivars", "{}", json_headers
+
+      expect(last_response.status).to eq(200)
+      expect(Rails.logger).not_to have_received(:info).with(a_string_matching(shape_log_re))
+    end
+  end
 end

data/spec/ruact/server_functions/introspection_spec.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "active_support/all"
+require "action_dispatch"
+require "ruact/server_functions"
+
+module Ruact
+  module ServerFunctions
+    # Plain query class — only `instance_method(...).parameters` (kwargs) and
+    # `.name` (collision origin) are read; no Rails boot needed. Defined at module
+    # level (mirrors query_source_spec) so it is not an example-group-leaky
+    # constant.
+    class CatalogIntrospectQ
+      def categories; end
+
+      def search_users(term:, limit: 10); end
+    end
+
+    # Story 15.3 (FR107) — `ruact:routes --json` introspection. Exercised through
+    # a REAL RouteSet carrying both a mutation action and mounted query routes,
+    # with the host/query resolvers injected (no controller boot), so the document
+    # is proven byte-derived from RouteSource + QuerySource (the same single
+    # source of truth codegen consumes) and side-effect-free.
+    RSpec.describe Introspection, :story_15_3 do
+      let(:query_prefix) { QuerySource::QUERY_CONTROLLER_PREFIX }
+
+      # A real RouteSet with a mutation action (createPost, updatePost) AND two
+      # mounted query GET routes under the query dispatch controller prefix.
+      def combined_route_set
+        prefix = query_prefix
+        rs = ActionDispatch::Routing::RouteSet.new
+        rs.draw do
+          resources :posts, only: %i[create update]
+          get "/q/categories", to: "#{prefix}catalog_introspect_q#categories"
+          get "/q/search_users", to: "#{prefix}catalog_introspect_q#search_users"
+        end
+        rs
+      end
+
+      def as_json(route_set)
+        described_class.as_json(
+          route_set: route_set,
+          host_predicate: ->(_controller) { true },
+          query_class_for: lambda { |controller|
+            controller.start_with?(query_prefix) ? CatalogIntrospectQ : nil
+          }
+        )
+      end
+
+      describe ".as_json" do
+        subject(:document) { as_json(combined_route_set) }
+
+        it "gates the document with the EXPERIMENTAL schema_version (0)", :aggregate_failures do
+          expect(document["schema_version"]).to eq(0)
+          expect(document["schema_version"]).to eq(described_class::SCHEMA_VERSION)
+        end
+
+        it "round-trips through JSON.parse" do
+          expect(JSON.parse(JSON.generate(document))).to eq(document)
+        end
+
+        it "reports BOTH action and query accessors sorted by name", :aggregate_failures do
+          names = document["accessors"].map { |a| a["accessor"] }
+          expect(names).to include("createPost", "updatePost", "categories", "searchUsers")
+          expect(names).to eq(names.sort)
+        end
+
+        it "shapes an action with its required path segments as declared params", :aggregate_failures do
+          update = document["accessors"].find { |a| a["accessor"] == "updatePost" }
+          expect(update["kind"]).to eq("action")
+          expect(update["verb"]).to eq("PATCH")
+          expect(update["path"]).to eq("/posts/:id")
+          expect(update["segments"]).to eq(["id"])
+          expect(update["params"]).to eq([{ "name" => "id", "required" => true }])
+        end
+
+        it "shapes a query with its declared kwargs as params (Story 13.4)", :aggregate_failures do
+          search = document["accessors"].find { |a| a["accessor"] == "searchUsers" }
+          expect(search["kind"]).to eq("query")
+          expect(search["verb"]).to eq("GET")
+          expect(search["path"]).to eq("/q/search_users")
+          expect(search["segments"]).to eq([])
+          expect(search["params"]).to eq(
+            [{ "name" => "term", "required" => true }, { "name" => "limit", "required" => false }]
+          )
+        end
+
+        it "carries exactly the AC2 keys per accessor" do
+          document["accessors"].each do |accessor|
+            expect(accessor.keys).to contain_exactly("accessor", "kind", "verb", "path", "segments", "params")
+          end
+        end
+
+        it "does NOT include a per-accessor component-contract link (D3 = report accessors faithfully)" do
+          document["accessors"].each do |accessor|
+            expect(accessor).not_to have_key("contract")
+            expect(accessor).not_to have_key("has_contract")
+            expect(accessor).not_to have_key("contract_exists")
+          end
+        end
+      end
+
+      describe "side-effect-free (AC2 / AC4d — writes NO bridge or TS)" do
+        it "never writes the codegen bridge / TS module", :aggregate_failures do
+          allow(SnapshotWriter).to receive(:write_if_changed!)
+          allow(Snapshot).to receive(:generate_v2!)
+          allow(Codegen).to receive(:generate_ts!)
+          allow(File).to receive(:write).and_call_original
+
+          as_json(combined_route_set)
+
+          expect(SnapshotWriter).not_to have_received(:write_if_changed!)
+          expect(Snapshot).not_to have_received(:generate_v2!)
+          expect(Codegen).not_to have_received(:generate_ts!)
+          expect(File).not_to have_received(:write)
+        end
+      end
+
+      describe "single source of truth (AC2)" do
+        it "is byte-derived from ServerFunctions.introspect (same collectors as codegen)" do
+          # Both introspection and write_v2_snapshot! flow through .introspect;
+          # the document's accessors mirror those entries' identifiers exactly.
+          entries = ServerFunctions.introspect(
+            route_set: combined_route_set,
+            host_predicate: ->(_c) { true },
+            query_class_for: ->(c) { c.start_with?(query_prefix) ? CatalogIntrospectQ : nil }
+          )
+          expect(as_json(combined_route_set)["accessors"].map { |a| a["accessor"] })
+            .to eq(entries.map { |e| e["js_identifier"] })
+        end
+      end
+    end
+  end
+end

data/spec/ruact/tasks_json_introspection_spec.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "rake"
+require "json"
+require "tmpdir"
+require "action_controller"
+require "ruact/server"
+require "ruact/doctor"
+require "ruact/server_functions"
+
+# Story 15.3 (FR107) — end-to-end coverage of the `--json` Rake glue itself:
+# the `-- --json` ARGV scan, JSON-only stdout (no human prose), and — for
+# `ruact:doctor` — the preserved process exit code (0 pass/warn, 1 on fail).
+# The `Doctor#as_json` / `Introspection.as_json` shapes are unit-tested
+# elsewhere; THIS proves the task wiring around them (Codex R1, Acceptance
+# Auditor). Mirrors the isolated-Rake harness in
+# spec/ruact/server_functions/rake_spec.rb.
+module Ruact
+  RSpec.describe "rake --json introspection tasks", :story_15_3 do
+    around do |example|
+      Dir.mktmpdir do |dir|
+        original_root = Rails.root
+        Rails.root = Pathname.new(dir)
+
+        prev = Rake.application
+        Rake.application = Rake::Application.new
+        Rake.application.define_task(Rake::Task, :environment)
+        load File.expand_path("../../lib/tasks/ruact.rake", __dir__)
+
+        example.run
+      ensure
+        Rake.application = prev
+        Rails.root = original_root
+      end
+    end
+
+    def invoke!(task_name)
+      Rake::Task[task_name].reenable
+      Rake::Task[task_name].invoke
+    end
+
+    # ---- ruact:doctor -- --json (AC1: JSON-only stdout + preserved exit) ----
+
+    describe "ruact:doctor -- --json" do
+      before { stub_const("ARGV", %w[ruact:doctor -- --json]) }
+
+      def stub_doctor(status:)
+        report = {
+          "schema_version" => 0,
+          "status" => status,
+          "checks" => [{ "name" => "manifest", "status" => status, "message" => "m", "remediation" => nil }]
+        }
+        allow(Ruact::Doctor).to receive(:new).and_return(instance_double(Ruact::Doctor, as_json: report))
+      end
+
+      it "prints ONLY the JSON document (no prose) and does not exit when all pass", :aggregate_failures do
+        stub_doctor(status: "pass")
+
+        out = nil
+        expect { out = capture_stdout_string { invoke!("ruact:doctor") } }.not_to raise_error
+        parsed = JSON.parse(out)
+        expect(parsed["schema_version"]).to eq(0)
+        expect(parsed["status"]).to eq("pass")
+        expect(out).not_to include("[ruact] Health check")
+        expect(out).not_to include("Run rails generate")
+      end
+
+      it "exits 1 (SystemExit) when a check fails, still emitting the JSON", :aggregate_failures do
+        stub_doctor(status: "fail")
+
+        expect do
+          expect { invoke!("ruact:doctor") }.to raise_error(SystemExit) { |e| expect(e.status).to eq(1) }
+        end.to output(/"status": "fail"/).to_stdout
+      end
+    end
+
+    it "ruact:doctor WITHOUT --json runs the human path (no JSON), returns 0 when healthy" do
+      stub_const("ARGV", %w[ruact:doctor])
+      allow(Ruact::Doctor).to receive(:run).and_return(true)
+
+      expect { expect { invoke!("ruact:doctor") }.not_to raise_error }.not_to output(/schema_version/).to_stdout
+      expect(Ruact::Doctor).to have_received(:run)
+    end
+
+    # ---- ruact:routes (AC2: JSON via -- --json, human table bare) ----
+
+    describe "ruact:routes" do
+      before do
+        stub_const("RakeRoutesPostsController", Class.new(ActionController::Base) { include Ruact::Server })
+        reloader = Object.new
+        def reloader.execute_unless_loaded; end
+        rs = ActionDispatch::Routing::RouteSet.new
+        rs.draw { resources :rake_routes_posts, only: %i[create] }
+        app = Object.new
+        app.define_singleton_method(:routes) { rs }
+        app.define_singleton_method(:routes_reloader) { reloader }
+        allow(Rails).to receive(:application).and_return(app)
+      end
+
+      it "emits the EXPERIMENTAL JSON document under -- --json (end-to-end, real resolvers)", :aggregate_failures do
+        stub_const("ARGV", %w[ruact:routes -- --json])
+
+        out = capture_stdout_string { invoke!("ruact:routes") }
+        parsed = JSON.parse(out)
+        expect(parsed["schema_version"]).to eq(0)
+        create = parsed["accessors"].find { |a| a["accessor"] == "createRakeRoutesPost" }
+        expect(create).to include("kind" => "action", "verb" => "POST", "path" => "/rake_routes_posts")
+      end
+
+      it "prints a compact human table (no JSON) when invoked bare", :aggregate_failures do
+        stub_const("ARGV", %w[ruact:routes])
+
+        out = capture_stdout_string { invoke!("ruact:routes") }
+        expect(out).to include("server-function accessors:")
+        expect(out).to include("createRakeRoutesPost")
+        expect(out).not_to include("schema_version")
+      end
+
+      it "exits 1 with a `[ruact] error:` line on a naming collision" do
+        stub_const("ARGV", %w[ruact:routes -- --json])
+        allow(Ruact::ServerFunctions).to receive(:introspect)
+          .and_raise(Ruact::ConfigurationError, "server-function naming collision: A#x and B#x ...")
+
+        expect { invoke!("ruact:routes") }
+          .to raise_error(SystemExit)
+          .and output(/\[ruact\] error:.*naming collision/).to_stderr
+      end
+    end
+
+    # Captures $stdout into a String (the harness has no shared helper).
+    def capture_stdout_string
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+      $stdout.string
+    ensure
+      $stdout = original
+    end
+  end
+end