gemstack-cli 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 302c6d867a26dcdbf305cc2c4d54479bc3b5094b30dc7c79873882b5d6062598
-  data.tar.gz: f09ed00f2ac675747ab91c808a682b75c71be04193defc59755e7798c0dbfc49
+  metadata.gz: 8f9ebe8567d9943d054f3baaf1427483fd75242677bc8a461034d63a826b197e
+  data.tar.gz: 816d6520c304822b290f30b417f574dfe8bd771586d5bc8a6df2b929ec144b4f
 SHA512:
-  metadata.gz: 94dddfd035b6782455385e61a8306bcb46526e5979c43f43b4604cb133593713b0166528df8345ab6850f288c7f6118e75381a91c5729c9dcba2977e12819d81
-  data.tar.gz: cae54dd8b24e7ce6ba106570d858476992c6b11634e717e9ef2b79b1ac1d853ea3292bd32b96994a65e98cc22320bbc860d55d781843c289320cccc6902deaaa
+  metadata.gz: 7068ec73cee6b4f0e87cb5c84a4f0531bbfd8444df9170a994e6223f8a32cf7d5b814ef089bc5c5854ce539e919bc9a5dde10118dcfcd035ac02099bff5e5e28
+  data.tar.gz: f1c8ddf36a3b0eb81f7a1a680b5c95bfa8df8328dbbf0804f927bfb85339f02fba020cb6e8d66e16f0c14fff3902a2183bd49a212dc1a39bf3ce650365b55b62

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.2
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
+## 0.2.1
+
+See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).
+
 ## 0.2.0
 
 See the [GemStack changelog](https://github.com/gemstack-rb/gemstack/blob/main/CHANGELOG.md).

data/LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Shoaib Malik
+Copyright (c) 2026 Adware Technologies (https://www.adwaretech.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -3,7 +3,7 @@
 GemStack command-line interface and generators.
 
 Part of [GemStack](https://github.com/gemstack-rb/gemstack), a modular Ruby API framework for Next.js
-applications. All GemStack gems are developed together in that repository and released with the same
+applications by [Adware Technologies](https://www.adwaretech.com). All GemStack gems are developed together in that repository and released with the same
 version.
 
 ## Installation
@@ -21,4 +21,4 @@ Source, issues and pull requests: [gemstack-rb/gemstack](https://github.com/gems
 
 ## License
 
-MIT — see [LICENSE.txt](LICENSE.txt).
+Open source under the MIT License — © [Adware Technologies](https://www.adwaretech.com). See [LICENSE.txt](LICENSE.txt).

data/lib/gemstack/cli/add_generator.rb

@@ -70,6 +70,7 @@ module GemStack
 
       def add_storage
         add_gem("gemstack-storage")
+        ensure_base_classes(@root, :serializer)
         copy_feature_templates("storage")
         add_routes(%(post "/uploads", to: "uploads#create" # direct uploads (gemstack add storage)\n),
                    marker: "uploads#create")
@@ -94,6 +95,7 @@ module GemStack
         add_gem("gemstack-mail")
         add_gem("gemstack-auth")
         JobGenerator.install_migration(@root, output: @output) # emails are sent from background jobs
+        ensure_base_classes(@root, :model, :serializer, :mailer)
         copy_feature_templates("auth", skip_migration: "*_create_auth_tables.rb")
         include_in_application_controller("GemStack::Auth::Controller")
         add_routes(AUTH_ROUTES, marker: "/auth/login")

data/lib/gemstack/cli/app_generator.rb

@@ -54,7 +54,7 @@ module GemStack
         database_adapter if database? # fail early on an unknown --database
         @output.puts("Creating GemStack application #{name} in #{destination}")
         render_directory("app", destination, skip: lambda { |rel|
-          !database? && (rel.start_with?("db/") || rel == "config/database.yml.tt")
+          !database? && (rel.start_with?("db/", "app/models/") || rel == "config/database.yml.tt")
         })
         render_directory("frontend", File.join(destination, "frontend")) if frontend?
         install unless @options[:skip_install]
@@ -86,6 +86,8 @@ module GemStack
 
         run_step("npm install", File.join(destination, "frontend"), "npm", "install", "--no-fund",
                  "--no-audit")
+        # The TypeScript contract, so frontend/lib/api/generated exists from the start.
+        run_step("gemstack contract", destination, "bin/gemstack", "contract", "--quiet") if bundled
       end
 
       # Best effort: a missing or password-protected database server shouldn't fail `new`.

data/lib/gemstack/cli/deploy_generator.rb

@@ -18,8 +18,7 @@ module GemStack
       def jobs?
         return true if gemfile.match?(/^\s*gem "gemstack-auth"/)
 
-        gemfile.match?(/^\s*gem "gemstack-jobs"/) &&
-          %w[app/jobs/*.rb app/mailers/*.rb].any? { |glob| !Dir.glob(File.join(@root, glob)).empty? }
+        gemfile.match?(/^\s*gem "gemstack-jobs"/) && Generator.background_work?(@root)
       end
 
       def mail? = gemfile.match?(/^\s*gem "gemstack-(mail|auth)"/)

data/lib/gemstack/cli/doctor.rb

@@ -290,7 +290,7 @@ module GemStack
       end
 
       def jobs_used?
-        %w[app/jobs/*.rb app/mailers/*.rb].any? { |glob| !Dir.glob(path(glob)).empty? }
+        Generator.background_work?(@root)
       end
 
       def location(error)

data/lib/gemstack/cli/generator.rb

@@ -59,6 +59,28 @@ module GemStack
       end
 
       # Every template file for a generator, with app overrides applied.
+      # The app's base classes (written by `gemstack new` since 0.2.1). Apps
+      # created earlier get the ones a generator's code inherits from.
+      BASE_CLASSES = {
+        model: "app/models/application_model.rb", serializer: "app/serializers/application_serializer.rb",
+        job: "app/jobs/application_job.rb", mailer: "app/mailers/application_mailer.rb"
+      }.freeze
+
+      # Whether the app has jobs or mailers of its own (base classes don't count).
+      def self.background_work?(root)
+        %w[app/jobs/*.rb app/mailers/*.rb].any? do |glob|
+          Dir.glob(File.join(root, glob)).any? { |file| !File.basename(file).start_with?("application_") }
+        end
+      end
+
+      def ensure_base_classes(root, *kinds)
+        kinds.each do |kind|
+          rel = BASE_CLASSES.fetch(kind)
+          target = File.join(root, rel)
+          write(target, File.read(File.join(template_root("app"), rel))) unless File.exist?(target)
+        end
+      end
+
       def template_files(name, override_root: nil)
         files = relative_files(template_root(name)).to_h { |rel| [rel, File.join(template_root(name), rel)] }
         if override_root

data/lib/gemstack/cli/job_generator.rb

@@ -35,6 +35,7 @@ module GemStack
       end
 
       def run
+        ensure_base_classes(@root, :job)
         template_files("job", override_root: @root).each do |rel, source|
           target = File.join(@root, rel.delete_suffix(".tt").gsub("%file_name%", file_name))
           write(target, render(File.read(source), source))

data/lib/gemstack/cli/resource_generator.rb

@@ -34,6 +34,7 @@ module GemStack
       end
 
       def run
+        ensure_base_classes(@root, *(%i[model serializer] & @parts))
         @parts.each { |part| render_part(part) }
         add_routes if @parts.include?(:controller)
         self

data/templates/app/Gemfile.tt

@@ -14,6 +14,7 @@ path "<%= gemstack_path %>" do
   gem "gemstack-db"
 <% end -%>
   gem "gemstack-jobs"
+  gem "gemstack-mail"
   gem "gemstack-dev"
   gem "gemstack-http"
   gem "gemstack-schema"
@@ -24,6 +25,7 @@ gem "gemstack", "~> <%= version %>"
 gem "gemstack-db", "~> <%= version %>"
 <% end -%>
 gem "gemstack-jobs", "~> <%= version %>"
+gem "gemstack-mail", "~> <%= version %>"
 <% end -%>
 gem "puma", ">= 6.4"
 <% if database? -%>

data/templates/app/app/jobs/application_job.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# The base class for this app's background jobs (docs/background-jobs.md):
+# retry and discard rules declared here apply to every job.
+class ApplicationJob < GemStack::Job
+  # retry_on Net::ReadTimeout, attempts: 5, wait: 30   # seconds, :exponential or ->(attempt) { … }
+  # discard_on GemStack::NotFound                      # e.g. the record was deleted before the job ran
+  # queue :default
+end

data/templates/app/app/mailers/application_mailer.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# The base class for this app's mailers (docs/mail.md). Templates live in
+# app/mailers/templates/<mailer>/<action>.{text,html}.erb.
+class ApplicationMailer < GemStack::Mailer
+  # default from: "My App <hello@example.com>"          # otherwise config.mail.default_from (MAIL_FROM)
+  # default reply_to: "support@example.com"
+end

data/templates/app/app/models/application_model.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# The base class for this app's models — add plugins, validations and helpers
+# every model should share here. `class Product < ApplicationModel` maps to the
+# products table (docs/models.md).
+#
+# Created with Class.new on purpose: `class ApplicationModel < GemStack::Model`
+# would make Sequel look for an "application_models" table.
+ApplicationModel = Class.new(GemStack::Model) # rubocop:disable Style/EmptyClassDefinition
+
+class ApplicationModel
+  # Sequel plugins for every model, e.g.:
+  # plugin :dirty                                    # previous values after an update (column_changes)
+
+  # Shared query helpers:
+  # dataset_module do
+  #   def recent = order(Sequel.desc(:created_at))
+  # end
+end

data/templates/app/app/serializers/application_serializer.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# The base class for this app's serializers (docs/serialization.md): attributes
+# and helpers defined here are shared by every serializer.
+class ApplicationSerializer < GemStack::Serializer
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Development settings: applied after config/app.rb when GEMSTACK_ENV=development
+# (the default). Each line shows the default value — uncomment one to change it.
+# All settings: docs/configuration.md.
+GemStack.configure do |config|
+  # ── Code ────────────────────────────────────────────────────────────────
+  # config.reload_code = true                  # reload app/ and config/routes.rb when they change
+  # config.eager_load = false                  # load app/ lazily, for a faster boot
+  # config.jit = nil                           # :yjit or :zjit to try Ruby's JIT locally
+
+  # ── Logging ─────────────────────────────────────────────────────────────
+  # config.logger.level = :debug               # :debug, :info, :warn, :error (or GEMSTACK_LOG_LEVEL)
+  # config.logger.format = :pretty             # readable lines; :json to see what production logs
+
+  # ── HTTP ────────────────────────────────────────────────────────────────
+  # config.http.show_exceptions = true         # 500s carry the exception; browsers get an error page
+  # config.contract.docs = true                # interactive API docs at /api/docs
+
+  # ── gemstack dev ────────────────────────────────────────────────────────
+  # config.dev.port = 3000                     # the one public port (or PORT)
+  # config.dev.jobs_command = %w[bundle exec gemstack jobs]   # nil: don't start a jobs worker
+<% if database? -%>
+
+  # ── Database (connection: config/database.yml) ──────────────────────────
+  # config.db.log_queries = true               # every SQL statement at DEBUG
+  # config.db.slow_query_ms = 500              # slower queries are logged at WARN
+<% end -%>
+
+  # ── Cache ───────────────────────────────────────────────────────────────
+  # config.cache.store = :memory               # :null to switch caching off, :redis to share it
+
+  # ── Mail ────────────────────────────────────────────────────────────────
+  # config.mail.delivery = :log                # saved to tmp/mail (.eml + .html); :smtp really sends
+end

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/auth/app/mailers/auth_mailer.rb

@@ -2,7 +2,7 @@
 
 # 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
+class AuthMailer < ApplicationMailer
   def password_reset(user_id)
     @user = User[user_id] or return
     token, = GemStack::Auth::Tokens.issue(@user.id, purpose: "password_reset")

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # API tokens (and single-use reset/verification tokens) — see GemStack::Auth::Tokens.
-class AuthToken < GemStack::Model
+class AuthToken < ApplicationModel
   field :purpose, :string, null: false
   field :name, :string, size: 100
   field :last_used_at, :datetime

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

@@ -2,7 +2,7 @@
 
 # Accounts. GemStack::Auth::User adds password hashing (Argon2id), email
 # normalization, validations and User.authenticate_by(email:, password:).
-class User < GemStack::Model
+class User < ApplicationModel
   include GemStack::Auth::User
 
   field :email, :string, null: false, size: 254

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

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class ApiTokenSerializer < GemStack::Serializer
+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

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

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

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

data/templates/frontend/app/page.module.css

@@ -0,0 +1,315 @@
+/* The GemStack welcome page (app/page.tsx). Delete both files when you replace it. */
+
+.shell {
+  --ruby: #e11d48;
+  --violet: #7c3aed;
+  --ink: #16181d;
+  --muted: #5b6170;
+  --surface: rgba(255, 255, 255, 0.72);
+  --border: rgba(22, 24, 29, 0.09);
+  --code: #f3f4f7;
+  --ok: #16a34a;
+  --pending: #d99a1e;
+  --error: #dc2626;
+
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  color: var(--ink);
+  background:
+    radial-gradient(60rem 30rem at 10% -10%, rgba(225, 29, 72, 0.12), transparent 60%),
+    radial-gradient(50rem 30rem at 100% 0%, rgba(124, 58, 237, 0.12), transparent 60%),
+    #fbfbfd;
+}
+
+@media (prefers-color-scheme: dark) {
+  .shell {
+    --ink: #eceef4;
+    --muted: #9aa0ad;
+    --surface: rgba(24, 27, 36, 0.72);
+    --border: rgba(255, 255, 255, 0.08);
+    --code: rgba(255, 255, 255, 0.06);
+    --ok: #4ade80;
+    --pending: #fbbf24;
+    --error: #f87171;
+
+    background:
+      radial-gradient(60rem 30rem at 10% -10%, rgba(225, 29, 72, 0.22), transparent 60%),
+      radial-gradient(50rem 30rem at 100% 0%, rgba(124, 58, 237, 0.22), transparent 60%),
+      #0c0d12;
+  }
+}
+
+.main {
+  flex: 1;
+  width: 100%;
+  max-width: 68rem;
+  margin: 0 auto;
+  padding: clamp(3rem, 8vw, 6rem) 1.25rem 3rem;
+}
+
+/* Hero */
+
+.hero {
+  text-align: center;
+  margin-bottom: clamp(2.5rem, 6vw, 4rem);
+}
+
+.logo {
+  width: 5rem;
+  height: 5rem;
+  filter: drop-shadow(0 12px 24px rgba(225, 29, 72, 0.35));
+  animation: float 6s ease-in-out infinite;
+}
+
+@keyframes float {
+  50% {
+    transform: translateY(-6px) rotate(-2deg);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .logo {
+    animation: none;
+  }
+}
+
+.eyebrow {
+  margin: 1rem 0 0.5rem;
+  font-size: 0.8rem;
+  font-weight: 700;
+  letter-spacing: 0.18em;
+  text-transform: uppercase;
+  color: var(--muted);
+}
+
+.title {
+  margin: 0;
+  font-size: clamp(2.2rem, 6vw, 3.6rem);
+  line-height: 1.1;
+  letter-spacing: -0.03em;
+  font-weight: 800;
+}
+
+.accent {
+  background: linear-gradient(120deg, #ff5f8f, var(--ruby) 45%, var(--violet));
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+}
+
+.lead {
+  max-width: 38rem;
+  margin: 1.1rem auto 0;
+  font-size: clamp(1.02rem, 2.2vw, 1.2rem);
+  color: var(--muted);
+}
+
+.lead strong {
+  color: var(--ink);
+}
+
+/* Live checks */
+
+.checks {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: center;
+  gap: 0.6rem;
+  margin-top: 2rem;
+}
+
+.check {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.55rem;
+  padding: 0.5rem 0.95rem;
+  border: 1px solid var(--border);
+  border-radius: 999px;
+  background: var(--surface);
+  backdrop-filter: blur(8px);
+  font-size: 0.92rem;
+  overflow-wrap: anywhere;
+}
+
+.check code {
+  font-size: 0.85em;
+}
+
+.dot {
+  width: 0.55rem;
+  height: 0.55rem;
+  flex: none;
+  border-radius: 50%;
+  background: currentColor;
+}
+
+.ok .dot {
+  background: var(--ok);
+  box-shadow: 0 0 0 4px color-mix(in srgb, var(--ok) 22%, transparent);
+}
+
+.pending .dot {
+  background: var(--pending);
+  animation: pulse 1.2s ease-in-out infinite;
+}
+
+.error .dot {
+  background: var(--error);
+}
+
+@keyframes pulse {
+  50% {
+    opacity: 0.35;
+  }
+}
+
+/* Cards */
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
+  gap: 1rem;
+}
+
+.card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  padding: 1.4rem;
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  background: var(--surface);
+  backdrop-filter: blur(8px);
+  transition:
+    transform 0.2s ease,
+    border-color 0.2s ease,
+    box-shadow 0.2s ease;
+}
+
+.card:hover {
+  transform: translateY(-2px);
+  border-color: color-mix(in srgb, var(--ruby) 35%, var(--border));
+  box-shadow: 0 16px 40px -24px rgba(225, 29, 72, 0.45);
+}
+
+.step {
+  display: grid;
+  place-items: center;
+  width: 1.9rem;
+  height: 1.9rem;
+  border-radius: 10px;
+  background: linear-gradient(135deg, var(--ruby), var(--violet));
+  color: #fff;
+  font-size: 0.85rem;
+  font-weight: 700;
+}
+
+.cardTitle {
+  margin: 0.3rem 0 0;
+  font-size: 1.08rem;
+}
+
+.cardText {
+  flex: 1;
+  margin: 0;
+  color: var(--muted);
+  font-size: 0.93rem;
+  line-height: 1.5;
+}
+
+.command {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.5rem;
+  padding: 0.55rem 0.6rem 0.55rem 0.8rem;
+  border-radius: 10px;
+  background: var(--code);
+  font-size: 0.82rem;
+}
+
+.command code {
+  flex: 1;
+  min-width: 0;
+  padding: 0.15rem 0 0;
+  background: none;
+  line-height: 1.5;
+  overflow-wrap: anywhere; /* long commands wrap instead of being cut off */
+}
+
+.prompt {
+  color: var(--ruby);
+  user-select: none;
+}
+
+.copy {
+  flex: none;
+  padding: 0.25rem 0.6rem;
+  border: 1px solid var(--border);
+  border-radius: 7px;
+  background: transparent;
+  color: var(--ink);
+  font: inherit;
+  font-size: 0.75rem;
+  cursor: pointer;
+}
+
+.copy:hover,
+.copy:focus-visible {
+  border-color: var(--ruby);
+  color: var(--ruby);
+}
+
+.link {
+  align-self: flex-start;
+  color: var(--ruby);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.link:hover,
+.link:focus-visible {
+  text-decoration: underline;
+}
+
+.edit {
+  margin: 2.5rem 0 0;
+  text-align: center;
+  color: var(--muted);
+  font-size: 0.92rem;
+}
+
+/* Footer */
+
+.footer {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 0.5rem 1.5rem;
+  width: 100%;
+  max-width: 68rem;
+  margin: 0 auto;
+  padding: 1.5rem 1.25rem 2rem;
+  border-top: 1px solid var(--border);
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.footer a {
+  color: var(--ink);
+  font-weight: 600;
+  text-decoration: none;
+}
+
+.footer a:hover,
+.footer a:focus-visible {
+  color: var(--ruby);
+}
+
+@media (max-width: 40rem) {
+  .footer {
+    justify-content: center;
+    text-align: center;
+  }
+}

data/templates/frontend/app/page.tsx.tt

@@ -1,45 +1,183 @@
 "use client";
 
 import { useQuery } from "@tanstack/react-query";
+import { useState } from "react";
 import { api, API_PATH } from "@/lib/gemstack/client";
+import styles from "./page.module.css";
 
-// Starter page: confirms the browser reaches the Ruby API through the same origin.
-// Replace it with your application.
-export default function Home() {
+// The GemStack welcome page: shows that Next.js renders and that the browser
+// reaches the Ruby API through the same origin. Replace it with your app —
+// this file and app/page.module.css are yours to delete.
+
+const DOCS = "https://github.com/gemstack-rb/gemstack/tree/main/docs";
+
+export default function Welcome() {
   const health = useQuery({
-    queryKey: ["health"],
-    queryFn: () => api.get<{ status: string }>("/health"),
+    queryKey: ["gemstack", "health"],
+    queryFn: async () => {
+      const started = performance.now();
+      const body = await api.get<{ status: string }>("/health");
+      return { ...body, ms: Math.round(performance.now() - started) };
+    },
+    retry: 1,
   });
+  const apiState = health.isPending ? "pending" : health.isError ? "error" : "ok";
+
+  return (
+    <div className={styles.shell}>
+      <main className={styles.main}>
+        <header className={styles.hero}>
+          <GemLogo className={styles.logo} />
+          <p className={styles.eyebrow}>GemStack</p>
+          <h1 className={styles.title}>
+            Yay! You&apos;re on <span className={styles.accent}>GemStack</span>.
+          </h1>
+          <p className={styles.lead}>
+            <strong><%= module_name %></strong> is running: a Next.js frontend and a Ruby API, served from one origin.
+          </p>
+
+          <div className={styles.checks} role="status" aria-live="polite">
+            <span className={`${styles.check} ${styles.ok}`}>
+              <span className={styles.dot} aria-hidden="true" /> Next.js rendering
+            </span>
+            <span className={`${styles.check} ${styles[apiState]}`}>
+              <span className={styles.dot} aria-hidden="true" />
+              {apiState === "pending" && "Connecting to the Ruby API…"}
+              {apiState === "ok" && (
+                <>
+                  Ruby API connected · <code>GET {API_PATH}/health</code> in {health.data?.ms} ms
+                </>
+              )}
+              {apiState === "error" && <>Ruby API unreachable: {health.error?.message}</>}
+            </span>
+          </div>
+        </header>
 
-  const state = health.isPending ? "pending" : health.isError ? "error" : "ok";
-  const label = {
-    pending: "Connecting to the Ruby API…",
-    error: `Ruby API unreachable: ${health.error?.message}`,
-    ok: `Ruby API connected — GET ${API_PATH}/health → ${health.data?.status}`,
-  }[state];
+        <section className={styles.grid} aria-label="Next steps">
+          <Card
+            step="1"
+            title="Generate a resource"
+            text="Migration, model, API, typed TypeScript client and Next.js pages — in one command."
+            command="gemstack g resource Product name:string"
+          />
+          <Card
+            step="2"
+            title="Explore your API"
+            text="Every endpoint with its types, and a form to try requests from the browser."
+            href={`${API_PATH}/docs`}
+            linkLabel={`Open ${API_PATH}/docs`}
+          />
+          <Card
+            step="3"
+            title="Check your setup"
+            text="Ruby, Node.js, the database, migrations and the TypeScript contract — with the fix for anything off."
+            command="gemstack doctor"
+          />
+          <Card
+            step="4"
+            title="Read the guides"
+            text="Models, controllers, jobs, realtime, authentication, storage and deployment."
+            href={DOCS}
+            linkLabel="Open the guides"
+            external
+          />
+        </section>
+
+        <p className={styles.edit}>
+          Edit <code>frontend/app/page.tsx</code> to replace this page · API code lives in <code>app/</code>
+        </p>
+      </main>
+
+      <footer className={styles.footer}>
+        <span>
+          GemStack <%= version %> · Ruby <%= ruby_version %> · Next.js
+        </span>
+        <span>
+          Open source by{" "}
+          <a href="https://www.adwaretech.com" target="_blank" rel="noreferrer">
+            Adware Technologies
+          </a>
+        </span>
+      </footer>
+    </div>
+  );
+}
+
+function Card(props: {
+  step: string;
+  title: string;
+  text: string;
+  command?: string;
+  href?: string;
+  linkLabel?: string;
+  external?: boolean;
+}) {
+  return (
+    <article className={styles.card}>
+      <span className={styles.step} aria-hidden="true">
+        {props.step}
+      </span>
+      <h2 className={styles.cardTitle}>{props.title}</h2>
+      <p className={styles.cardText}>{props.text}</p>
+      {props.command && <Command text={props.command} />}
+      {props.href && (
+        <a
+          className={styles.link}
+          href={props.href}
+          {...(props.external ? { target: "_blank", rel: "noreferrer" } : {})}
+        >
+          {props.linkLabel} <span aria-hidden="true">→</span>
+        </a>
+      )}
+    </article>
+  );
+}
+
+function Command({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false);
+  async function copy() {
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    } catch {
+      // Clipboard unavailable (e.g. not a secure context): the command stays selectable.
+    }
+  }
+  return (
+    <div className={styles.command}>
+      <code>
+        <span className={styles.prompt} aria-hidden="true">
+          $
+        </span>{" "}
+        {text}
+      </code>
+      <button type="button" className={styles.copy} onClick={copy} aria-label={`Copy: ${text}`}>
+        {copied ? "Copied" : "Copy"}
+      </button>
+    </div>
+  );
+}
 
+function GemLogo({ className }: { className?: string }) {
   return (
-    <main className="page">
-      <h1><%= module_name %></h1>
-      <p className="muted">Next.js + TypeScript frontend, GemStack Ruby API, one origin.</p>
-
-      <p className={`status status-${state}`} role="status">
-        <span className="dot" aria-hidden="true" />
-        {label}
-      </p>
-
-      <h2>Next steps</h2>
-      <ul>
-        <li>
-          Add an endpoint: <code>gemstack generate controller Status show</code>
-        </li>
-        <li>
-          Call it from here: <code>api.get(&quot;/status/1&quot;)</code> (see <code>lib/gemstack/client.ts</code>)
-        </li>
-        <li>
-          Edit this page: <code>frontend/app/page.tsx</code>
-        </li>
-      </ul>
-    </main>
+    <svg className={className} viewBox="0 0 64 64" role="img" aria-label="GemStack">
+      <defs>
+        <linearGradient id="gemstack-gem" x1="0" y1="0" x2="1" y2="1">
+          <stop offset="0" stopColor="#ff5f8f" />
+          <stop offset="0.55" stopColor="#e11d48" />
+          <stop offset="1" stopColor="#7c3aed" />
+        </linearGradient>
+      </defs>
+      <path d="M18 8h28l12 15-26 34L6 23z" fill="url(#gemstack-gem)" />
+      <path
+        d="M6 23h52M18 8l7 15 7-15 7 15 7-15M25 23l7 34 7-34"
+        fill="none"
+        stroke="rgba(255,255,255,0.55)"
+        strokeWidth="1.4"
+        strokeLinejoin="round"
+      />
+      <path d="M18 8h28l-7 15H25z" fill="rgba(255,255,255,0.18)" />
+    </svg>
   );
 }

data/templates/job/app/jobs/%file_name%.rb.tt

@@ -2,7 +2,7 @@
 
 # Enqueue with <%= class_name %>.perform_later(...) — arguments must be JSON values (pass ids, not records).
 # Runs in `gemstack jobs` (and in `gemstack dev`). Delivery is at-least-once: keep perform idempotent.
-class <%= class_name %> < GemStack::Job
+class <%= class_name %> < ApplicationJob
 <% if queue_name -%>
   queue :<%= queue_name %>
 <% end -%>

data/templates/resource/model/app/models/%file_name%.rb.tt

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-class <%= class_name %> < GemStack::Model
+class <%= class_name %> < ApplicationModel
 <% fields.each do |field| -%>
   <%= model_field(field) %>
 <% end -%>

data/templates/resource/serializer/app/serializers/%file_name%_serializer.rb.tt

@@ -2,6 +2,6 @@
 
 # What the API returns for a <%= class_name %>. Only listed attributes are exposed;
 # their types (from <%= class_name %>'s fields) drive the generated TypeScript types.
-class <%= class_name %>Serializer < GemStack::Serializer
+class <%= class_name %>Serializer < ApplicationSerializer
   attributes :id, <%= fields.map { |f| ":#{f.column}" }.join(", ") %>, :created_at, :updated_at
 end

data/templates/storage/app/serializers/upload_serializer.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Where and how the browser sends the file (see UploadsController).
-class UploadSerializer < GemStack::Serializer
+class UploadSerializer < ApplicationSerializer
   Result = Data.define(:signed_id, :url, :http_method, :headers)
 
   attribute :signed_id, :string

metadata

@@ -1,9 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: gemstack-cli
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
+- Adware Technologies
 - Shoaib Malik
 bindir: exe
 cert_chain: []
@@ -15,28 +16,28 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.2
 - !ruby/object:Gem::Dependency
   name: gemstack-dev
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 0.2.0
+        version: 0.2.2
 - !ruby/object:Gem::Dependency
   name: thor
   requirement: !ruby/object:Gem::Requirement
@@ -80,13 +81,18 @@ files:
 - templates/app/Gemfile.tt
 - templates/app/README.md.tt
 - templates/app/app/controllers/application_controller.rb
+- templates/app/app/jobs/application_job.rb
+- templates/app/app/mailers/application_mailer.rb
+- templates/app/app/mailers/templates/dot_keep
+- templates/app/app/models/application_model.rb
+- templates/app/app/serializers/application_serializer.rb
 - templates/app/bin/gemstack
 - templates/app/config.ru
 - templates/app/config/app.rb.tt
 - templates/app/config/database.yml.tt
-- templates/app/config/environments/development.rb
-- templates/app/config/environments/production.rb
-- templates/app/config/environments/test.rb
+- templates/app/config/environments/development.rb.tt
+- templates/app/config/environments/production.rb.tt
+- templates/app/config/environments/test.rb.tt
 - templates/app/config/puma.rb
 - templates/app/config/routes.rb
 - templates/app/db/migrations/dot_keep
@@ -134,6 +140,7 @@ files:
 - templates/deploy/dot_dockerignore
 - templates/frontend/app/globals.css
 - templates/frontend/app/layout.tsx.tt
+- templates/frontend/app/page.module.css
 - templates/frontend/app/page.tsx.tt
 - templates/frontend/app/providers.tsx
 - templates/frontend/lib/gemstack/client.ts

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

@@ -1,6 +0,0 @@
-# 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

@@ -1,8 +0,0 @@
-# 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

@@ -1,7 +0,0 @@
-# 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