whoosh 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3029bc3666ce5b81096d8248de52ac25f31e6cc11e271ad954058d9241bf48fb
-  data.tar.gz: 4a62476bf115c24635c2833ddf0814ec49de5b7e036a138e37f197ef8fb51905
+  metadata.gz: 7276060a2fd0b8ef3edc620c087767b92de6684e6ef54a130f5c3b45f5468a52
+  data.tar.gz: 98f9f219bbc2e01af9ba63803a525d100fcd70adf397248065db796b28319ae4
 SHA512:
-  metadata.gz: 1152664925e99cce8c668a87aa0e9e131bb48a59b4cb967569fa76224f4ae50ab00aa9658231eb9312ea640993cfb46f904bf9248200bf40a5f65df282a7ac71
-  data.tar.gz: 8c32d13d07cdfe9fdf8ff5ab201ba72632c054ee9ef60540a06f00dd4d0303755ddb7c22b0e6fad702003e0c3b088c69c062d606e1dee947f08f2330faf74285
+  metadata.gz: a12f5a8f431ff694382192e046072596beeaced996cf47e19633ea3974ebd7bae17bc079118b28cc08b019282219d0ff4cf263291eed418a38d2f32a4021d38a
+  data.tar.gz: 76c4e804ea925a037ecd60fcc02834800fb0d2ec000d9fdfb48a7a142625c32e37dd3f8bdbf56bae934f1a6ee46a3731a1f0db06cddac660630c4f14bdccd579

data/README.md

@@ -5,27 +5,38 @@
 <h1 align="center">Whoosh</h1>
 
 <p align="center">
-  <strong>AI-first Ruby API framework inspired by FastAPI</strong><br>
-  Schema validation, MCP, streaming, background jobs, and OpenAPI docs — out of the box.
+  <strong>The fastest way to ship a production MCP server in Ruby.</strong><br>
+  A FastAPI-style framework with MCP, schema validation, auth, streaming, and OpenAPI — built in.
 </p>
 
 <p align="center">
   <img src="https://img.shields.io/badge/ruby-%3E%3D%203.4.0-red" alt="Ruby">
   <img src="https://img.shields.io/badge/rack-3.0-blue" alt="Rack">
   <img src="https://img.shields.io/badge/license-MIT-green" alt="License">
-  <img src="https://img.shields.io/badge/tests-564%20passing-brightgreen" alt="Tests">
-  <img src="https://img.shields.io/badge/overhead-2.5%C2%B5s-orange" alt="Performance">
+  <img src="https://img.shields.io/badge/tests-659%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/stability-evolving-yellow" alt="Stability">
 </p>
 
 ---
 
 ## Why Whoosh?
 
-- **AI-first** — Every app is an MCP server automatically. LLM wrapper with structured output, caching, and streaming. Vector search built-in. 18+ AI gem auto-discovery.
-- **Fast** — 2.5µs framework overhead, 87K req/s with Falcon. Beats Fastify on multi-worker PostgreSQL benchmarks.
-- **Batteries included** — Auth, rate limiting, caching, background jobs, file uploads, vector search, pagination, metrics, CI pipeline.
-- **Zero config to start** — `whoosh new myapp && cd myapp && whoosh s` — everything works.
-- **AI-agent friendly** — `whoosh describe` dumps your app as JSON for AI tools. Generated `CLAUDE.md` in every project. `whoosh check` catches mistakes before runtime.
+- **MCP-native** — opt routes into MCP with `mcp: true` and they become typed tools over stdio/SSE. No glue code, no separate server.
+- **FastAPI-style DSL in Ruby** — declarative schemas, typed request/response, auto-generated OpenAPI + Swagger UI, dependency injection.
+- **Batteries included** — auth (JWT, API key, OAuth), rate limiting, caching, background jobs, file uploads, vector search, streaming, pagination.
+- **Agent-friendly** — `whoosh describe` emits a JSON snapshot of your app; generated `CLAUDE.md` so coding agents understand it; `whoosh check` validates config before runtime.
+- **Competitive Ruby performance** — YJIT + Falcon fibers + Oj, ~2.5µs framework overhead. See [Performance](#performance) for honest, per-core comparisons.
+
+## When NOT to use Whoosh
+
+Whoosh is on 1.x but still evolving — solo-maintained, without a production track record yet, and breaking changes ship occasionally (always called out in `CHANGELOG.md`). Reach for something else when:
+
+- **You need a managed backend.** Supabase, PocketBase, or Firebase give you DB + auth + realtime without hosting a framework. Whoosh is the app layer — use it *with* a managed DB if that fits.
+- **You want maximum ecosystem depth.** Rails has more gems; FastAPI has the Python ML/AI library ecosystem (PyTorch, transformers, LangChain). If your core workload lives in those libraries, stay where they are.
+- **You need a frozen API surface.** Being on 1.x doesn't mean the API is locked — breaking changes still ship when the design calls for it. If you need strict stability contracts today, wait a few releases.
+- **Your team has no Ruby experience** and the project isn't specifically about AI/MCP. Hiring and ecosystem gravity usually beat framework features.
+
+Whoosh's sweet spot: Ruby shops (or Ruby-curious teams) building AI / LLM / MCP-backed APIs who want typed schemas, OpenAPI, and MCP without wiring three libraries together.
 
 ## Install
 
@@ -192,21 +203,24 @@ end
 
 ### MCP (Model Context Protocol)
 
-**Every route is automatically an MCP tool.** No `mcp: true` needed.
+**Routes are exposed as MCP tools only when you opt in with `mcp: true`.** This prevents internal or admin endpoints from being callable as tools by accident.
 
 ```ruby
-# These are all MCP tools automatically:
-app.post "/summarize", request: SummarizeRequest do |req|
+# Opt in per route:
+app.post "/summarize", request: SummarizeRequest, mcp: true do |req|
   { summary: llm.summarize(req.body[:text]) }
 end
 
-app.post "/translate" do |req|
-  { result: translate(req.body["text"]) }
+# Or opt in a whole group:
+app.group "/tools", mcp: true do
+  post "/translate" do |req|
+    { result: translate(req.body["text"]) }
+  end
 end
 
-# Opt OUT with mcp: false for internal routes:
-app.get "/internal", mcp: false do
-  { debug: "not exposed as MCP tool" }
+# Default: not exposed as an MCP tool.
+app.get "/internal" do
+  { debug: "not exposed" }
 end
 ```
 
@@ -346,6 +360,43 @@ app.docs enabled: true, redoc: true
 - `/redoc` — ReDoc
 - `/openapi.json` — Machine-readable spec
 
+### Client Generator
+
+Generate complete, typed, ready-to-run client apps from your Whoosh API — one command.
+
+```sh
+whoosh generate client react_spa          # React + Vite + TypeScript
+whoosh generate client expo               # Expo + React Native
+whoosh generate client ios                # SwiftUI + MVVM
+whoosh generate client flutter            # Dart + Riverpod + GoRouter
+whoosh generate client htmx               # Plain HTML + htmx, no build step
+whoosh generate client telegram_bot       # Ruby Telegram bot
+whoosh generate client telegram_mini_app  # React + Telegram WebApp SDK
+
+whoosh generate client react_spa --oauth  # Add Google/GitHub/Apple login
+```
+
+The generator **introspects your Whoosh app** via OpenAPI — it reads your routes, schemas, and auth config, then produces a typed client with:
+
+- API client with auth headers and automatic token refresh
+- Model types matching your schemas
+- Auth screens (login, register, logout)
+- CRUD screens for every resource
+- Navigation and routing
+- Starter tests
+
+If no Whoosh app exists yet, it scaffolds a standard backend (JWT auth + tasks CRUD) alongside the client.
+
+| Client | Stack | Token Storage |
+|--------|-------|---------------|
+| `react_spa` | React 19, Vite, TypeScript, React Router | localStorage |
+| `expo` | Expo SDK 52, Expo Router, TypeScript | SecureStore |
+| `ios` | SwiftUI, async/await, MVVM | Keychain |
+| `flutter` | Dart, Dio, Riverpod, GoRouter | flutter_secure_storage |
+| `htmx` | HTML, htmx 2.x, vanilla JS | localStorage |
+| `telegram_bot` | Ruby, telegram-bot-ruby | In-memory session |
+| `telegram_mini_app` | React, Telegram WebApp SDK | Telegram initData |
+
 ### Health Checks
 
 ```ruby
@@ -377,6 +428,8 @@ whoosh generate model User name:string email:string
 whoosh generate migration add_email_to_users
 whoosh generate plugin my_tool      # plugin boilerplate
 whoosh generate proto ChatRequest   # .proto file
+whoosh generate client react_spa    # full client app (7 types)
+whoosh generate client expo --oauth # with OAuth2 social login
 
 whoosh db migrate             # run migrations
 whoosh db rollback            # rollback
@@ -401,55 +454,56 @@ whoosh check                 # validates config, auth, dependencies
 
 ## Performance
 
-### HTTP Benchmark: `GET /health → {"status":"ok"}`
+> Apple Silicon arm64, 12 cores. Ruby 3.4 + YJIT. [Full benchmark suite & reproduction steps](benchmarks/comparison/)
+>
+> **How to read these numbers.** Benchmarks are selective by nature. A `GET /health` returning `{"status":"ok"}` tests the router + serializer, not your real app. A Postgres read tests one query pattern. We show single-process (per-core) numbers first because that's the fair cross-language comparison. Multi-worker numbers are included for deployment sizing, but scaling strategies differ per runtime (Node uses `cluster`, Python uses multiple workers, Ruby uses workers × threads or fibers) and mixing them isn't apples-to-apples.
 
-> Apple Silicon arm64, 12 cores. [Full benchmark suite](benchmarks/comparison/)
+### HTTP micro-benchmark — `GET /health`
 
-**Single process** (fair 1:1 comparison):
+**Single process (per-core, fair comparison):**
 
 | Framework | Language | Server | Req/sec |
 |-----------|----------|--------|---------|
 | Fastify | Node.js 22 | built-in | 69,200 |
-| **Whoosh** | Ruby 3.4 +YJIT | **Falcon** | **24,400** |
+| **Whoosh** | Ruby 3.4 +YJIT | Falcon | **24,400** |
 | **Whoosh** | Ruby 3.4 +YJIT | Puma (5 threads) | **15,500** |
 | FastAPI | Python 3.13 | uvicorn | 8,900 |
 | Sinatra | Ruby 3.4 | Puma (5 threads) | 7,100 |
-| PHP (raw) | PHP 8.5 | built-in | 2,000 |
 
-> Whoosh + Falcon is **2.7x faster** than FastAPI single-core. Whoosh + Puma is **1.7x faster** than FastAPI. Use Falcon (recommended) for best performance.
+On this microbenchmark, Fastify is ~2.8× Whoosh+Falcon per-core; that's the honest picture for trivial JSON. Against other Ruby frameworks and against FastAPI on CPython, Whoosh is competitive.
 
-**Multi-worker** (production deployment):
+**Multi-worker (sizing reference, not apples-to-apples):**
 
-| Framework | Language | Server | Req/sec |
-|-----------|----------|--------|---------|
-| **Whoosh** | Ruby 3.4 +YJIT | **Falcon (4 workers)** | **87,400** |
-| Fastify | Node.js 22 | built-in (single thread) | 69,200 |
-| **Whoosh** | Ruby 3.4 +YJIT | Puma (4w×4t) | **52,500** |
-| Roda | Ruby 3.4 | Puma (4w×4t) | 14,700 |
+| Framework | Server | Req/sec |
+|-----------|--------|---------|
+| Whoosh | Falcon (4 workers) | 87,400 |
+| Fastify | built-in (single thread, no cluster) | 69,200 |
+| Whoosh | Puma (4w × 4t) | 52,500 |
+| Roda | Puma (4w × 4t) | 14,700 |
 
-> **Note:** Fastify is single-threaded by design (Node.js event loop). It can scale via `cluster` module but was not tested in that mode. Whoosh + Falcon with 4 workers uses 4 cores.
+Fastify was not run under `cluster`; don't read this table as "Whoosh beats Fastify." Read it as "Whoosh on 4 cores handles ~87K req/s on trivial JSON."
 
-### Real-World Benchmark: `GET /users/:id` from PostgreSQL (1000 rows)
+### Real-world benchmark — `GET /users/:id` from PostgreSQL (1000-row table)
 
-**Single process:**
+**Single process (per-core):**
 
-| Framework | Language | Req/sec |
-|-----------|----------|---------|
-| Fastify + pg | Node.js 22 | 36,900 |
-| **Whoosh + Falcon (fiber PG pool)** | Ruby 3.4 +YJIT | **13,400** |
-| **Whoosh + Puma (Sequel)** | Ruby 3.4 +YJIT | **8,600** |
-| Roda + Puma | Ruby 3.4 | 6,700 |
-| Sinatra + Puma | Ruby 3.4 | 4,400 |
-| FastAPI + uvicorn | Python 3.13 | 2,400 |
+| Framework | Req/sec |
+|-----------|---------|
+| Fastify + pg | 36,900 |
+| **Whoosh + Falcon (fiber PG pool)** | **13,400** |
+| Whoosh + Puma (Sequel) | 8,600 |
+| Roda + Puma | 6,700 |
+| Sinatra + Puma | 4,400 |
+| FastAPI + uvicorn | 2,400 |
 
-**Multi-worker (PostgreSQL):**
+On realistic DB-bound work, Whoosh's fiber-aware PG pool closes a lot of the gap vs Fastify (~2.75×) and has a wide lead over FastAPI on CPython and over other Ruby frameworks.
 
-| Framework | Language | Req/sec |
-|-----------|----------|---------|
-| **Whoosh + Falcon (4 workers, fiber PG pool)** | Ruby 3.4 +YJIT | **45,900** |
-| Fastify (single thread) | Node.js 22 | 36,900 |
+**Multi-worker (sizing reference):**
 
-> Whoosh + Falcon with fiber-aware PG pool is **5.6x faster** than FastAPI. Multi-worker Falcon **beats Fastify by 24%** on real PostgreSQL workloads.
+| Framework | Req/sec |
+|-----------|---------|
+| Whoosh + Falcon (4 workers, fiber PG pool) | 45,900 |
+| Fastify (single thread) | 36,900 |
 
 ### Micro-benchmarks
 

data/lib/whoosh/app.rb

@@ -493,8 +493,9 @@ module Whoosh
       internal_paths = %w[/openapi.json /docs /redoc /metrics /healthz]
 
       @router.routes.each do |route|
-        # Auto-expose all routes as MCP tools (opt-out with mcp: false)
-        next if route[:metadata] && route[:metadata][:mcp] == false
+        # Routes are exposed as MCP tools only when opted in with mcp: true.
+        # Why: default-expose leaks internal/admin endpoints as callable tools.
+        next unless route[:metadata] && route[:metadata][:mcp] == true
         next if internal_paths.include?(route[:path])
 
         tool_name = "#{route[:method]} #{route[:path]}"

data/lib/whoosh/cli/client_generator.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "whoosh/client_gen/ir"
+require "whoosh/client_gen/introspector"
+require "whoosh/client_gen/base_generator"
+require "whoosh/client_gen/dependency_checker"
+require "whoosh/client_gen/fallback_backend"
+
+module Whoosh
+  module ClientGen
+    class Error < StandardError; end
+  end
+
+  module CLI
+    class ClientGenerator
+      CLIENT_TYPES = %i[react_spa expo ios flutter htmx telegram_bot telegram_mini_app].freeze
+
+      attr_reader :type, :oauth, :output_dir
+
+      def self.client_types
+        CLIENT_TYPES
+      end
+
+      def initialize(type:, oauth:, dir:, root: Dir.pwd)
+        @type = type.to_sym
+        @oauth = oauth
+        @output_dir = dir || default_output_dir
+        @root = root
+      end
+
+      def run
+        validate!
+        check_dependencies!
+        result = introspect_or_fallback
+
+        case result[:mode]
+        when :introspected
+          display_found(result[:ir])
+          ir = confirm_selection(result[:ir])
+          generate_client(ir)
+        when :fallback
+          display_fallback_prompt
+          generate_fallback_backend
+          ir = build_fallback_ir
+          generate_client(ir)
+        end
+
+        display_success
+      end
+
+      def validate!
+        unless CLIENT_TYPES.include?(@type)
+          raise ClientGen::Error, "Unknown client type: #{@type}. Supported: #{CLIENT_TYPES.join(", ")}"
+        end
+      end
+
+      def default_output_dir
+        "clients/#{@type}"
+      end
+
+      def check_dependencies!
+        result = ClientGen::DependencyChecker.check(@type)
+        return if result[:ok]
+
+        puts "\n⚠️  Missing dependencies for #{@type}:"
+        result[:missing].each do |dep|
+          msg = "  - #{dep[:cmd]} (check: #{dep[:check]})"
+          msg += " — found v#{dep[:found_version]}, need v#{dep[:min_version]}+" if dep[:found_version]
+          puts msg
+        end
+        puts "\nInstall the missing dependencies and try again."
+        exit 1
+      end
+
+      def introspect_or_fallback
+        app = load_app
+        if app
+          introspector = ClientGen::Introspector.new(app, base_url: detect_base_url(app))
+          ir = introspector.introspect
+          if ir.has_resources? || ir.has_auth?
+            { mode: :introspected, ir: ir }
+          else
+            { mode: :fallback }
+          end
+        else
+          { mode: :fallback }
+        end
+      end
+
+      private
+
+      def load_app
+        app_file = File.join(@root, "app.rb")
+        return nil unless File.exist?(app_file)
+
+        require app_file
+        ObjectSpace.each_object(Whoosh::App).first
+      rescue => e
+        puts "⚠️  Failed to load app: #{e.message}"
+        puts "Run `whoosh check` to debug."
+        nil
+      end
+
+      def detect_base_url(app)
+        config = app.instance_variable_get(:@config)
+        port = config&.respond_to?(:port) ? config.port : 9292
+        host = config&.respond_to?(:host) ? config.host : "localhost"
+        "http://#{host}:#{port}"
+      end
+
+      def display_found(ir)
+        puts "\n🔍 Inspecting Whoosh app...\n\n"
+        puts "Found:"
+        puts "  Auth:       #{ir.auth&.type || "none"}"
+        ir.resources.each do |r|
+          puts "  Resource:   #{r.name} (#{r.endpoints.length} endpoints)"
+        end
+        ir.streaming.each do |s|
+          puts "  Streaming:  #{s[:type]} on #{s[:path]}"
+        end
+        puts
+      end
+
+      def confirm_selection(ir)
+        ir
+      end
+
+      def display_fallback_prompt
+        puts "\n⚠️  No Whoosh app found (or no routes defined).\n\n"
+        puts "Generating standard starter with:"
+        puts "  - JWT auth (email/password login + register)"
+        puts "  - Tasks CRUD (title, description, status, due_date)"
+        puts "  - Matching backend endpoints"
+        if @oauth
+          puts "  - OAuth2 (Google, GitHub, Apple)"
+        end
+        puts
+      end
+
+      def generate_fallback_backend
+        ClientGen::FallbackBackend.generate(root: @root, oauth: @oauth)
+        puts "✅ Backend endpoints generated"
+      end
+
+      def build_fallback_ir
+        ClientGen::IR::AppSpec.new(
+          auth: ClientGen::IR::Auth.new(
+            type: :jwt,
+            endpoints: {
+              login: { method: :post, path: "/auth/login" },
+              register: { method: :post, path: "/auth/register" },
+              refresh: { method: :post, path: "/auth/refresh" },
+              logout: { method: :delete, path: "/auth/logout" },
+              me: { method: :get, path: "/auth/me" }
+            },
+            oauth_providers: @oauth ? %i[google github apple] : []
+          ),
+          resources: [
+            ClientGen::IR::Resource.new(
+              name: :tasks,
+              endpoints: [
+                ClientGen::IR::Endpoint.new(method: :get, path: "/tasks", action: :index, pagination: true),
+                ClientGen::IR::Endpoint.new(method: :get, path: "/tasks/:id", action: :show),
+                ClientGen::IR::Endpoint.new(method: :post, path: "/tasks", action: :create),
+                ClientGen::IR::Endpoint.new(method: :put, path: "/tasks/:id", action: :update),
+                ClientGen::IR::Endpoint.new(method: :delete, path: "/tasks/:id", action: :destroy)
+              ],
+              fields: [
+                { name: :title, type: :string, required: true },
+                { name: :description, type: :string, required: false },
+                { name: :status, type: :string, required: false, enum: %w[pending in_progress done], default: "pending" },
+                { name: :due_date, type: :string, required: false }
+              ]
+            )
+          ],
+          streaming: [],
+          base_url: "http://localhost:9292"
+        )
+      end
+
+      def generate_client(ir)
+        generator_class = load_generator_class
+        output = File.join(@root, @output_dir)
+
+        if Dir.exist?(output) && !Dir.empty?(output)
+          puts "⚠️  #{@output_dir}/ already exists."
+          print "Overwrite? [y/N] "
+          answer = $stdin.gets&.strip&.downcase
+          unless answer == "y"
+            puts "Aborted."
+            exit 0
+          end
+          FileUtils.rm_rf(output)
+        end
+
+        generator_class.new(ir: ir, output_dir: output, platform: platform_for_type).generate
+      end
+
+      def load_generator_class
+        require "whoosh/client_gen/generators/#{@type}"
+        Whoosh::ClientGen::Generators.const_get(camelize(@type.to_s))
+      end
+
+      def platform_for_type
+        case @type
+        when :react_spa, :expo, :telegram_mini_app then :typescript
+        when :ios then :swift
+        when :flutter then :dart
+        when :htmx then :html
+        when :telegram_bot then :ruby
+        end
+      end
+
+      def camelize(str)
+        str.split("_").map(&:capitalize).join
+      end
+
+      def display_success
+        puts "\n✅ Generated #{@type} client in #{@output_dir}/"
+        case @type
+        when :react_spa, :telegram_mini_app
+          puts "   Run: cd #{@output_dir} && npm install && npm run dev"
+        when :expo
+          puts "   Run: cd #{@output_dir} && npm install && npx expo start"
+        when :ios
+          puts "   Run: open #{@output_dir}/WhooshApp.xcodeproj"
+        when :flutter
+          puts "   Run: cd #{@output_dir} && flutter pub get && flutter run"
+        when :htmx
+          puts "   Run: cd #{@output_dir} && open index.html (or any static server)"
+        when :telegram_bot
+          puts "   Run: cd #{@output_dir} && bundle install && ruby bot.rb"
+        end
+      end
+    end
+  end
+end

data/lib/whoosh/cli/main.rb

@@ -600,6 +600,16 @@ module Whoosh
           require "whoosh/cli/generators"
           Whoosh::CLI::Generators.proto(name)
         end
+
+        desc "client TYPE", "Generate a client app (react_spa, expo, ios, flutter, htmx, telegram_bot, telegram_mini_app)"
+        option :oauth, type: :boolean, default: false, desc: "Include OAuth2 social login"
+        option :dir, type: :string, desc: "Output directory (default: clients/<type>)"
+        def client(type)
+          require "whoosh/cli/client_generator"
+          Whoosh::CLI::ClientGenerator.new(
+            type: type, oauth: options[:oauth], dir: options[:dir]
+          ).run
+        end
       }
     end
   end

data/lib/whoosh/client_gen/base_generator.rb

@@ -0,0 +1,84 @@
+# lib/whoosh/client_gen/base_generator.rb
+# frozen_string_literal: true
+
+require "fileutils"
+require "whoosh/client_gen/ir"
+
+module Whoosh
+  module ClientGen
+    class BaseGenerator
+      TYPE_MAPS = {
+        typescript: {
+          string: "string", integer: "number", number: "number",
+          boolean: "boolean", array: "any[]", object: "Record<string, any>"
+        },
+        swift: {
+          string: "String", integer: "Int", number: "Double",
+          boolean: "Bool", array: "[Any]", object: "[String: Any]"
+        },
+        dart: {
+          string: "String", integer: "int", number: "double",
+          boolean: "bool", array: "List<dynamic>", object: "Map<String, dynamic>"
+        },
+        ruby: {
+          string: "String", integer: "Integer", number: "Float",
+          boolean: "Boolean", array: "Array", object: "Hash"
+        },
+        html: {
+          string: "text", integer: "number", number: "number",
+          boolean: "checkbox", array: "text", object: "text"
+        }
+      }.freeze
+
+      attr_reader :ir, :output_dir, :platform
+
+      def initialize(ir:, output_dir:, platform:)
+        @ir = ir
+        @output_dir = output_dir
+        @platform = platform
+      end
+
+      def generate
+        raise NotImplementedError, "Subclasses must implement #generate"
+      end
+
+      def type_for(ir_type)
+        TYPE_MAPS.dig(@platform, ir_type.to_sym) || "string"
+      end
+
+      def write_file(relative_path, content)
+        full_path = File.join(@output_dir, relative_path)
+        FileUtils.mkdir_p(File.dirname(full_path))
+        File.write(full_path, content)
+      end
+
+      def classify(name)
+        singular = singularize(name.to_s)
+        singular.split(/[-_]/).map(&:capitalize).join
+      end
+
+      def singularize(word)
+        w = word.to_s
+        if w.end_with?("ies")
+          w[0..-4] + "y"
+        elsif w.end_with?("ses") || w.end_with?("xes") || w.end_with?("zes") || w.end_with?("ches") || w.end_with?("shes")
+          w[0..-3]
+        elsif w.end_with?("sses")
+          w[0..-3]
+        elsif w.end_with?("s") && !w.end_with?("ss") && !w.end_with?("us")
+          w[0..-2]
+        else
+          w
+        end
+      end
+
+      def camelize(name)
+        name.to_s.split(/[-_]/).map(&:capitalize).join
+      end
+
+      def snake_case(name)
+        name.to_s.gsub(/([A-Z])/, '_\1').downcase.sub(/^_/, "")
+      end
+    end
+  end
+end

data/lib/whoosh/client_gen/dependency_checker.rb

@@ -0,0 +1,49 @@
+# lib/whoosh/client_gen/dependency_checker.rb
+# frozen_string_literal: true
+
+module Whoosh
+  module ClientGen
+    class DependencyChecker
+      DEPENDENCIES = {
+        react_spa: [{ cmd: "node", check: "node --version", min_version: "18" }],
+        expo: [
+          { cmd: "node", check: "node --version", min_version: "18" },
+          { cmd: "npx", check: "npx expo --version", min_version: nil }
+        ],
+        ios: [{ cmd: "xcodebuild", check: "xcodebuild -version", min_version: "15" }],
+        flutter: [{ cmd: "flutter", check: "flutter --version", min_version: "3" }],
+        htmx: [],
+        telegram_bot: [{ cmd: "ruby", check: "ruby --version", min_version: "3.2" }],
+        telegram_mini_app: [{ cmd: "node", check: "node --version", min_version: "18" }]
+      }.freeze
+
+      def self.check(client_type)
+        deps = DEPENDENCIES[client_type.to_sym] || []
+        return { ok: true, dependencies: [], missing: [] } if deps.empty?
+
+        missing = []
+        deps.each do |dep|
+          output = `#{dep[:check]} 2>/dev/null`.strip
+          if output.empty?
+            missing << dep
+          elsif dep[:min_version]
+            version = output.scan(/(\d+)\./)[0]&.first
+            if version && version.to_i < dep[:min_version].to_i
+              missing << dep.merge(found_version: version)
+            end
+          end
+        end
+
+        {
+          ok: missing.empty?,
+          dependencies: deps.map { |d| d[:cmd] },
+          missing: missing
+        }
+      end
+
+      def self.dependency_for(client_type)
+        DEPENDENCIES[client_type.to_sym] || []
+      end
+    end
+  end
+end