hamster-web 0.1.0.pre.2 → 0.1.0.pre.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da9a6aefcced6e728e844a09b04ebaab4d6970b0742b9e527be34c36bcc52de1
-  data.tar.gz: f063de9bfdd15a06f17992ed6efd23cb6e3ad50fbe99195ec2e82718e11b2aef
+  metadata.gz: ad523636ae12bea5f7c62d7ba64c1f9f343340c3c73952d086cb88ad003ebb33
+  data.tar.gz: 8b09067b4f17a7a5031f20b543e9ac8564b63319252c1cfb991da4bf4de0b321
 SHA512:
-  metadata.gz: 1a06018d216e769b046d6ec6614ff110ab61fce962de8f35d38ee96a8cccbbf67fe73c5d1c6885e225e8f76b5757ef56b5a4b8f18f6f208fc7c2570a1e3b2a3c
-  data.tar.gz: 47d17563010f3acb9f3b678dd9c2027e2ebedb38cc31b7d28c4abecab57fa994f696a8d72f8551006dc7c5d374ebb36f37431ac466e910e1b0b0cc28b66b8ae9
+  metadata.gz: a714e1f4112d612d6123ee30b7febcb5f5b7eac0138d7c8a01e6b969656654c32dac6e2995aa54bd692131d9e323da62480b3904082cd11512784d04409688ca
+  data.tar.gz: 7df33a2df961b34d348399c1d6a3e2051457811f3de7543c76eaa6c5c73099ed3bd6c37234d1bcd38ac4efafdcf28d3b65eb911116e59c43bbeae4b7f4db98f8

data/README.md

@@ -9,11 +9,11 @@ actions, compiled views, and SQL migrations. Database creation and migration
 commands, the console, and schema-aware records/queries are available.
 Telemetry extraction and asset delivery remain under development.
 
-Build and install the local framework preview:
+Install the public framework preview from RubyGems:
 
 ```sh
-gem build hamster-web.gemspec
-gem install --local hamster-web-0.1.0.pre.2.gem
+gem install bundler --version 2.5.23
+gem install hamster-web --version 0.1.0.pre.3
 hamster new MyApp
 cd my_app
 bin/hamster setup
@@ -28,7 +28,7 @@ bin/hamster build
 bin/hamster serve
 ```
 
-Run framework tests with `ruby -Ilib -e 'Dir["test/*_test.rb"].sort.each { |file| require_relative file }'`.
+Run framework tests with `ruby -Ilib -e 'Dir["test/*_test.rb"].sort.each { |file| require File.expand_path(file) }'`.
 
 ## Records and queries
 
@@ -59,3 +59,103 @@ configured PostgreSQL database. It reports missing tables/columns, incompatible
 types, and unexpected nullability with a nonzero exit status. It never migrates
 or modifies the schema. Configuration is loaded through config/commands.rb,
 a CRuby-only adapter generated with new applications.
+
+## Installation contract and Linux verification
+
+The clean-install gate targets Ruby 3.3.6, Bundler 2.5.23, Hamster
+0.1.0.pre.3, Spinner 0.1.0.pre.1, PostgreSQL 16.6, and unmodified Spinel/Spin
+revision `10f112c51666e7ffd308e0ab90a69c2184870c06`. The exact CI inputs live
+in `script/ci/versions.env`; Linux compatibility is verified by the native
+smoke workflow. This pin does not include the experimental benchmark runtime.
+
+The server gem is named `spinel-spinner`; Ruby application code uses
+`require "spinner"` and the `Spinner` namespace. Hamster installs it as a
+separate, exact-version dependency. The RubyGems package named `spinner` is
+unrelated. Neither framework gem bundles a compiler or a precompiled server.
+
+Spinel and its `spin` project tool must be installed before app setup. On
+Debian Bookworm, install `build-essential`, `ca-certificates`, `curl`, `git`,
+`pkg-config`, `libffi-dev`, and `libssl-dev`. PostgreSQL must be available;
+`postgresql-client` provides the smoke test's `psql` checks. Build the pinned
+upstream toolchain into a dedicated installation prefix:
+
+```sh
+git clone https://github.com/matz/spinel.git
+cd spinel
+git checkout --detach 10f112c51666e7ffd308e0ab90a69c2184870c06
+make deps
+make -j2
+make install PREFIX="$HOME/.local"
+export PATH="$HOME/.local/bin:$PATH"
+spinel --version
+spin --version
+```
+
+Then run the app generation commands above from an empty directory. Setup
+fetches the PostgreSQL driver revision in the generated `spin.lock` from
+`https://github.com/rubys/spinel-pg`. RubyGems and GitHub network access are
+required. Configure `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`,
+`DATABASE_USERNAME`, and `DATABASE_PASSWORD` for your PostgreSQL server.
+`DATABASE_ADMIN_NAME` defaults to `postgres`; administrative credentials default
+to the application credentials and need permission to create the database.
+The generated README describes the defaults and build/serve commands.
+
+To build a local framework preview instead of installing the public package:
+
+```sh
+gem build hamster-web.gemspec
+gem install --local hamster-web-0.1.0.pre.3.gem
+```
+
+Run the clean Linux gate locally with Docker running (no local PostgreSQL or
+Spinel installation needed):
+
+```sh
+# Public packages, installed directly from RubyGems:
+bash script/ci/run_native_smoke.sh published
+
+# Candidate gem built from this checkout, plus published Spinner:
+mkdir -p tmp
+gem build hamster-web.gemspec --output tmp/hamster-web.gem
+bash script/ci/run_native_smoke.sh candidate tmp/hamster-web.gem
+```
+
+Each invocation builds an image without caches, installs the compiler from its
+pinned upstream source, and tests in a separate consumer image containing no
+Hamster/Spinner checkout. Only the CI harness and optional candidate gem enter
+that environment. Gems, Bundler settings, and the generated app use fresh
+isolated directories. Package resolution must stay within that gem installation.
+The test creates a disposable database, applies a real migration twice, checks
+its effects and tracking, compiles the app, and asserts HTTP 200 and welcome
+content from the native executable. Containers, their processes, networks, and
+the tagged test image are removed on exit. Docker retains image build layers;
+no restored layers are used by the gate.
+
+Logs, lockfiles, resolved package paths, and HTTP output are retained under
+`tmp/native-smoke-<mode>/` (override with `SMOKE_ARTIFACTS_DIR`). GitHub Actions
+uploads those diagnostics even on failure. Pull requests and main test the
+candidate package; weekly and manually triggered runs also test published
+packages. Public pins are advanced deliberately when releases are available.
+
+## Generated deployment images
+
+New applications include a multi-stage `Dockerfile`, `.dockerignore`, and a
+`GET /up` liveness endpoint. Build with `docker build -t my_app .`; no host Ruby,
+Spinel, or database is needed. The default image runs the native executable as
+UID 10001 on port 4000, with shared libraries, migrations and public assets only.
+Ruby and the compiler are confined to build/operational stages.
+
+Build `--target migrations` separately and run that image's `db:migrate`
+command with database settings supplied at runtime before deploying the native
+image. Migrations never run during image build or server startup. `/up` bypasses
+database checkout after the application's initial database/migration verification,
+so it reports process liveness rather than database readiness. The generated
+README includes deployment commands, environment settings and shutdown semantics.
+
+Run `bash script/ci/run_app_docker_smoke.sh` to verify the generated image using
+Docker alone. It packages and installs the current framework inside a temporary
+container, generates an app, builds before creating any database, checks secret
+exclusions and runtime linkage, applies a real migration, verifies HTTP and Docker
+health checks as a non-root user without Ruby/Spinel, stops PostgreSQL to test
+liveness, and verifies clean SIGTERM shutdown. Diagnostics are retained in
+`tmp/app-docker-smoke/`. This runs as a separate job in the native smoke workflow.

data/lib/hamster/cli.rb

@@ -44,6 +44,13 @@ module Hamster
       end
     end
 
+    def self.require_tool!(executable, instruction)
+      paths = executable.include?(File::SEPARATOR) ? [executable] : ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |directory| File.join(directory, executable) }
+      return if paths.any? { |path| File.file?(path) && File.executable?(path) }
+
+      raise "Required executable #{executable.inspect} was not found; #{instruction}"
+    end
+
     def self.dispatch(command)
       app_root = root
       metadata = JSON.parse(File.read(File.join(app_root, "config/hamster.json")))
@@ -63,10 +70,13 @@ module Hamster
           Console.run(ApplicationCommands.build)
         end
       when "setup"
+        require_tool!("bundle", "install Bundler with gem install bundler")
+        require_tool!("spin", "install the supported Spinel toolchain (including spin); see the Hamster README") if File.file?(File.join(app_root, "spin.toml"))
         Dir.chdir(app_root) { raise "Dependency installation failed" unless system("bundle", "install") }
         Dir.chdir(app_root) { raise "Spin dependency vendoring failed" unless system("spin", "vendor") } if File.file?(File.join(app_root, "spin.toml"))
         Build::PostgresCompatibility.apply(app_root) if File.file?(File.join(app_root, "spin.toml"))
       when "db:create", "db:migrate"
+        require_tool!("spin", "install the supported Spinel toolchain and run bin/hamster setup")
         output, status = Open3.capture2e("spin", "list", "--json", chdir: app_root)
         raise "Cannot resolve PostgreSQL dependency: #{output}" unless status.success?
         pg = JSON.parse(output).find { |package| package["name"] == "pg" }
@@ -95,6 +105,9 @@ module Hamster
         raise issues.join("\n") unless issues.empty?
         puts "Manifest check passed"
       when "build"
+        compiler = ENV.fetch("SPINEL", "spinel")
+        require_tool!(compiler, "install the supported Spinel toolchain or set SPINEL to its compiler path; see the Hamster README")
+        require_tool!("spin", "install the supported Spinel toolchain (including spin)") if File.file?(File.join(app_root, "spin.toml"))
         Build::PostgresCompatibility.apply(app_root) if File.file?(File.join(app_root, "spin.toml"))
         Build::Manifest.generate(app_root)
         issues = Build::Manifest.check(app_root)
@@ -109,7 +122,7 @@ module Hamster
               raise "Spin dependency resolution failed: #{diagnostic}" unless status.success?
               flags.concat(Shellwords.split(output))
             end
-            raise "Spinel compilation failed" unless system(ENV.fetch("SPINEL", "spinel"), "bin/server", *flags, "-o", temporary)
+            raise "Spinel compilation failed" unless system(compiler, "bin/server", *flags, "-o", temporary)
           end
           File.rename(temporary, binary)
         ensure

data/lib/hamster/web/version.rb

@@ -2,6 +2,6 @@
 
 module Hamster
   module Web
-    VERSION = "0.1.0.pre.2"
+    VERSION = "0.1.0.pre.3"
   end
 end

data/templates/app/.dockerignore

@@ -0,0 +1,18 @@
+.git
+.bundle
+vendor
+node_modules
+tmp
+log
+coverage
+*.gem
+bin/*-server
+bin/*.tmp
+**/.env
+**/.env.*
+**/*.key
+**/*.pem
+**/credentials.yml.enc
+README.md
+AGENTS.md
+test

data/templates/app/AGENTS.md

@@ -1,6 +1,6 @@
 # Application conventions
 
-- Keep one action per endpoint directory with a sibling view.html.erb.
+- Keep one action per endpoint directory; HTML responses can use a sibling view.html.erb.
 - Declare routes in app/routes/mappings.rb.
 - App Ruby files load through config/manifest.rb; do not add local requires.
 - Run bin/hamster manifest after editing application Ruby files or templates.

data/templates/app/Dockerfile

@@ -0,0 +1,53 @@
+# Build with Docker only; Spinel and Ruby are installed inside the builder.
+ARG RUBY_IMAGE=ruby:3.3.6-bookworm@sha256:347edd0c70ee08d87de9f01b99de2f14a64cedb5d1bfb38457dfe8cd0bf113c5
+ARG RUNTIME_IMAGE=debian:bookworm-slim@sha256:99c0b25c46d0214d5a2091092e7908907dcaecd6a962cde0ac700acee222b6f3
+FROM ${RUBY_IMAGE} AS toolchain
+ARG SPINEL_REVISION=10f112c51666e7ffd308e0ab90a69c2184870c06
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential ca-certificates curl git libffi-dev libssl-dev pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+RUN mkdir /src && cd /src && git init \
+    && git remote add origin https://github.com/matz/spinel.git \
+    && git fetch --depth 1 origin "$SPINEL_REVISION" && git checkout --detach FETCH_HEAD \
+    && test "$(git rev-parse HEAD)" = "$SPINEL_REVISION" \
+    && make deps && make -j2 && make install PREFIX=/opt/spinel \
+    && rm -rf /src
+ENV PATH="/opt/spinel/bin:${PATH}"
+RUN gem install bundler --version 2.5.23 --no-document \
+    && gem install hamster-web --version __HAMSTER_VERSION__ --no-document
+
+FROM toolchain AS builder
+WORKDIR /app
+COPY . .
+# Setup and compilation require no database connection or credentials.
+RUN bin/hamster setup && bin/hamster manifest && bin/hamster manifest:check && bin/hamster build
+RUN mkdir -p /runtime/app/bin /runtime/app/db/migrations /runtime/app/public \
+    && cp bin/__APP_NAME__-server /runtime/app/bin/ \
+    && cp -a db/migrations/. /runtime/app/db/migrations/ \
+    && cp -a public/. /runtime/app/public/ \
+    && ldd bin/__APP_NAME__-server > /runtime/ldd.txt \
+    && cat /runtime/ldd.txt && ! grep -F 'not found' /runtime/ldd.txt
+
+# Optional operational image. Migrations run explicitly, never during build/boot.
+FROM builder AS migrations
+ENV HAMSTER_APP_ROOT=/app HAMSTER_ENV=production
+ENTRYPOINT ["bin/hamster"]
+CMD ["db:migrate"]
+
+FROM ${RUNTIME_IMAGE} AS runtime
+# Runtime libraries and a small HTTP health probe; no Ruby, gems or compiler.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ca-certificates curl libcrypt1 libffi8 libssl3 \
+    && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --from=builder /runtime/app/ /app/
+# Check linkage in the actual runtime image as well as in the builder.
+RUN ldd /app/bin/__APP_NAME__-server > /tmp/ldd.txt \
+    && cat /tmp/ldd.txt && ! grep -F 'not found' /tmp/ldd.txt && rm /tmp/ldd.txt
+ENV HAMSTER_APP_ROOT=/app HAMSTER_ENV=production HOST=0.0.0.0 PORT=4000
+USER 10001:10001
+EXPOSE 4000
+STOPSIGNAL SIGTERM
+HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 \
+    CMD curl --fail --silent --show-error --max-time 2 "http://127.0.0.1:${PORT}/up" > /dev/null || exit 1
+ENTRYPOINT ["/app/bin/__APP_NAME__-server"]

data/templates/app/README.md

@@ -1,7 +1,13 @@
 # __APP_NAME__
 
 Run `bin/hamster setup` to install gems and vendor the locked Spin PostgreSQL driver.
-Spin and Spinel must already be installed. Configure DATABASE_USERNAME,
+Spin and Spinel must already be installed. The preview installation contract is
+Ruby 3.3.6, Bundler 2.5.23, Hamster __HAMSTER_VERSION__, spinel-spinner
+0.1.0.pre.1, and Spinel/Spin revision
+`10f112c51666e7ffd308e0ab90a69c2184870c06`. See the framework README at
+https://github.com/dostaglou/hamster-web for compiler installation prerequisites.
+Spinner's gem name is `spinel-spinner`; application code uses `require "spinner"`.
+Both gems are available from https://rubygems.org. Configure DATABASE_USERNAME,
 DATABASE_PASSWORD, and optionally DATABASE_HOST and DATABASE_PORT for your local
 PostgreSQL server. DATABASE_NAME defaults to __APP_NAME___development.
 
@@ -14,7 +20,7 @@ then `bin/hamster serve`. Build does not require a database connection.
 An empty migration directory is valid; db:migrate initializes migration tracking.
 The server listens on http://127.0.0.1:4000 by default; configure HOST and PORT
 to override it. During framework development, install the local hamster-web
-gem before running setup.
+gem before running setup. Otherwise the pinned framework is installed from RubyGems.
 
 Run a deployed binary from the application root or set HAMSTER_APP_ROOT.
 Include db/migrations alongside the binary. PostgreSQL TLS is not supported
@@ -30,3 +36,60 @@ Each endpoint has an action.rb and optional view.html.erb in app/routes/.
 Declare endpoints centrally in app/routes/mappings.rb. Run
 `bin/hamster manifest` after changing Ruby sources or templates and commit
 the generated manifest and view registry with your source changes.
+
+## Docker deployment
+
+The generated Dockerfile builds the Spinel compiler and `spin` at the pinned
+revision, installs the framework from RubyGems, runs setup and manifest checks,
+and compiles your application. Docker is the only build prerequisite on the
+host. Commit `Gemfile.lock` and `spin.lock` to keep dependency resolution stable.
+No database or database credentials are needed to build either target.
+
+```sh
+docker build -t __APP_NAME__:latest .
+docker build --target migrations -t __APP_NAME__:migrations .
+```
+
+The default image uses Debian Bookworm slim and UID/GID 10001. It contains the
+native executable, shared runtime libraries, SQL migrations and `public/`;
+Ruby, gems, Spinel, application source and build tools stay in the builder.
+Both builder and runtime verify the executable's shared library linkage with
+`ldd`. Public files are retained for application-managed assets; the image does
+not add an asset-serving route.
+
+Provide database settings at container runtime, for example in an uncommitted
+`.env.production` file. Set `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`,
+`DATABASE_USERNAME`, and `DATABASE_PASSWORD`. The production database name
+defaults to `__APP_NAME___production`. The database must already exist; use
+`db:create` with separate administrative credentials only when provisioning it.
+The Docker context excludes `.env` files, private keys, local gems, compiled
+host binaries, and local Bundler settings. Keep credentials out of Ruby source
+and Docker build arguments as well.
+
+Apply migrations explicitly as a deployment step, then start the native image:
+
+```sh
+docker run --rm --env-file .env.production __APP_NAME__:migrations
+docker run -d --name __APP_NAME__ --env-file .env.production -p 4000:4000 __APP_NAME__:latest
+```
+
+The `migrations` target includes Ruby and build dependencies for the existing
+Hamster CLI; it is a separate operational image. Its default command is
+`db:migrate`, and an explicit argument can select another command. Neither
+image build nor native server startup applies migrations. Startup verifies the
+configured database and rejects missing migration tracking or pending migrations.
+
+The runtime sets `HAMSTER_APP_ROOT=/app`, `HAMSTER_ENV=production`,
+`HOST=0.0.0.0` and `PORT=4000`. Override `PORT` and the port mapping together if
+needed. The executable runs directly as PID 1 and receives SIGTERM. Allow its
+graceful shutdown time when stopping it, for example `docker stop -t 20 __APP_NAME__`.
+Only temporary storage needs to be writable; the CI smoke test runs with a
+read-only root filesystem and a writable `/tmp`.
+
+`GET /up` returns HTTP 200 with `OK` after successful startup. This is liveness:
+it checks HTTP dispatch without checking out a database connection. A later
+database outage does not make `/up` fail. It is not a readiness check or a
+promise that application requests can reach PostgreSQL. The route is declared
+in `app/routes/mappings.rb`, and `app/application.rb` bypasses the normal
+database checkout for that path. The Docker health check calls `/up` using the
+configured `PORT`.

data/templates/app/app/application.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+module __APP_MODULE__
+  class Application < Hamster::Application
+    def initialize(routes:, database:)
+      super(routes: routes, database: database)
+      @liveness_router = Hamster::Router.new(routes)
+    end
+
+    def call(env)
+      # Liveness checks process/HTTP dispatch only, even during a DB outage.
+      return @liveness_router.call(env) if env.fetch("PATH_INFO", "/") == "/up"
+      super
+    end
+  end
+end

data/templates/app/app/routes/mappings.rb

@@ -3,6 +3,7 @@ module __APP_MODULE__
   module Routes
     class Mappings < Hamster::Routing::Base
       get "/", to: Home::Index::Action, as: :root
+      get "/up", to: Up::Index::Action, as: :up
     end
   end
 end

data/templates/app/app/routes/up/index/action.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+module __APP_MODULE__
+  module Routes
+    module Up
+      module Index
+        class Action < Hamster::Action::Base
+          def call
+            respond(body: "OK\n", headers: {"content-type" => "text/plain; charset=utf-8"})
+          end
+        end
+      end
+    end
+  end
+end

data/templates/app/config/application.rb

@@ -9,7 +9,7 @@ module __APP_MODULE__
     database = Hamster::Database.new(database_configuration, migrations_path: File.join(root, "db/migrations"))
     begin
       database.verify!
-      Hamster::Application.new(routes: Routes::Mappings, database: database)
+      Application.new(routes: Routes::Mappings, database: database)
     rescue StandardError
       database.shutdown
       raise

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hamster-web
 version: !ruby/object:Gem::Version
-  version: 0.1.0.pre.2
+  version: 0.1.0.pre.3
 platform: ruby
 authors:
 - Dillon Wyatt
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-10-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: spinel-spinner
@@ -93,13 +94,17 @@ files:
 - lib/hamster/web/version.rb
 - lib/hamster/web/view.rb
 - lib/hamster/web/view/form.rb
+- templates/app/.dockerignore
 - templates/app/.gitignore
 - templates/app/AGENTS.md
+- templates/app/Dockerfile
 - templates/app/Gemfile
 - templates/app/README.md
+- templates/app/app/application.rb
 - templates/app/app/routes/home/index/action.rb
 - templates/app/app/routes/home/index/view.html.erb
 - templates/app/app/routes/mappings.rb
+- templates/app/app/routes/up/index/action.rb
 - templates/app/app/views/layouts/application.html.erb
 - templates/app/bin/hamster
 - templates/app/bin/server
@@ -108,11 +113,14 @@ files:
 - templates/app/config/database.rb
 - templates/app/config/hamster.json
 - templates/app/db/migrations/.keep
+- templates/app/public/.keep
 - templates/app/spin.lock
 - templates/app/spin.toml
+homepage:
 licenses:
 - MIT
 metadata: {}
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -127,7 +135,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.23
+rubygems_version: 3.5.16
+signing_key:
 specification_version: 4
 summary: A Spinel web framework and application generator
 test_files: []