gemstack-cli 0.1.0

data/templates/app/README.md.tt

@@ -0,0 +1,29 @@
+# <%= module_name %>
+
+A [GemStack](https://github.com/gemstack/gemstack) application: a Ruby API with a
+Next.js + TypeScript frontend, served from one origin.
+
+```bash
+gemstack dev          # http://localhost:3000  (/api/* → Ruby, everything else → Next.js)
+gemstack routes       # list API routes
+gemstack test         # run the Ruby tests
+gemstack console      # IRB with the app loaded
+gemstack generate controller Status show
+```
+
+## Layout
+
+| Path | What lives there |
+|---|---|
+| `config/app.rb` | configuration (`GemStack.configure`) |
+| `config/routes.rb` | API routes, relative to `/api` |
+| `app/` | autoloaded code: `controllers/`, and any folder you add (`services/`, ...) |
+| `test/` | Minitest + rack-test (`GemStack::TestCase`) |
+| `frontend/` | the Next.js app; `lib/gemstack/client.ts` talks to the API |
+
+## Production
+
+Run the API with `gemstack server` (Puma, `config/puma.rb`) and the frontend
+with `npm run build && npm start` in `frontend/`. Either route `/api/*` to the
+API with your reverse proxy, or set `GEMSTACK_API_URL` for the Next.js process
+and it will proxy `/api/*` itself.

data/templates/app/app/controllers/application_controller.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Shared behaviour for every controller: before callbacks (e.g. authentication),
+# rescue_from handlers and helpers.
+class ApplicationController < GemStack::Controller
+end

data/templates/app/bin/gemstack

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Runs the GemStack CLI from this application's bundle.
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../Gemfile", __dir__)
+require "bundler/setup"
+load Gem.bin_path("gemstack-cli", "gemstack")

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "gemstack"
+
+# Sets the application root and loads .env files (development/test).
+GemStack.setup(root: File.expand_path("..", __dir__))
+
+# Require the gems listed in the Gemfile for the current environment.
+Bundler.require(:default, GemStack.env.to_sym)
+
+GemStack.configure do |config|
+  config.name = "<%= name %>"
+
+  # Everything below is optional — these are the defaults. See docs/configuration.md.
+  #
+  # config.http.api_path = "/api"                  # where the API lives (routes are relative to it)
+  # config.http.max_body_size = 10 * 1024 * 1024   # bytes; larger requests get 413
+  # config.http.json = :json                       # or :oj (add gem "oj"), or your own codec
+  # config.http.cors.origins = []                  # only for frontends on another domain
+  # config.http.middleware.use MyMiddleware        # add / insert_before / swap / delete
+  # config.logger.level = :debug
+  # config.filter_parameters += %w[iban]           # masked in logs
+<% if database? -%>
+  #
+  # config.db.url = ENV["DATABASE_URL"]            # default: postgres:///<name>_<env> (TEST_DATABASE_URL in test)
+  # config.db.pool_size = 5                        # default: GEMSTACK_MAX_THREADS (one per Puma thread)
+  # config.db.statement_timeout = 5_000            # ms
+<% end -%>
+end

data/templates/app/config/environments/development.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Development-only settings. config/app.rb applies to every environment.
+GemStack.configure do |config|
+  # config.http.show_exceptions = true   # exception details in 500 responses (default in development)
+end

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

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Production-only settings. Defaults here: JSON logs, no exception details in
+# responses, eager loading, HSTS on HTTPS requests.
+GemStack.configure do |config|
+  # config.logger.level = :info
+  # config.http.cors.origins = ["https://app.example.com"]   # only if the frontend is on another domain
+end

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

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Test-only settings. config/app.rb applies to every environment.
+GemStack.configure do |config|
+  # Logs are discarded in tests unless GEMSTACK_LOG_LEVEL is set, e.g.:
+  # config.logger.level = :debug
+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

@@ -0,0 +1,9 @@
+# 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
+
+# PostgreSQL. Defaults: postgres:///<app>_development locally (current OS user).
+# DATABASE_URL=postgres://user:password@localhost:5432/myapp_development
+# TEST_DATABASE_URL=postgres://user:password@localhost:5432/myapp_test

data/templates/app/dot_gitignore

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

data/templates/app/dot_ruby-version.tt

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

data/templates/app/dot_tool-versions.tt

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

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 < GemStack::Mailer
+  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 < GemStack::Model
+  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 < GemStack::Model
+  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 < GemStack::Serializer
+  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 < GemStack::Serializer
+  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 < GemStack::Serializer
+  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
+      column :email, :text, null: false, unique: true # stored lowercased
+      column :password_digest, :text, 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
+      column :token_digest, :text, null: false, unique: true
+      column :ip, :inet
+      column :user_agent, :text
+      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
+      column :purpose, :text, null: false
+      column :token_digest, :text, null: false, unique: true
+      column :name, :text
+      column :email, :text
+      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>
+  );
+}