gemstack 0.2.5 → 0.3.0

data/templates/app/config/environments/production.rb.tt

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Production settings: applied after config/app.rb when GEMSTACK_ENV=production.
+# Each line shows the default value — uncomment one to change it.
+#
+# Secrets and connections come from environment variables, never from files:
+# SECRET_KEY_BASE, <% if database? %>DATABASE_URL, <% end %>SMTP_URL, MAIL_FROM, APP_URL, REDIS_URL…
+# `gemstack doctor --production` checks what's missing (docs/deployment.md).
+GemStack.configure do |config|
+  # ── Code ────────────────────────────────────────────────────────────────
+  # config.eager_load = true                   # load all code at boot (copy-on-write friendly with Puma workers)
+  # config.jit = :yjit                         # Ruby's JIT (or GEMSTACK_JIT=yjit|zjit|off)
+
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :info
+  # config.logger.format = :json               # one JSON object per line, with the request id
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.show_exceptions = false        # never send exception details to clients
+  # config.http.hsts = "max-age=63072000; includeSubDomains"   # on HTTPS requests; nil if your proxy sets it
+  # config.http.cors.origins = ["https://app.example.com"]    # only if the frontend is on another domain
+  # config.http.max_body_size = 10 * 1024 * 1024               # larger requests get 413
+<% if database? -%>
+
+  # ── Database ────────────────────────────────────────────────────────────
+  # config.db.pool_size = 5                    # connections per process (GEMSTACK_MAX_THREADS)
+  # config.db.statement_timeout = 5_000        # ms; stop runaway queries (PostgreSQL, MySQL)
+  # config.db.slow_query_ms = 500              # slower queries are logged at WARN
+<% end -%>
+
+  # ── Cache: :memory is per process — use Redis with several processes or servers ──
+  # config.cache.store = :redis                # add gem "redis-client"; REDIS_URL
+
+  # ── Background jobs (`gemstack jobs`) ───────────────────────────────────
+  # config.jobs.concurrency = 5                # threads per worker (or GEMSTACK_JOB_CONCURRENCY)
+
+  # ── Mail ────────────────────────────────────────────────────────────────
+  # config.mail.delivery = :smtp               # SMTP_URL=smtp://user:password@smtp.example.com:587
+  # config.mail.default_from = "App <hello@example.com>"      # or MAIL_FROM
+end

data/templates/app/config/environments/test.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Test settings: applied after config/app.rb when tests run (`gemstack test`).
+# Each line shows the default value — uncomment one to change it.
+GemStack.configure do |config|
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :debug               # logs are discarded in tests unless this (or GEMSTACK_LOG_LEVEL) is set
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.show_exceptions = true         # a failing request's JSON includes the exception
+<% if database? -%>
+
+  # ── Database (connection: the test section of config/database.yml, or TEST_DATABASE_URL) ──
+  # config.db.log_queries = false
+<% end -%>
+
+  # ── Background work is recorded, not performed ──────────────────────────
+  # config.jobs.adapter = :test                # assert_enqueued / perform_enqueued_jobs; :inline runs jobs at once
+  # config.mail.delivery = :test               # assert_emails / last_email
+  # config.cache.store = :null                 # no caching, so tests can't leak into each other; :memory to test it
+end

data/templates/app/config/puma.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Puma configuration. Every value can be set through the environment.
+# `gemstack dev` sets GEMSTACK_API_HOST/PORT to a private loopback port
+# behind the development gateway.
+
+max_threads = Integer(ENV.fetch("GEMSTACK_MAX_THREADS", 5))
+min_threads = Integer(ENV.fetch("GEMSTACK_MIN_THREADS", max_threads))
+threads min_threads, max_threads
+
+bind "tcp://#{ENV.fetch("GEMSTACK_API_HOST", "0.0.0.0")}:#{ENV.fetch("GEMSTACK_API_PORT", 4000)}"
+environment ENV.fetch("GEMSTACK_ENV", "development")
+
+# Cluster mode for multi-core production servers: WEB_CONCURRENCY=4
+worker_count = Integer(ENV.fetch("WEB_CONCURRENCY", 0))
+if worker_count.positive?
+  workers worker_count
+  preload_app!
+  # Connections must not be shared across forked workers; each reconnects lazily.
+  before_fork { GemStack::DB.disconnect if defined?(GemStack::DB) }
+end

data/templates/app/config/routes.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# API routes, relative to config.http.api_path ("/api"):
+#
+#   get "/status", to: "status#show"   # GET /api/status → StatusController#show
+#   resources :products                # /api/products: index, create, show, update, destroy
+#
+# List them with `gemstack routes`. In development this file reloads on save.
+GemStack.routes do
+end

data/templates/app/config.ru

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Rack entry point. Works with Puma (config/puma.rb) or any Rack server.
+require_relative "config/app"
+
+run GemStack.boot!

data/templates/app/db/seeds.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Development data, loaded by `gemstack db:seed` (and db:setup). Make it safe to run twice:
+#
+#   Product.find_by(name: "Desk lamp") || Product.create(name: "Desk lamp", price: "39.00")

data/templates/app/dot_env.example.tt

@@ -0,0 +1,19 @@
+# Copy to .env for local development overrides. Never commit real secrets.
+# Variables already set in your shell always take precedence.
+
+# PORT=3000                   # public development port (gemstack dev)
+# GEMSTACK_LOG_LEVEL=debug
+
+<% if database? -%>
+# Database: config/database.yml. A URL here overrides it (hosting platforms set DATABASE_URL).
+<% if database_adapter == "sqlite3" -%>
+# DATABASE_URL=sqlite3:db/development.sqlite3
+<% elsif database_adapter == "postgresql" -%>
+# DATABASE_URL=postgres://user:password@localhost:5432/<%= database_name %>_development
+# TEST_DATABASE_URL=postgres://user:password@localhost:5432/<%= database_name %>_test
+<% else -%>
+# DATABASE_PASSWORD=
+# DATABASE_URL=<%= database_adapter %>://root:password@127.0.0.1:3306/<%= database_name %>_development
+# TEST_DATABASE_URL=<%= database_adapter %>://root:password@127.0.0.1:3306/<%= database_name %>_test
+<% end -%>
+<% end -%>

data/templates/app/dot_gitignore

@@ -0,0 +1,16 @@
+/.bundle/
+/log/
+/tmp/
+/db/*.sqlite3
+/db/*.sqlite3-*
+.env
+.env.local
+.env.*.local
+
+node_modules/
+/frontend/.next/
+/frontend/out/
+/frontend/next-env.d.ts
+*.tsbuildinfo
+
+.DS_Store

data/templates/app/dot_node-version.tt

@@ -0,0 +1 @@
+<%= node_version %>

data/templates/app/dot_nvmrc.tt

@@ -0,0 +1 @@
+<%= node_version %>

data/templates/app/dot_ruby-version.tt

@@ -0,0 +1 @@
+<%= ruby_version %>

data/templates/app/dot_tool-versions.tt

@@ -0,0 +1,4 @@
+ruby <%= ruby_version %>
+<% if frontend? -%>
+nodejs <%= node_version %>
+<% end -%>

data/templates/app/test/health_test.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "test_helper"
+
+class HealthTest < GemStack::TestCase
+  def test_api_boots_and_answers_health_checks
+    get_json "/api/health"
+
+    assert_status 200
+    assert_equal({ "status" => "ok" }, json_body)
+  end
+
+  def test_unknown_routes_return_json_errors
+    get_json "/api/does-not-exist"
+
+    assert_error 404, "route_not_found"
+  end
+end

data/templates/app/test/test_helper.rb.tt

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+ENV["GEMSTACK_ENV"] = "test"
+
+require_relative "../config/app"
+require "gemstack/testing"
+require "gemstack/jobs/testing"
+<% if database? -%>
+require "gemstack/db/testing"
+<% end -%>
+require "minitest/autorun"
+
+<% if database? -%>
+# Creates the test database (TEST_DATABASE_URL) if needed and applies migrations.
+GemStack::DB::Testing.prepare!
+<% end -%>
+GemStack.boot!
+<% if database? -%>
+
+# Every test runs in a transaction that is rolled back afterwards.
+GemStack::TestCase.include GemStack::DB::Testing::Transactions
+<% end -%>
+
+# Jobs are recorded, not run: assert_enqueued / perform_enqueued_jobs.
+GemStack::TestCase.include GemStack::Jobs::Testing

data/templates/auth/app/controllers/api_tokens_controller.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Personal API tokens: send `Authorization: Bearer <token>` instead of a cookie.
+#   GET /api/auth/tokens · POST /api/auth/tokens · DELETE /api/auth/tokens/:id
+class ApiTokensController < ApplicationController
+  before :require_login
+  before :require_session, only: %i[create destroy] # a leaked token can't mint or revoke tokens
+
+  accepts :create do
+    required :name, :string, max_length: 100
+  end
+  returns :index, [ApiTokenSerializer]
+  returns :create, NewApiTokenSerializer
+
+  def index = render(current_user.auth_tokens_dataset.api.order(Sequel.desc(:created_at)), serializer: ApiTokenSerializer)
+
+  def create
+    token, id = GemStack::Auth::Tokens.issue(current_user.id, purpose: "api", name: input[:name])
+    render NewApiTokenSerializer::Result.new(token: token, api_token: AuthToken[id]),
+           status: :created, serializer: NewApiTokenSerializer
+  end
+
+  def destroy
+    revoked = GemStack::Auth::Tokens.revoke(params[:id], user_id: current_user.id)
+    raise GemStack::NotFound, "API token not found" unless revoked
+  end
+
+  private
+
+  def require_session
+    return if authenticated_by == :session
+
+    raise GemStack::Forbidden.new("Manage API tokens from the app.", code: "session_required")
+  end
+end

data/templates/auth/app/controllers/email_verifications_controller.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# POST /api/auth/email/resend · POST /api/auth/email/verify
+class EmailVerificationsController < ApplicationController
+  before :require_login, only: :create
+  rate_limit to: 5, within: 3600, only: :create
+  rate_limit to: 20, within: 3600, only: :update
+
+  accepts :update do
+    required :token, :string, max_length: 200
+  end
+  returns :create, nil
+  returns :update, nil
+
+  def create
+    AuthMailer.email_verification(current_user.id).deliver_later unless current_user.email_verified?
+    head :accepted
+  end
+
+  # Works signed in or out: the link may be opened on another device.
+  def update
+    row = GemStack::Auth::Tokens.consume(input[:token], purpose: "email_verification")
+    user = row && User[row[:user_id]]
+    # Only valid for the address it was sent to.
+    unless user && user.email == row[:email]
+      raise GemStack::BadRequest.new("This verification link is invalid or has expired.", code: "invalid_token")
+    end
+
+    user.update(email_verified_at: Time.now) unless user.email_verified?
+  end
+end

data/templates/auth/app/controllers/password_resets_controller.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# POST /api/auth/password/forgot · POST /api/auth/password/reset
+class PasswordResetsController < ApplicationController
+  rate_limit to: 10, within: 3600, only: :create
+  rate_limit to: 3, within: 3600, only: :create, name: "reset-email", by: -> { params[:email].to_s.downcase }
+  rate_limit to: 10, within: 3600, only: :update
+
+  accepts :create do
+    required :email, :string, max_length: 254
+  end
+  accepts :update do
+    required :token, :string, max_length: 200
+    required :password, :string, max_length: 1024
+  end
+  returns :create, nil
+  returns :update, UserSerializer
+
+  # Always 202: whether an account exists is nobody else's business.
+  def create
+    user = User.first(email: User.normalize_email(input[:email]))
+    AuthMailer.password_reset(user.id).deliver_later if user
+    head :accepted
+  end
+
+  def update
+    errors = GemStack::Auth::Password.errors(input[:password])
+    raise GemStack::ValidationError.new(errors: { password: errors }) unless errors.empty?
+
+    row = GemStack::Auth::Tokens.consume(input[:token], purpose: "password_reset")
+    raise GemStack::BadRequest.new("This reset link is invalid or has expired.", code: "invalid_token") unless row
+
+    user = User[row[:user_id]]
+    user.update(password: input[:password])
+    # A reset usually means the old password leaked: end every session.
+    GemStack::Auth::Sessions.revoke_all(user.id)
+    sign_in(user)
+    render user
+  end
+end

data/templates/auth/app/controllers/registrations_controller.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# POST /api/auth/signup
+class RegistrationsController < ApplicationController
+  rate_limit to: 10, within: 3600, only: :create
+
+  accepts :create do
+    required :email, :string, max_length: 254
+    required :password, :string, max_length: 1024
+  end
+  returns :create, UserSerializer
+
+  def create
+    user = User.create(email: input[:email], password: input[:password]) # invalid: 422 with field errors
+    AuthMailer.email_verification(user.id).deliver_later
+    sign_in(user)
+    render user, status: :created
+  end
+end

data/templates/auth/app/controllers/sessions_controller.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# POST /api/auth/login · GET /api/auth/me · DELETE /api/auth/logout
+class SessionsController < ApplicationController
+  before :require_login, only: :show
+  # Per IP, and per account so one address can't be guessed at from many IPs.
+  rate_limit to: 20, within: 300, only: :create
+  rate_limit to: 10, within: 300, only: :create, name: "login-email", by: -> { params[:email].to_s.downcase }
+
+  accepts :create do
+    required :email, :string, max_length: 254
+    required :password, :string, max_length: 1024
+  end
+  returns :create, UserSerializer
+  returns :show, UserSerializer
+
+  def create
+    user = User.authenticate_by(email: input[:email], password: input[:password])
+    # The same answer for "no such account" and "wrong password".
+    raise GemStack::Unauthorized.new("Invalid email or password.", code: "invalid_credentials") unless user
+
+    sign_in(user)
+    render user
+  end
+
+  def show = render(current_user)
+
+  def destroy = sign_out
+end

data/templates/auth/app/mailers/auth_mailer.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Account emails. Templates: app/mailers/templates/auth_mailer/*.erb.
+# Links point at the Next.js pages (config.auth.app_url, APP_URL in production).
+class AuthMailer < ApplicationMailer
+  def password_reset(user_id)
+    @user = User[user_id] or return
+    token, = GemStack::Auth::Tokens.issue(@user.id, purpose: "password_reset")
+    @url = GemStack::Auth.url("/reset-password", token: token)
+    @minutes = GemStack.config.auth.password_reset_ttl / 60
+    mail to: @user.email, subject: "Reset your password"
+  end
+
+  def email_verification(user_id)
+    @user = User[user_id] or return
+    token, = GemStack::Auth::Tokens.issue(@user.id, purpose: "email_verification", email: @user.email)
+    @url = GemStack::Auth.url("/verify-email", token: token)
+    mail to: @user.email, subject: "Confirm your email address"
+  end
+end

data/templates/auth/app/mailers/templates/auth_mailer/email_verification.html.erb

@@ -0,0 +1,2 @@
+<p>Welcome! Please confirm that <%= @user.email %> is your email address.</p>
+<p><a href="<%= @url %>">Confirm my email address</a></p>

data/templates/auth/app/mailers/templates/auth_mailer/email_verification.text.erb

@@ -0,0 +1,2 @@
+Welcome! Please confirm that <%= @user.email %> is your email address:
+<%= @url %>

data/templates/auth/app/mailers/templates/auth_mailer/password_reset.html.erb

@@ -0,0 +1,3 @@
+<p>Someone (hopefully you) asked to reset the password for <%= @user.email %>.</p>
+<p><a href="<%= @url %>">Choose a new password</a> — the link works once, for <%= @minutes %> minutes.</p>
+<p>If it wasn't you, ignore this email: your password stays the same.</p>

data/templates/auth/app/mailers/templates/auth_mailer/password_reset.text.erb

@@ -0,0 +1,6 @@
+Someone (hopefully you) asked to reset the password for <%= @user.email %>.
+
+Choose a new password here (the link works once, for <%= @minutes %> minutes):
+<%= @url %>
+
+If it wasn't you, ignore this email — your password stays the same.

data/templates/auth/app/models/auth_token.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# API tokens (and single-use reset/verification tokens) — see GemStack::Auth::Tokens.
+class AuthToken < ApplicationModel
+  field :purpose, :string, null: false
+  field :name, :string, size: 100
+  field :last_used_at, :datetime
+  field :expires_at, :datetime
+
+  belongs_to :user
+
+  dataset_module do
+    def api = where(purpose: "api")
+  end
+end

data/templates/auth/app/models/user.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Accounts. GemStack::Auth::User adds password hashing (Argon2id), email
+# normalization, validations and User.authenticate_by(email:, password:).
+class User < ApplicationModel
+  include GemStack::Auth::User
+
+  field :email, :string, null: false, size: 254
+  field :email_verified_at, :datetime
+
+  has_many :auth_tokens
+end

data/templates/auth/app/policies/application_policy.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Base class for policies (`gemstack generate policy Order`). Everything is
+# denied unless a policy allows it; see docs/authorization.md.
+class ApplicationPolicy < GemStack::Policy
+end

data/templates/auth/app/serializers/api_token_serializer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+class ApiTokenSerializer < ApplicationSerializer
+  model AuthToken
+  attributes :id, :name, :last_used_at, :expires_at, :created_at
+end

data/templates/auth/app/serializers/new_api_token_serializer.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The response to creating an API token: the only time the token itself is shown.
+class NewApiTokenSerializer < ApplicationSerializer
+  Result = Data.define(:token, :api_token)
+
+  attribute :token, :string
+  attribute :api_token, ApiTokenSerializer
+end

data/templates/auth/app/serializers/user_serializer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# What the API shows about the signed-in user. Never add password_digest.
+class UserSerializer < ApplicationSerializer
+  attributes :id, :email, :email_verified_at, :created_at
+end

data/templates/auth/db/migrations/%timestamp%_create_auth_tables.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# Tables used by GemStack::Auth (docs/authentication.md).
+Sequel.migration do
+  change do
+    create_table(:users) do
+      primary_key :id, type: :Bignum
+      String :email, null: false, unique: true # stored lowercased
+      String :password_digest, null: false     # Argon2id
+      column :email_verified_at, :timestamptz
+      column :created_at, :timestamptz, null: false
+      column :updated_at, :timestamptz, null: false
+    end
+
+    # One row per signed-in browser; the cookie holds a random token, the
+    # table only its SHA-256 digest.
+    create_table(:sessions) do
+      primary_key :id, type: :Bignum
+      foreign_key :user_id, :users, type: :Bignum, null: false, on_delete: :cascade, index: true
+      String :token_digest, size: 64, null: false, unique: true
+      column :ip, :inet
+      String :user_agent
+      column :created_at, :timestamptz, null: false
+      column :last_seen_at, :timestamptz, null: false
+      column :expires_at, :timestamptz, null: false, index: true
+    end
+
+    # API tokens, password reset and email verification tokens (digests only).
+    create_table(:auth_tokens) do
+      primary_key :id, type: :Bignum
+      foreign_key :user_id, :users, type: :Bignum, null: false, on_delete: :cascade, index: true
+      String :purpose, size: 30, null: false
+      String :token_digest, size: 64, null: false, unique: true
+      String :name
+      String :email
+      column :created_at, :timestamptz, null: false
+      column :last_used_at, :timestamptz
+      column :expires_at, :timestamptz
+    end
+  end
+end

data/templates/auth/frontend/app/account/page.tsx

@@ -0,0 +1,116 @@
+"use client";
+
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+import { useState, type FormEvent } from "react";
+import {
+  errorMessage,
+  useApiTokens,
+  useCreateApiToken,
+  useCurrentUser,
+  useLogout,
+  useResendVerification,
+  useRevokeApiToken,
+} from "@/lib/auth";
+
+export default function AccountPage() {
+  const router = useRouter();
+  const { data: user, isPending } = useCurrentUser();
+  const logout = useLogout();
+  const resend = useResendVerification();
+
+  if (isPending) return <main className="page muted">Loading…</main>;
+  if (!user) {
+    return (
+      <main className="page">
+        <h1>Account</h1>
+        <p>
+          You are signed out. <Link href="/login">Log in</Link> or <Link href="/signup">sign up</Link>.
+        </p>
+      </main>
+    );
+  }
+
+  return (
+    <main className="page">
+      <div className="page-header">
+        <h1>Account</h1>
+        <button className="button" onClick={() => logout.mutate(undefined, { onSuccess: () => router.push("/login") })}>
+          Log out
+        </button>
+      </div>
+      <dl className="card">
+        <dt>Email</dt>
+        <dd>
+          {user.email}{" "}
+          {user.email_verified_at ? (
+            <span className="muted">(confirmed)</span>
+          ) : (
+            <button className="button" disabled={resend.isPending || resend.isSuccess} onClick={() => resend.mutate()}>
+              {resend.isSuccess ? "Email sent" : "Resend confirmation email"}
+            </button>
+          )}
+        </dd>
+        <dt>Member since</dt>
+        <dd>{new Date(user.created_at).toLocaleDateString()}</dd>
+      </dl>
+      <ApiTokens />
+    </main>
+  );
+}
+
+function ApiTokens() {
+  const tokens = useApiTokens();
+  const create = useCreateApiToken();
+  const revoke = useRevokeApiToken();
+  const [name, setName] = useState("");
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    create.mutate(name, { onSuccess: () => setName("") });
+  }
+
+  return (
+    <section>
+      <h2>API tokens</h2>
+      <p className="muted">
+        For scripts and other services: send <code>Authorization: Bearer &lt;token&gt;</code>.
+      </p>
+      {create.data && (
+        <p className="status status-ok">
+          <span className="dot" />
+          Copy your new token now — it won&apos;t be shown again: <code>{create.data.token}</code>
+        </p>
+      )}
+      <form className="form" onSubmit={handleSubmit}>
+        <label className="field">
+          Name
+          <input required maxLength={100} value={name} onChange={(e) => setName(e.target.value)} placeholder="CI" />
+        </label>
+        {create.error && <p className="form-error">{errorMessage(create.error)}</p>}
+        <div className="actions">
+          <button className="button" type="submit" disabled={create.isPending}>
+            Create token
+          </button>
+        </div>
+      </form>
+      <table className="table">
+        <tbody>
+          {tokens.data?.map((token) => (
+            <tr key={token.id}>
+              <td>{token.name}</td>
+              <td className="muted">
+                {token.last_used_at ? `used ${new Date(token.last_used_at).toLocaleString()}` : "never used"}
+              </td>
+              <td>
+                <button className="button button-danger" onClick={() => revoke.mutate(token.id)}>
+                  Revoke
+                </button>
+              </td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}