tina4ruby 3.0.0 → 3.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47c53ad8cda483d0cde2eaec4072b5620de88dbd172d45fe9ab0df52a865c71e
-  data.tar.gz: 438bbf58dc14e8b7f91007cde01c53bc4326b4b088c8d39fac845189da9a2cf9
+  metadata.gz: c9e0a35ede3d5672d8d4b1c4197129db19443f60638e0596b1e94f367f9a40aa
+  data.tar.gz: 37d5d5d98b0511ac523eeec07d8b2ada21d5a47553bab176ccbce9a01a600389
 SHA512:
-  metadata.gz: ae5246539beea74da1618b9e498d6f6f1ea3949e26663ec862d79934c3acdb6ec7ba59cb49778444badcab81aaa5a42de3e8e2c02ed4717d3ba368f0701045a7
-  data.tar.gz: ddecbcd770270106b44733563e9c83f58e5b3084a0b190f3b5ea8041066f310cfec6017ee5e0fa03895c048a7a61100f9a8bca222a23825794726fdc7c1bebad
+  metadata.gz: 9f9f9b1240111c24ba20e461439c55c043792206f5b2150811f2c8d97b1e0e7e937d644777d4c2a06c59888b994f01aa8d54ebcffdad5dffcbdca159f3868fab
+  data.tar.gz: 581ac0b6d4b0493f0d787d53846d9c1811e9dab6515797ad693ecceec8e5b7401e92d08319b434c3729df0321b3399b8b73019e2b701d39664fa2f69c8baa20a

data/README.md

@@ -18,7 +18,7 @@
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/tests-1334%20passing-brightgreen" alt="Tests">
+  <img src="https://img.shields.io/badge/tests-1577%20passing-brightgreen" alt="Tests">
   <img src="https://img.shields.io/badge/carbonah-A%2B%20rated-00cc44" alt="Carbonah A+">
   <img src="https://img.shields.io/badge/zero--dep-core-blue" alt="Zero Dependencies">
   <img src="https://img.shields.io/badge/ruby-3.1%2B-blue" alt="Ruby 3.1+">
@@ -27,17 +27,53 @@
 
 ---
 
-## Quickstart
+## Quick Start
 
 ```bash
-gem install tina4ruby
-tina4ruby init my-app
-cd my-app
-tina4ruby serve
-# -> http://localhost:7147
+# Install the Tina4 CLI
+cargo install tina4  # or download binary from https://github.com/tina4stack/tina4/releases
+
+# Create a project
+tina4 init ruby ./my-app
+
+# Run it
+cd my-app && tina4 serve
+```
+
+Open http://localhost:7147 — your app is running.
+
+<details>
+<summary><strong>Without the Tina4 CLI</strong></summary>
+
+```bash
+# 1. Create project
+mkdir my-app && cd my-app
+echo 'source "https://rubygems.org"' > Gemfile
+echo 'gem "tina4-ruby", "~> 3.0"' >> Gemfile
+bundle install
+
+# 2. Create entry point
+cat > app.rb << 'EOF'
+require "tina4"
+Tina4.initialize!(__dir__)
+app = Tina4::RackApp.new
+Tina4::WebServer.new(app, host: "0.0.0.0", port: 7147).start
+EOF
+
+# 3. Create .env
+echo 'TINA4_DEBUG=true' > .env
+echo 'TINA4_LOG_LEVEL=ALL' >> .env
+
+# 4. Create route directory
+mkdir -p src/routes
+
+# 5. Run
+bundle exec ruby app.rb
 ```
 
-That's it. Zero configuration, zero classes, zero boilerplate.
+Open http://localhost:7147
+
+</details>
 
 ---
 
@@ -50,7 +86,7 @@ Every feature is built from scratch -- no gem install, no node_modules, no third
 | **HTTP** | Rack 3 server, block routing, path params (`{id:int}`, `{p:path}`), middleware pipeline, CORS, rate limiting, graceful shutdown |
 | **Templates** | Frond engine (Twig-compatible), inheritance, partials, 35+ filters, macros, fragment caching, sandboxing |
 | **ORM** | Active Record, typed fields with validation, soft delete, relationships (`has_one`/`has_many`/`belongs_to`), scopes, result caching, multi-database |
-| **Database** | SQLite, PostgreSQL, MySQL, MSSQL, Firebird -- unified adapter interface |
+| **Database** | SQLite, PostgreSQL, MySQL, MSSQL, Firebird -- unified adapter interface, query caching (TINA4_DB_CACHE=true for 4x speedup) |
 | **Auth** | Zero-dep JWT (RS256), sessions (file, Redis, MongoDB), password hashing, form tokens |
 | **API** | Swagger/OpenAPI auto-generation, GraphQL with ORM auto-schema and GraphiQL IDE |
 | **Background** | DB-backed queue with priority, delayed jobs, retry, batch processing, multi-queue |
@@ -58,9 +94,9 @@ Every feature is built from scratch -- no gem install, no node_modules, no third
 | **Frontend** | tina4-css (~24 KB), frond.js helper, SCSS compiler, live reload, CSS hot-reload |
 | **DX** | Dev admin dashboard, error overlay, request inspector, AI tool integration, Carbonah green benchmarks |
 | **Data** | Migrations with rollback, 50+ fake data generators, ORM and table seeders |
-| **Other** | REST client, localization (6 languages), in-memory cache (TTL/tags/LRU), event system, inline testing, configurable error pages |
+| **Other** | REST client, localization (6 languages), cache (memory/Redis/file), event system, inline testing, messenger (.env driven), configurable error pages |
 
-**676 tests across 28 modules. All Carbonah benchmarks rated A+.**
+**1,577 tests across 38 built-in features. Zero dependencies. All Carbonah benchmarks rated A+.**
 
 For full documentation visit **[tina4.com](https://tina4.com)**.
 
@@ -345,9 +381,9 @@ end
 ### JWT Authentication
 
 ```ruby
-auth = Tina4::Auth.new
-token = auth.get_token({ user_id: 42 })
-payload = auth.get_payload(token)
+token = Tina4::Auth.create_token({ user_id: 42 })
+result = Tina4::Auth.validate_token(token)
+payload = Tina4::Auth.get_payload(token)
 ```
 
 POST/PUT/PATCH/DELETE routes require `Authorization: Bearer <token>` by default. Use `auth: false` to make public, `secure_get` to protect GET routes.
@@ -486,7 +522,7 @@ cache.tag("users").flush
 
 ## Dev Mode
 
-Set `TINA4_DEBUG_LEVEL=DEBUG` in `.env` to enable:
+Set `TINA4_DEBUG=true` in `.env` to enable:
 
 - **Live reload** -- browser auto-refreshes on code changes
 - **CSS hot-reload** -- SCSS changes apply without page refresh
@@ -500,9 +536,14 @@ Set `TINA4_DEBUG_LEVEL=DEBUG` in `.env` to enable:
 ```bash
 tina4ruby init [dir]             # Scaffold a new project
 tina4ruby serve [port]           # Start dev server (default: 7147)
+tina4ruby serve --production     # Auto-install and use Puma production server
 tina4ruby migrate                # Run pending migrations
 tina4ruby migrate --create <desc># Create a migration file
 tina4ruby migrate --rollback     # Rollback last batch
+tina4ruby generate model <name>  # Generate ORM model scaffold
+tina4ruby generate route <name>  # Generate route scaffold
+tina4ruby generate migration <d> # Generate migration file
+tina4ruby generate middleware <n># Generate middleware scaffold
 tina4ruby seed                   # Run seeders from src/seeds/
 tina4ruby routes                 # List all registered routes
 tina4ruby test                   # Run test suite
@@ -510,6 +551,53 @@ tina4ruby build                  # Build distributable gem
 tina4ruby ai [--all]             # Detect AI tools and install context
 ```
 
+### Production Server Auto-Detection
+
+`tina4 serve` automatically detects and uses the best available production server:
+
+- **Ruby**: Puma (if installed), otherwise WEBrick -- Puma gives 2.8x improvement
+- Use `tina4ruby serve --production` to auto-install Puma
+
+### Scaffolding with `tina4 generate`
+
+Quickly scaffold new components:
+
+```bash
+tina4ruby generate model User          # Creates src/orm/user.rb with field stubs
+tina4ruby generate route users         # Creates src/routes/users.rb with CRUD stubs
+tina4ruby generate migration "add age" # Creates migration SQL file
+tina4ruby generate middleware AuthLog   # Creates middleware class
+```
+
+### ORM Relationships & Eager Loading
+
+```ruby
+# Relationships
+orders = user.has_many("Order", "user_id")
+profile = user.has_one("Profile", "user_id")
+customer = order.belongs_to("Customer", "customer_id")
+
+# Eager loading with include:
+users = User.all(include: ["orders", "profile"])
+```
+
+### DB Query Caching
+
+Enable query caching for up to 4x speedup on read-heavy workloads:
+
+```bash
+# .env
+TINA4_DB_CACHE=true
+```
+
+### Frond Pre-Compilation
+
+Templates are pre-compiled for 2.8x faster rendering.
+
+### Gallery
+
+7 interactive examples with **Try It** deploy.
+
 ## Environment
 
 ```bash
@@ -517,7 +605,8 @@ SECRET=your-jwt-secret
 DATABASE_URL=sqlite://data/app.db
 DATABASE_USERNAME=
 DATABASE_PASSWORD=
-TINA4_DEBUG_LEVEL=DEBUG              # DEBUG, INFO, WARNING, ERROR, ALL
+TINA4_DEBUG=true                     # Enable dev toolbar, error overlay
+TINA4_LOG_LEVEL=ALL                  # ALL, DEBUG, INFO, WARNING, ERROR
 TINA4_LANGUAGE=en                    # en, fr, af, zh, ja, es
 TINA4_SESSION_HANDLER=SessionFileHandler
 SWAGGER_TITLE=My API

data/lib/tina4/cli.rb

@@ -5,7 +5,7 @@ require "fileutils"
 
 module Tina4
   class CLI
-    COMMANDS = %w[init start migrate seed seed:create test version routes console ai help].freeze
+    COMMANDS = %w[init start migrate seed seed:create test version routes console generate ai help].freeze
 
     def self.start(argv)
       new.run(argv)
@@ -23,6 +23,7 @@ module Tina4
       when "version"    then cmd_version
       when "routes"     then cmd_routes
       when "console"    then cmd_console
+      when "generate"   then cmd_generate(argv)
       when "ai"         then cmd_ai(argv)
       when "help", "-h", "--help" then cmd_help
       else
@@ -97,37 +98,45 @@ module Tina4
 
       app = Tina4::RackApp.new(root_dir: root_dir)
 
+      is_debug = Tina4::Env.truthy?(ENV["TINA4_DEBUG"])
+
       # Try Puma first (production-grade), fall back to WEBrick
-      begin
-        require "puma"
-        require "puma/configuration"
-        require "puma/launcher"
-
-        puma_host = options[:host]
-        puma_port = options[:port]
-
-        config = Puma::Configuration.new do |user_config|
-          user_config.bind "tcp://#{puma_host}:#{puma_port}"
-          user_config.app app
-          user_config.threads 0, 16
-          user_config.workers 0
-          user_config.environment "development"
-          user_config.log_requests false
-          user_config.quiet
-        end
+      # In debug mode, always use WEBrick for dev toolbar/reload support
+      if !is_debug
+        begin
+          require "puma"
+          require "puma/configuration"
+          require "puma/launcher"
+
+          puma_host = options[:host]
+          puma_port = options[:port]
+
+          config = Puma::Configuration.new do |user_config|
+            user_config.bind "tcp://#{puma_host}:#{puma_port}"
+            user_config.app app
+            user_config.threads 0, 16
+            user_config.workers 0
+            user_config.environment "production"
+            user_config.log_requests false
+            user_config.quiet
+          end
 
-        Tina4::Log.info("Starting Puma server on http://#{puma_host}:#{puma_port}")
+          Tina4::Log.info("Production server: puma")
 
-        # Setup graceful shutdown (Puma manages its own signals, but we handle DB cleanup)
-        Tina4::Shutdown.setup
+          # Setup graceful shutdown (Puma manages its own signals, but we handle DB cleanup)
+          Tina4::Shutdown.setup
 
-        launcher = Puma::Launcher.new(config)
-        launcher.run
-      rescue LoadError
-        Tina4::Log.info("Puma not found, falling back to WEBrick")
-        server = Tina4::WebServer.new(app, host: options[:host], port: options[:port])
-        server.start
+          launcher = Puma::Launcher.new(config)
+          launcher.run
+          return
+        rescue LoadError
+          # Puma not installed, fall through to WEBrick
+        end
       end
+
+      Tina4::Log.info("Development server: WEBrick")
+      server = Tina4::WebServer.new(app, host: options[:host], port: options[:port])
+      server.start
     end
 
     # ── migrate ───────────────────────────────────────────────────────────
@@ -310,6 +319,123 @@ module Tina4
 
     # ── help ──────────────────────────────────────────────────────────────
 
+    # ── generate ────────────────────────────────────────────────────────
+
+    def cmd_generate(argv)
+      what = argv.shift
+      name = argv.shift
+      unless what && name
+        puts "Usage: tina4ruby generate <what> <name>"
+        puts "  Generators: model, route, migration, middleware"
+        exit 1
+      end
+
+      case what
+      when "model"    then generate_model(name)
+      when "route"    then generate_route(name)
+      when "migration" then generate_migration(name)
+      when "middleware" then generate_middleware(name)
+      else
+        puts "Unknown generator: #{what}"
+        puts "  Available: model, route, migration, middleware"
+        exit 1
+      end
+    end
+
+    def generate_model(name)
+      dir = "src/orm"
+      FileUtils.mkdir_p(dir)
+      snake = name.gsub(/([A-Z])/) { |m| ($~.begin(0) > 0 ? "_" : "") + m.downcase }
+      path = File.join(dir, "#{snake}.rb")
+      abort "  File already exists: #{path}" if File.exist?(path)
+      File.write(path, <<~RUBY)
+        class #{name} < Tina4::ORM
+          integer_field :id, primary_key: true, auto_increment: true
+          string_field :name
+          string_field :email
+        end
+      RUBY
+      puts "  Created #{path}"
+    end
+
+    def generate_route(name)
+      route_path = name.sub(%r{^/}, "")
+      dir = "src/routes/#{route_path}"
+      FileUtils.mkdir_p(dir)
+      path = dir.chomp("/") + ".rb"
+      abort "  File already exists: #{path}" if File.exist?(path)
+      File.write(path, <<~RUBY)
+        Tina4.get "/#{route_path}" do |request, response|
+          response.json(data: [])
+        end
+
+        Tina4.get "/#{route_path}/:id" do |request, response|
+          response.json(data: {})
+        end
+
+        Tina4.post "/#{route_path}" do |request, response|
+          response.json({ message: "created" }, 201)
+        end
+
+        Tina4.put "/#{route_path}/:id" do |request, response|
+          response.json(message: "updated")
+        end
+
+        Tina4.delete "/#{route_path}/:id" do |request, response|
+          response.json(message: "deleted")
+        end
+      RUBY
+      puts "  Created #{path}"
+    end
+
+    def generate_migration(name)
+      dir = "migrations"
+      FileUtils.mkdir_p(dir)
+      timestamp = Time.now.strftime("%Y%m%d%H%M%S")
+      table = name.sub(/^create_/, "")
+      table = if table.end_with?("s")
+                table
+              elsif table.end_with?("y")
+                table[0..-2] + "ies"
+              else
+                table + "s"
+              end
+      filename = "#{timestamp}_#{name}.sql"
+      path = File.join(dir, filename)
+      now = Time.now.strftime("%Y-%m-%d %H:%M:%S")
+      File.write(path, <<~SQL)
+        -- Migration: #{name}
+        -- Created: #{now}
+
+        CREATE TABLE #{table} (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            name TEXT NOT NULL,
+            email TEXT NOT NULL,
+            created_at DATETIME DEFAULT CURRENT_TIMESTAMP
+        );
+      SQL
+      puts "  Created #{path}"
+    end
+
+    def generate_middleware(name)
+      dir = "src/middleware"
+      FileUtils.mkdir_p(dir)
+      snake = name.gsub(/([A-Z])/) { |m| ($~.begin(0) > 0 ? "_" : "") + m.downcase }
+      path = File.join(dir, "#{snake}.rb")
+      abort "  File already exists: #{path}" if File.exist?(path)
+      File.write(path, <<~RUBY)
+        class #{name} < Tina4::Middleware
+          def process(request, response)
+            auth = request.headers["Authorization"]
+            return response.json({ error: "Unauthorized" }, 401) unless auth
+
+            nil
+          end
+        end
+      RUBY
+      puts "  Created #{path}"
+    end
+
     def cmd_help
       puts <<~HELP
         Tina4 Ruby CLI
@@ -326,6 +452,7 @@ module Tina4
           version            Show Tina4 version
           routes             List all registered routes
           console            Start an interactive console
+          generate <what> <name>  Generate scaffolding (model, route, migration, middleware)
           ai                 Detect AI tools and install context files
           help               Show this help message
 

data/lib/tina4/database.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 require "json"
 require "uri"
+require "digest"
 
 module Tina4
   class Database
@@ -24,6 +25,15 @@ module Tina4
       @driver_name = driver_name || detect_driver(@connection_string)
       @driver = create_driver
       @connected = false
+
+      # Query cache — off by default, opt-in via TINA4_DB_CACHE=true
+      @cache_enabled = truthy?(ENV["TINA4_DB_CACHE"])
+      @cache_ttl = (ENV["TINA4_DB_CACHE_TTL"] || "30").to_i
+      @query_cache = {}  # key => { expires_at:, value: }
+      @cache_hits = 0
+      @cache_misses = 0
+      @cache_mutex = Mutex.new
+
       connect
     end
 
@@ -41,21 +51,74 @@ module Tina4
       @connected = false
     end
 
+    # ── Query Cache ──────────────────────────────────────────────
+
+    def cache_stats
+      @cache_mutex.synchronize do
+        {
+          enabled: @cache_enabled,
+          hits: @cache_hits,
+          misses: @cache_misses,
+          size: @query_cache.size,
+          ttl: @cache_ttl
+        }
+      end
+    end
+
+    def cache_clear
+      @cache_mutex.synchronize do
+        @query_cache.clear
+        @cache_hits = 0
+        @cache_misses = 0
+      end
+    end
+
     def fetch(sql, params = [], limit: nil, skip: nil)
       effective_sql = sql
       if limit
         effective_sql = @driver.apply_limit(effective_sql, limit, skip || 0)
       end
+
+      if @cache_enabled
+        key = cache_key(effective_sql, params)
+        cached = cache_get(key)
+        if cached
+          @cache_mutex.synchronize { @cache_hits += 1 }
+          return cached
+        end
+        result = @driver.execute_query(effective_sql, params)
+        result = Tina4::DatabaseResult.new(result, sql: effective_sql)
+        cache_set(key, result)
+        @cache_mutex.synchronize { @cache_misses += 1 }
+        return result
+      end
+
       rows = @driver.execute_query(effective_sql, params)
       Tina4::DatabaseResult.new(rows, sql: effective_sql)
     end
 
     def fetch_one(sql, params = [])
+      if @cache_enabled
+        key = cache_key(sql + ":ONE", params)
+        cached = cache_get(key)
+        if cached
+          @cache_mutex.synchronize { @cache_hits += 1 }
+          return cached
+        end
+        result = fetch(sql, params, limit: 1)
+        value = result.first
+        cache_set(key, value)
+        @cache_mutex.synchronize { @cache_misses += 1 }
+        return value
+      end
+
       result = fetch(sql, params, limit: 1)
       result.first
     end
 
     def insert(table, data)
+      cache_invalidate if @cache_enabled
+
       # List of hashes — batch insert
       if data.is_a?(Array)
         return { success: true, affected_rows: 0 } if data.empty?
@@ -74,6 +137,8 @@ module Tina4
     end
 
     def update(table, data, filter = {})
+      cache_invalidate if @cache_enabled
+
       set_parts = data.keys.map { |k| "#{k} = #{@driver.placeholder}" }
       where_parts = filter.keys.map { |k| "#{k} = #{@driver.placeholder}" }
       sql = "UPDATE #{table} SET #{set_parts.join(', ')}"
@@ -84,6 +149,8 @@ module Tina4
     end
 
     def delete(table, filter = {})
+      cache_invalidate if @cache_enabled
+
       # List of hashes — delete each row
       if filter.is_a?(Array)
         filter.each { |row| delete(table, row) }
@@ -107,6 +174,7 @@ module Tina4
     end
 
     def execute(sql, params = [])
+      cache_invalidate if @cache_enabled
       @driver.execute(sql, params)
     end
 
@@ -142,6 +210,39 @@ module Tina4
 
     private
 
+    def truthy?(val)
+      %w[true 1 yes on].include?((val || "").to_s.strip.downcase)
+    end
+
+    def cache_key(sql, params)
+      Digest::SHA256.hexdigest(sql + params.to_s)
+    end
+
+    def cache_get(key)
+      @cache_mutex.synchronize do
+        entry = @query_cache[key]
+        return nil unless entry
+        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > entry[:expires_at]
+          @query_cache.delete(key)
+          return nil
+        end
+        entry[:value]
+      end
+    end
+
+    def cache_set(key, value)
+      @cache_mutex.synchronize do
+        @query_cache[key] = {
+          expires_at: Process.clock_gettime(Process::CLOCK_MONOTONIC) + @cache_ttl,
+          value: value
+        }
+      end
+    end
+
+    def cache_invalidate
+      @cache_mutex.synchronize { @query_cache.clear }
+    end
+
     def detect_driver(conn)
       case conn.to_s.downcase
       when /\.db$/, /\.sqlite/, /sqlite/

data/lib/tina4/dev_mailbox.rb

@@ -34,7 +34,7 @@ module Tina4
         attachments: store_attachments(msg_id, attachments),
         read: false,
         folder: "outbox",
-        created_at: timestamp.iso8601,
+        created_at: timestamp.strftime("%Y-%m-%dT%H:%M:%S.%6N%:z"),
         updated_at: timestamp.iso8601
       }