ruact 0.0.7 → 0.0.8

data/spec/ruact/install_generator_spec.rb

@@ -359,6 +359,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
             gen.create_server_functions_directory
             gen.append_gitignore_entries
             gen.create_vite_config
+            gen.create_agents_md
           end.not_to raise_error
         end
 
@@ -371,6 +372,7 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
         expect(File.read(File.join(app_root, ".gitignore")))
           .to include("app/javascript/.ruact/server-functions.ts")
         expect(File).to exist(File.join(app_root, "vite.config.js"))
+        expect(File).to exist(File.join(app_root, "AGENTS.md"))
       end
     end
   end
@@ -889,4 +891,287 @@ RSpec.describe Ruact do # rubocop:disable RSpec/SpecFilePathFormat
       end
     end
   end
+
+  # Story 15.1 (FR105) — `ruact:install` emits an AGENTS.md teaching coding
+  # agents the ruact conventions, traps, and verification commands. The ruact
+  # content is delimited by explicit markers so re-runs are idempotent, a
+  # user-authored AGENTS.md is appended to (never clobbered), and --force
+  # refreshes ONLY the marked section. Content assertions grep stable tokens
+  # (commands, file paths, API names) — never full-file snapshots, since later
+  # stories (15.2/15.3/15.4) deliberately evolve the prose.
+  describe "install generator — AGENTS.md emission (Story 15.1 — FR105)", :story_15_1 do
+    require "stringio"
+    require "generators/ruact/install/install_generator"
+
+    let(:app_root) { Dir.mktmpdir("ruact_install_1501") }
+    let(:agents_md_path) { File.join(app_root, "AGENTS.md") }
+    let(:begin_marker) { "<!-- ruact:begin -->" }
+    let(:end_marker) { "<!-- ruact:end -->" }
+    let(:template_path) do
+      File.expand_path("../../lib/generators/ruact/install/templates/AGENTS.md.tt", __dir__)
+    end
+
+    after { FileUtils.rm_rf(app_root) }
+
+    def build_generator(root, opts = {})
+      Ruact::Generators::InstallGenerator.new([], opts, destination_root: root)
+    end
+
+    def silently
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+    ensure
+      $stdout = original
+    end
+
+    # Captures and returns the generator's say/say_status stdout for text asserts.
+    def capture_stdout
+      original = $stdout
+      $stdout = StringIO.new
+      yield
+      $stdout.string
+    ensure
+      $stdout = original
+    end
+
+    describe "fresh emission (AC#1)" do
+      it "creates AGENTS.md delimited by the ruact markers", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+
+        expect(File).to exist(agents_md_path)
+        content = File.read(agents_md_path)
+        expect(content).to start_with(begin_marker)
+        expect(content.rstrip).to end_with(end_marker)
+      end
+
+      it "covers the model, codegen, queries and verification areas", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        # The verb rule (mutations = non-GET routed actions on Ruact::Server)
+        expect(content).to include("Ruact::Server")
+        expect(content).to include("non-GET")
+        # Route-driven codegen: ground-truth file + regenerate command
+        expect(content).to include("app/javascript/.ruact/server-functions.ts")
+        expect(content).to include("bin/rails ruact:server_functions:generate")
+        # Queries (reads)
+        expect(content).to include("Ruact::Query")
+        expect(content).to include("app/queries/")
+        expect(content).to include("ruact_queries")
+        expect(content).to include("useQuery")
+        # Verification commands (the only two that exist today)
+        expect(content).to include("bin/rails ruact:doctor")
+        # Docs pointers
+        expect(content).to include("https://ruact.dev")
+        expect(content).to include("llms.txt")
+      end
+
+      it "covers the five traps and the safety areas", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        # Trap 1 — children unsupported / self-closing only
+        expect(content).to include("self-closing")
+        expect(content).to include("children")
+        # Trap 2 — Ruby (not JS) inside {} props
+        expect(content).to include("Ruby, not JavaScript")
+        # Trap 3 — Accept-header dual shape (exact application/json)
+        expect(content).to include("Accept")
+        expect(content).to include("application/json")
+        # Trap 4 — ruact_errors fall-through
+        expect(content).to include("ruact_errors")
+        expect(content).to include("fall-through")
+        # Trap 5 — name derivation from routes
+        expect(content).to include("createPost")
+        expect(content).to include("ruact_function_name")
+        # Serialization allowlist
+        expect(content).to include("ruact_props")
+        expect(content).to include("strict_serialization")
+        # SGID helpers (purpose + expiry required grain)
+        expect(content).to include("Ruact.signed_global_id")
+        expect(content).to include("Ruact.locate_signed")
+      end
+
+      it "makes no claim before its artifact (AC#4 — content honesty)", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        # (The loud children `PreprocessorError` is Story 15.2's shipped
+        # artifact, and the `--json` introspection commands are Story 15.3's —
+        # both may now be claimed; see the `:story_15_2` / `:story_15_3` guards
+        # below that PIN each claim's presence. Story 15.4's public render
+        # helpers are now shipped too — see the `:story_15_4` guard below.)
+        #
+        # tsc does not run in a fresh install (no typescript devDep / tsconfig) —
+        # it may only appear conditionally phrased (D1).
+        expect(content).to match(/if your app has typescript tooling/i) if content.include?("tsc")
+        # Volatile strings must not be quoted: no gem version pins.
+        expect(content).not_to match(/\b0\.0\.\d+\b/)
+      end
+
+      # Story 15.2 (D2) — now that the loud children error is a shipped artifact,
+      # trap #1 truthfully claims it fails LOUDLY (was "fails silently" in 15.1).
+      it "trap #1 claims the loud PreprocessorError (Story 15.2 D2)", :aggregate_failures, :story_15_2 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to include("PreprocessorError")
+        expect(content).to match(/fail LOUDLY/i)
+        expect(content).not_to match(/fail silently/i)
+      end
+
+      # Story 15.3 (D2) — now that the `--json` introspection surface is a shipped
+      # artifact, the "Verify your work" section references it (relaxes the 15.1
+      # honesty guard above). This PINS the claim AND its EXPERIMENTAL framing so
+      # the template never presents the JSON shape as a stable contract.
+      it "references --json introspection as EXPERIMENTAL (15.3 D2)", :aggregate_failures, :story_15_3 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to include("ruact:routes -- --json")
+        expect(content).to include("ruact:doctor")
+        expect(content).to include("Append `-- --json`")
+        expect(content).to match(/EXPERIMENTAL/)
+        expect(content).to include("schema_version")
+      end
+
+      # Story 15.4 (D6) — now that the public render-assertion helpers are a
+      # shipped artifact (FR108), the "Verify your work" section references them.
+      # This PINS the claim (name + explicit require + the JSON-vs-Flight rule)
+      # so it stays consistent with `website/public/llms.txt`.
+      it "references the ruact/testing render helpers (15.4 D6)", :aggregate_failures, :story_15_4 do
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to include(%(require "ruact/testing"))
+        expect(content).to include("have_ruact_component")
+        expect(content).to include("JSON.parse(response.body)")
+      end
+    end
+
+    describe "idempotency (AC#2 — double-run zero diff)" do
+      it "leaves the file byte-identical on a second run and reports a skip", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        first = File.read(agents_md_path)
+
+        output = capture_stdout { build_generator(app_root).create_agents_md }
+
+        expect(File.read(agents_md_path)).to eq(first)
+        expect(output).to include("skip")
+      end
+    end
+
+    describe "append mode (AC#2 — user-authored AGENTS.md)" do
+      let(:user_content) { "# My app\n\nUse pnpm here. Never touch config/secrets.yml.\n" }
+
+      it "appends the marked section preserving every pre-existing user byte", :aggregate_failures do
+        File.write(agents_md_path, user_content)
+
+        silently { build_generator(app_root).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to start_with(user_content)
+        expect(content.scan(begin_marker).count).to eq(1)
+        expect(content.scan(end_marker).count).to eq(1)
+        expect(content).to include("\n\n#{begin_marker}")
+      end
+
+      it "blank-line separates the section when the user file lacks a trailing newline" do
+        File.write(agents_md_path, "# My app — no trailing newline")
+
+        silently { build_generator(app_root).create_agents_md }
+
+        expect(File.read(agents_md_path))
+          .to include("# My app — no trailing newline\n\n#{begin_marker}")
+      end
+
+      it "appending then re-running is idempotent (skip, zero diff)" do
+        File.write(agents_md_path, user_content)
+        silently { build_generator(app_root).create_agents_md }
+        appended = File.read(agents_md_path)
+
+        silently { build_generator(app_root).create_agents_md }
+
+        expect(File.read(agents_md_path)).to eq(appended)
+      end
+    end
+
+    describe "--force refresh (AC#2 — marked-block-only)" do
+      it "replaces ONLY the between-marker content, never user bytes outside", :aggregate_failures do
+        silently { build_generator(app_root).create_agents_md }
+        section = File.read(agents_md_path)
+        stale = section.sub("## Five traps", "## STALE CONTENT FROM AN OLDER GEM")
+        File.write(agents_md_path, "# mine, above\n\n#{stale}\n# mine, below\n")
+
+        silently { build_generator(app_root, { force: true }).create_agents_md }
+        content = File.read(agents_md_path)
+
+        expect(content).to start_with("# mine, above\n")
+        expect(content).to end_with("# mine, below\n")
+        expect(content).to include("## Five traps")
+        expect(content).not_to include("STALE CONTENT FROM AN OLDER GEM")
+        expect(content.scan(begin_marker).count).to eq(1)
+      end
+
+      it "creates the file under --force when none exists" do
+        silently { build_generator(app_root, { force: true }).create_agents_md }
+        expect(File.read(agents_md_path)).to include(begin_marker)
+      end
+    end
+
+    # Codex R1 — an incomplete marker state is ambiguous in BOTH directions
+    # (appending would duplicate content next to a stray marker; replacing
+    # would guess the range), so the only byte-safe move is warn + no-op.
+    describe "broken marker pair (byte-safety)" do
+      [
+        ["a begin marker without its end marker",
+         "# mine\n\n<!-- ruact:begin -->\ntruncated ruact section, no end marker\n"],
+        ["an end marker without its begin marker",
+         "# mine\n\nstray tail of a ruact section\n<!-- ruact:end -->\n"],
+        ["an end marker preceding the begin marker",
+         "# mine\n\n<!-- ruact:end -->\nreversed\n<!-- ruact:begin -->\n"],
+        # Codex R2 — a VALID pair plus stray extra markers is still ambiguous:
+        # skip/refresh would leave (or eat past) the unmatched marker.
+        ["a stray end marker before a valid pair",
+         "<!-- ruact:end -->\nstray\n\n<!-- ruact:begin -->\nsection\n<!-- ruact:end -->\n"],
+        ["a stray begin marker after a valid pair",
+         "<!-- ruact:begin -->\nsection\n<!-- ruact:end -->\n\nstray\n<!-- ruact:begin -->\n"],
+        ["two complete marker pairs",
+         "<!-- ruact:begin -->\none\n<!-- ruact:end -->\n\n<!-- ruact:begin -->\ntwo\n<!-- ruact:end -->\n"]
+      ].each do |(label, broken)|
+        it "warns and leaves the file untouched with #{label} (no --force)", :aggregate_failures do
+          File.write(agents_md_path, broken)
+
+          output = capture_stdout { build_generator(app_root).create_agents_md }
+
+          expect(File.read(agents_md_path)).to eq(broken)
+          expect(output).to include("warn")
+        end
+
+        it "warns and leaves the file untouched with #{label} (--force)", :aggregate_failures do
+          File.write(agents_md_path, broken)
+
+          output = capture_stdout { build_generator(app_root, { force: true }).create_agents_md }
+
+          expect(File.read(agents_md_path)).to eq(broken)
+          expect(output).to include("warn")
+        end
+      end
+    end
+
+    describe "action ordering + template budget" do
+      it "defines create_agents_md BEFORE install_javascript_dependencies" do
+        klass = Ruact::Generators::InstallGenerator
+        line = ->(name) { klass.instance_method(name).source_location.last }
+        expect(line.call(:create_agents_md)).to be < line.call(:install_javascript_dependencies)
+      end
+
+      # AC#3 tripwire — the ~150-line budget is the epic's scope probe; the
+      # tripwire's tolerance is 160 (the tripwire's, not the product contract's).
+      it "keeps the template body at or under 160 lines" do
+        expect(File.read(template_path).lines.count).to be <= 160
+      end
+    end
+  end
 end

data/spec/ruact/manifest_resolver_spec.rb

@@ -107,6 +107,21 @@ module Ruact
         expect { described_class.resolve }.to raise_error(ManifestError, %r{Vite dev server.*bin/dev}m)
       end
 
+      # Story 15.0 (F8) — an error message is a prompt: agents (and humans)
+      # regex-match error text, so the ENGLISH wording and its stable tokens
+      # (`Vite dev server`, `react-client-manifest.json`, `bin/dev`) are pinned.
+      it "raises the ENGLISH message naming the dev-server URL, the manifest path and the bin/dev fix " \
+         "(Story 15.0)", :story_15_0 do
+        allow(Net::HTTP).to receive(:start).and_raise(Errno::ECONNREFUSED)
+        allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")
+
+        expect { described_class.resolve }.to raise_error(ManifestError) do |error|
+          expect(error.message).to include("[ruact] Vite dev server unreachable at http://localhost:5173")
+          expect(error.message).to include("no react-client-manifest.json found at /no/such/manifest.json")
+          expect(error.message).to include("run `bin/dev`")
+        end
+      end
+
       it "ignores a non-2xx dev-server response and falls back" do
         allow(Net::HTTP).to receive(:start).and_return(Net::HTTPNotFound.new("1.1", "404", "Not Found"))
         allow(described_class).to receive(:file_path).and_return("/no/such/manifest.json")

data/spec/ruact/serializable_spec.rb

@@ -32,6 +32,132 @@ module Ruact
       end
     end
 
+    # Story 13.7 — `ruact_props` on ActiveRecord models.
+    #
+    # ActiveRecord defines its attribute reader methods LAZILY (on first
+    # instance access), so at the moment the `ruact_props :title` macro runs,
+    # `method_defined?(:title)` is `false` even for a real column. The eager
+    # boot check used to raise there, so an AR model that included
+    # `Ruact::Serializable` crashed at class-load. Story 13.7 makes the check
+    # HYBRID: POROs are still checked eagerly at class-load (byte-identical, see
+    # the block above), while for a lazy-attribute (AR) class the loud check is
+    # DEFERRED to the first `ruact_serialize` — where the DB is up and the reader
+    # exists. Loudness is preserved: a bogus prop still raises a clean
+    # `ArgumentError`, just at first render of that model instead of at boot.
+    #
+    # Zero suite-boot DB footprint: the connection + table are built INSIDE the
+    # example (direct connection DDL, NOT `Schema.define`, so we touch nothing
+    # global — no `schema_migrations` / `ar_internal_metadata`), and only a
+    # connection we ourselves opened is torn down.
+    describe "ActiveRecord models (Story 13.7)", :story_13_7 do
+      before do
+        require "active_record"
+        @already_connected =
+          ActiveRecord::Base.respond_to?(:connected?) && ActiveRecord::Base.connected?
+        ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:") unless @already_connected
+        ActiveRecord::Base.connection.create_table(:ruact_props_probe_posts, force: true) do |t|
+          t.string :title
+          t.string :secret
+        end
+      end
+
+      after do
+        if defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+          ActiveRecord::Base.connection.drop_table(:ruact_props_probe_posts, if_exists: true)
+        end
+        ActiveRecord::Base.remove_connection unless @already_connected
+      end
+
+      let(:ar_model) do
+        Class.new(ActiveRecord::Base) do
+          self.table_name = "ruact_props_probe_posts"
+          include Ruact::Serializable
+
+          ruact_props :id, :title
+        end
+      end
+
+      it "loads without raising even though readers are lazy at class-load (AC#1)" do
+        expect { ar_model }.not_to raise_error
+      end
+
+      it "ruact_serialize returns only the declared allowlist (AC#1)" do
+        row = ar_model.create!(title: "Hello", secret: "top-secret")
+
+        expect(row.ruact_serialize).to eq({ "id" => row.id, "title" => "Hello" })
+        expect(row.ruact_serialize.keys).not_to include("secret")
+      end
+
+      it "defers the loud check to first serialize for a bogus prop (AC#2)" do
+        model = nil
+
+        # Declaring a bogus prop on an AR model does NOT raise at class-load —
+        # the reader might still be defined lazily, so the check is deferred.
+        expect do
+          model = Class.new(ActiveRecord::Base) do
+            self.table_name = "ruact_props_probe_posts"
+            include Ruact::Serializable
+
+            ruact_props :ttile # typo — neither a column nor a method
+          end
+        end.not_to raise_error
+
+        # …but it fails LOUDLY (same clean ArgumentError) on first serialize.
+        expect { model.new.ruact_serialize }
+          .to raise_error(ArgumentError, /ttile.*not defined/)
+      end
+
+      it "re-validates loudly when props are re-declared after a first serialize (AC#2)" do
+        model = Class.new(ActiveRecord::Base) do
+          self.table_name = "ruact_props_probe_posts"
+          include Ruact::Serializable
+
+          ruact_props :id, :title
+        end
+
+        # First serialize succeeds and memoizes "validated"…
+        model.create!(title: "Hello").ruact_serialize
+
+        # …a re-declaration with a bogus prop must NOT be masked by the stale
+        # memo: the next serialize still raises the clean ArgumentError.
+        model.ruact_props :id, :ttile
+        expect { model.new.ruact_serialize }
+          .to raise_error(ArgumentError, /ttile.*not defined/)
+      end
+
+      it "re-validates an inherited declaration re-declared on the parent after a subclass serialize (AC#2)" do
+        parent = Class.new(ActiveRecord::Base) do
+          self.table_name = "ruact_props_probe_posts"
+          include Ruact::Serializable
+
+          ruact_props :id, :title
+        end
+        child = Class.new(parent)
+
+        # The subclass serializes first, memoizing the inherited (valid) list…
+        parent.create!(title: "Hello")
+        child.first.ruact_serialize
+
+        # …then the PARENT re-declares with a bogus prop. The subclass must not
+        # keep serving its stale memo: its next serialize re-validates loudly.
+        parent.ruact_props :id, :ttile
+        expect { child.first.ruact_serialize }
+          .to raise_error(ArgumentError, /ttile.*not defined/)
+      end
+
+      it "dispatches through serialize_serializable under strict true AND false (AC#4)" do
+        row = ar_model.create!(title: "Hello", secret: "top-secret")
+
+        [true, false].each do |strict|
+          output = Ruact::Flight::Renderer.render(
+            row, Ruact::ClientManifest.from_hash({}), strict_serialization: strict
+          )
+          expect(output).to include("Hello")
+          expect(output).not_to include("top-secret")
+        end
+      end
+    end
+
     describe "ruact_serialize (AC#1)" do
       it "returns only declared props" do
         obj = serializable_class.new