develoz-rails 0.1.0

data/.tool-versions

@@ -0,0 +1,2 @@
+ruby 4.0.5
+nodejs 24.15.0

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-15
+
+### Added
+
+- Initial `develoz` CLI with interactive and `--yes` application generation.
+- Ruby and Rails version resolution for new Rails 8.1 applications.
+- Core generators for tooling, testing, the Solid stack, CI, PostgreSQL,
+  shared concerns, strict loading, maintenance tasks, frontend conventions,
+  documentation, and application versioning.
+- Opt-in generators for APIs, authentication, PWA support, push
+  notifications, Active Resource, admin interfaces, Develoz UI, Kamal,
+  Docker, and database backups.
+- Pagy pagination by default with a `--skip-pagy` opt-out.
+- Canonical fixture fidelity tests and a full RSpec, coverage, and RuboCop CI
+  workflow.
+
+[Unreleased]: https://github.com/develoz-com/rails-template/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/develoz-com/rails-template/releases/tag/v0.1.0

data/CONTRIBUTING.md

@@ -0,0 +1,120 @@
+# Contributing
+
+Contributions should preserve the generator's two main guarantees: a fresh
+application is reproducible, and generated files remain faithful to their
+canonical sources.
+
+## Development setup
+
+The repository uses [asdf](https://asdf-vm.com/) and pins Ruby 4.0.5 and
+Node.js 24.15.0 in `.tool-versions`.
+
+From the repository root:
+
+```bash
+asdf install
+ruby --version
+bundle install
+```
+
+The Ruby version output should start with `ruby 4.0.5`. `bin/setup` is also
+available as a wrapper around `bundle install`.
+
+Run a focused spec while developing, then run the complete checks before
+submitting a change:
+
+```bash
+bundle exec rspec spec/path/to/spec.rb
+./bin/ci
+```
+
+`./bin/ci` runs the full RSpec suite followed by RuboCop and exits on the first
+failure. RSpec also enforces 100% line and branch coverage through SimpleCov,
+so the coverage gate is part of every full CI run.
+
+## Canonical fixtures
+
+Canonical fixtures are byte-for-byte copies of files from source repositories.
+Templates may adapt those files with documented substitutions, while fidelity
+specs compare rendered output with the committed fixture using
+`match_canonical`.
+
+To refresh the configured sources:
+
+```bash
+bundle exec rake develoz:fetch_canonical
+```
+
+Private sources require authentication through `GH_TOKEN` or `gh auth token`.
+The complete source-to-template map is in
+`templates/CANONICAL_SOURCES.md`.
+
+When adding or updating a canonical template:
+
+1. Add or update its source mapping in `lib/tasks/canonical.rake`.
+2. Run `bundle exec rake develoz:fetch_canonical` rather than editing the
+   downloaded fixture by hand.
+3. Store the source under `spec/fixtures/canonical/<owner>-<repo>/`.
+4. Add the `.tt` template and record any substitutions in
+   `templates/CANONICAL_SOURCES.md`.
+5. Add or update a spec in `spec/fidelity/` that uses `match_canonical`.
+6. Run `./bin/ci` and include the refreshed fixture with the change.
+
+## Adding a generator
+
+Use an existing generator with similar behavior as the starting point. A
+generator named `example` follows this layout:
+
+```text
+lib/generators/develoz/example/
+  example_generator.rb
+  templates/
+```
+
+The class must be named `Develoz::Generators::ExampleGenerator`, inherit from
+`Develoz::Generators::Base`, and set its `source_root` to the adjacent
+`templates` directory. Generator lifecycle methods are public; implementation
+helpers are private. Use the base class helpers for idempotent Gemfile, route,
+environment, and file changes.
+
+To register and verify a new generator:
+
+1. Add its implementation and `.tt` templates under
+   `lib/generators/develoz/<name>/`.
+2. Register it in `config/generators.yml` with `always: true` for core behavior
+   or a `requires` list for opt-in behavior.
+3. For an opt-in generator, add the option to `Develoz::CLI::OPT_IN_FLAGS`,
+   `Develoz::CLI::FLAG_LABELS`, the Thor options, and the install generator's
+   class options and `OPTION_FLAGS`.
+4. Add a focused spec at
+   `spec/develoz/generators/<name>_generator_spec.rb`, including idempotency
+   coverage where the generator changes existing files.
+5. Extend `spec/develoz/generators/install_generator_spec.rb` and
+   `spec/e2e/greenfield_spec.rb` when the manifest or public CLI behavior
+   changes.
+6. Add canonical fixture and fidelity coverage when templates derive from an
+   external source.
+7. Run `./bin/ci`.
+
+## Release process
+
+One-time setup uses RubyGems trusted publishing, so no token secret is needed:
+
+1. Create a GitHub environment named `rubygems` with no secrets.
+2. Add a pending trusted publisher for the `develoz-rails` gem on RubyGems with
+   owner `develoz-com`, repository `rails-template`, workflow `release.yml`, and
+   environment `rubygems`.
+
+For each release:
+
+1. Bump the version in `lib/develoz/version.rb` and add the user-facing changes
+   to the `Unreleased` section of `CHANGELOG.md`.
+2. Merge the changes and ensure CI is green.
+3. Publish a stable GitHub Release with tag `vX.Y.Z` at the current `main`
+   commit. Keep `main` unchanged until the release workflow finishes.
+4. Let the workflow validate the release, publish the gem, and finalize and
+   commit `CHANGELOG.md` to `main`.
+
+Prereleases aren't supported. Never move or recreate a published tag. If gem
+publication succeeds but changelog finalization fails, rerun the same failed
+workflow rather than creating another release.

data/README.md

@@ -0,0 +1,76 @@
+# Develoz Rails
+
+Develoz Rails is an opinionated application generator for Rails 8.1. It wraps
+`rails new` with a tested Develoz baseline and lets each application opt into
+product, deployment, and operations features as needed.
+
+The generated baseline includes PostgreSQL, RSpec, the Solid stack, shared
+model concerns, strict loading, maintenance tasks, frontend conventions,
+documentation tooling, CI configuration, and application versioning.
+
+## Quickstart
+
+Generate a Rails app in one step:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/develoz-com/rails-template/main/install | bash -s -- my_app
+```
+
+Or install the gem and run interactively:
+
+```bash
+gem install develoz-rails
+develoz new my_app
+```
+
+For an unattended run with specific features:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/develoz-com/rails-template/main/install | bash -s -- my_app --yes --auth --ui --docker
+```
+
+```bash
+develoz new my_app --yes --auth --ui --docker
+```
+
+Use `--ruby=VERSION` or `--rails=VERSION` to select explicit toolchain
+versions. Run `develoz help new` for the complete command reference.
+
+For prerequisites and detailed setup, see the
+[installation guide](docs/guide/installation.md).
+
+## Feature matrix
+
+Core features are installed in every generated application.
+
+| Mode | Feature | Switch | What it adds |
+| --- | --- | --- | --- |
+| Core | Tooling | Always on | Editor settings, environment files, and shared application constants |
+| Core | Testing | Always on | RSpec, FactoryBot, Capybara, Selenium, parallel tests, and coverage |
+| Core | Solid stack | Always on | Solid Queue, Solid Cache, Solid Cable, and Mission Control Jobs |
+| Core | CI and quality | Always on | CI workflow plus Ruby, security, frontend, and documentation checks |
+| Core | Database | Always on | PostgreSQL configuration and `pg_search` |
+| Core | Shared concerns | Always on | Search, optimized finder, transition, and configuration concerns |
+| Core | Strict loading | Always on | Strict loading by default for Active Record models |
+| Core | Maintenance | Always on | Maintenance Tasks integration and task examples |
+| Core | Frontend | Always on | Importmap, Hotwire, AnnotateRb, and Pagy; use `--skip-pagy` to omit Pagy |
+| Core | Documentation renderer | Always on | Markdown documentation model, controller, view, assets, and route |
+| Core | Documentation specs | Always on | Documentation generation, checks, screenshots, and an example system spec |
+| Core | Agent documentation | Always on | `AGENTS.md`, development guides, PR template, and external API test support |
+| Core | Versioning | Always on | Application version constant, helper, and display partial |
+| Opt-in | REST API | `--api` | Blueprinter, RSwag, API base controller, routes, and request spec |
+| Opt-in | Authentication | `--auth` | Native Rails authentication models, controllers, views, routes, and specs |
+| Opt-in | Progressive Web App | `--pwa` | Web manifest, service worker, offline page, registration, and routes |
+| Opt-in | Push notifications | `--push` | Web Push subscriptions and notification support; also enables PWA support |
+| Opt-in | Active Resource | `--active-resource` | Active Resource dependency and application resource classes |
+| Opt-in | Admin | `--admin` | Admin base controller, layout, dashboard, and routes |
+| Opt-in | Develoz UI | `--ui` | Develoz UI integration and controller pins |
+| Opt-in | Kamal | `--kamal` | Kamal deployment configuration, secrets, and production Dockerfile |
+| Opt-in | Docker | `--docker` | Local Docker Compose workflow, development image, and helper scripts |
+| Opt-in | Database backups | `--db-backup` | Backup script, rake task, retention settings, and backup ignore rules |
+
+## Project documentation
+
+- [Installation guide](docs/guide/installation.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)

data/Rakefile

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Run RuboCop linter"
+task :rubocop do
+  sh "bundle exec rubocop"
+end
+
+desc "Run CI checks (rspec + rubocop + coverage gate)"
+task :ci do
+  sh "bin/ci"
+end
+
+task default: :spec

data/config/generators.yml

@@ -0,0 +1,105 @@
+---
+# Always-core generators (included regardless of flags)
+tooling:
+  description: "Tooling setup (linting, formatting, CI)"
+  always: true
+
+testing:
+  description: "Testing framework and helpers"
+  always: true
+
+solid:
+  description: "Solid Stack integration (Stimulus, Turbo, Hotwire)"
+  always: true
+
+ci:
+  description: "CI/CD pipeline configuration"
+  always: true
+
+database:
+  description: "Database configuration and migrations"
+  always: true
+
+concerns:
+  description: "Shared concerns and mixins"
+  always: true
+
+strict_loading:
+  description: "Strict loading configuration"
+  always: true
+
+maintenance:
+  description: "Maintenance tasks and utilities"
+  always: true
+
+frontend_core:
+  description: "Core frontend setup (Tailwind, Importmap, Pagy)"
+  always: true
+
+docs_render:
+  description: "Documentation rendering setup"
+  always: true
+
+doc_specs:
+  description: "Documentation specs"
+  always: true
+
+agents_docs:
+  description: "AGENTS.md documentation"
+  always: true
+
+versioning:
+  description: "App versioning scheme"
+  always: true
+
+# Opt-in generators (included only when flags are true)
+api:
+  description: "REST API setup (Blueprinter, RSWAG)"
+  requires:
+    - api
+
+auth:
+  description: "Authentication setup (Devise, JWT)"
+  requires:
+    - auth
+
+ui:
+  description: "UI component library"
+  requires:
+    - ui
+
+admin:
+  description: "Admin panel setup"
+  requires:
+    - admin
+
+pwa:
+  description: "Progressive Web App setup"
+  requires:
+    - pwa
+
+push:
+  description: "Push notifications setup"
+  requires:
+    - pwa
+    - push
+
+active_resource:
+  description: "ActiveResource integration"
+  requires:
+    - active_resource
+
+docker:
+  description: "Docker and Docker Compose setup"
+  requires:
+    - docker
+
+kamal:
+  description: "Kamal deployment configuration"
+  requires:
+    - kamal
+
+db_backup:
+  description: "Database backup utilities"
+  requires:
+    - db_backup