Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions .okf/architecture/flat-namespace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
---
type: Decision
title: Flat `ruby_ui_scaffold` namespace for the entry generator
description: The entry generator forces namespace "ruby_ui_scaffold" because the auto-derived nested form shadows the sub-generator lookups and causes silent recursion.
tags: [generators, rails-internals]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: entry
title: RubyUiScaffoldGenerator
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
---

# Decision

`RubyUiScaffoldGenerator` declares `namespace "ruby_ui_scaffold"` explicitly.[^entry]

# Why

Rails would auto-derive `ruby_ui_scaffold:ruby_ui_scaffold` from the file path.
`find_by_namespace` tries candidate names in order, and that nested name would
match first when the hooks look up `ruby_ui_scaffold:scaffold` and
`ruby_ui_scaffold:scaffold_controller` — the entry generator would invoke
itself instead of the sub-generator, recursing **silently**.[^entry]

The same reason explains `as: :scaffold_controller` on the controller hook in the
[Generator chain](/architecture/generator-chain.md): it steers lookup to the
`name:context` form.

# Consequences

Do not remove or rename the `namespace` call. A regression shows up as the
scaffold never reaching the controller/views, not as an error.
58 changes: 58 additions & 0 deletions .okf/architecture/generator-chain.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
type: Component
title: Generator chain
description: How one `rails g ruby_ui_scaffold` fans out through three cooperating generators that subclass and selectively redirect Rails' own scaffold pipeline.
tags: [generators, rails-internals]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: entry
title: RubyUiScaffoldGenerator
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
- id: controller
title: ScaffoldControllerGenerator
resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb
- id: views
title: ScaffoldGenerator (views)
resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb
---

# Overview

The core trick is **hook redirection**: rather than reimplementing scaffold, the
gem subclasses Rails' generators and swaps exactly two hooks.

```
rails g ruby_ui_scaffold User name:string
└─ RubyUiScaffoldGenerator (< Rails ScaffoldGenerator) namespace "ruby_ui_scaffold"
├─ :orm hook → model, migration, model test, fixtures (inherited; no-op under --skip-model)
├─ resource route, helper, tests (inherited)
└─ :scaffold_controller hook, as: :scaffold_controller
└─ ScaffoldControllerGenerator (< Rails ScaffoldControllerGenerator)
├─ controller.rb.tt | controller_data_table.rb.tt
└─ :template_engine hook, as: :scaffold, default "ruby_ui_scaffold"
└─ ScaffoldGenerator (< NamedBase) → Phlex views + components
```

1. The entry generator removes the inherited `scaffold_controller` hook and
re-adds it with `as: :scaffold_controller` so lookup resolves
`ruby_ui_scaffold:scaffold_controller`.[^entry] Details:
[Entry generator](/generators/entry-generator.md).
2. The controller generator does the same for `template_engine`
(`as: :scaffold`), so `ruby_ui_scaffold:scaffold` runs instead of
`erb:scaffold`; the hook is skipped under `--api`.[^controller] Details:
[Controller generator](/generators/controller-generator.md).
3. The views generator is the "template engine": preflight, Phlex views,
helper injection into `Components::Base`, then on-demand component
install.[^views] Details: [Views generator](/generators/views-generator.md).

# What makes it fragile

Three non-obvious constraints hold the chain together, each its own decision:

- the entry generator's namespace must be flat — [Flat namespace](/architecture/flat-namespace.md);
- the Railtie must not require generator classes, while the entry file must
eagerly require its sub-generators — [Lazy generator loading](/architecture/lazy-generator-loading.md);
- options reach sub-generators by re-parsing the original CLI args —
[Option propagation](/architecture/option-propagation.md).
6 changes: 6 additions & 0 deletions .okf/architecture/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
# Architecture

* [Generator chain](generator-chain.md) - How one `rails g ruby_ui_scaffold` fans out through three cooperating generators via hook redirection.
* [Flat `ruby_ui_scaffold` namespace](flat-namespace.md) - Why the entry generator forces a flat namespace.
* [Lazy generator loading](lazy-generator-loading.md) - Railtie sets defaults only; entry file eager-requires sub-generators.
* [Option propagation](option-propagation.md) - Flags reach sub-generators by re-parsing raw CLI args.
58 changes: 58 additions & 0 deletions .okf/architecture/lazy-generator-loading.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
---
type: Decision
title: Lazy generator loading — Railtie sets defaults only, entry file eager-requires sub-generators
description: The Railtie must never require generator classes (it would freeze Rails' :orm hook to false), while the entry generator must require its sub-generators (Rails loads only the first matching file).
tags: [rails-internals, generators, regression]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: railtie
title: Railtie
resource: ../../lib/ruby_ui_scaffold/railtie.rb
- id: entry
title: RubyUiScaffoldGenerator (require block)
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
- id: railtie-test
title: test/railtie_test.rb
resource: ../../test/railtie_test.rb
- id: changelog
title: CHANGELOG 0.1.1 — Fixed
resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/CHANGELOG.md
---

# Decision

Two rules that look contradictory but are both load-bearing:

1. **`Railtie#generators` only sets an option default** —
`Rails::Generators.options[:ruby_ui_scaffold][:template_engine] = "ruby_ui_scaffold"` —
and requires **no** generator class.[^railtie]
2. **The entry generator file eagerly requires** the controller and views
sub-generators.[^entry]

# Why rule 1

Rails runs every railtie's `generators` block *before*
`Rails::Generators.configure!`. `hook_for` / `class_option` freeze defaults at
class-definition time, so requiring our generators there loads Rails'
`ScaffoldGenerator → ModelGenerator` early and freezes `:orm` as `false`. Result:
`rails g ruby_ui_scaffold` — and even plain `rails g model` in any app with the
gem bundled — silently generates no model or migration.[^railtie] This shipped
in 0.1.0 and was fixed in 0.1.1.[^changelog]

# Why rule 2

Rails' hook lookup requires only the **first** existing candidate file. For the
views hook that is the entry file itself, so without the eager require
`scaffold/scaffold_generator.rb` never loads and Rails prints
`ruby_ui_scaffold [not found]`.[^entry] This is safe because the entry file is
itself loaded lazily, after `configure!`.

# Guard

`test/railtie_test.rb` boots a minimal app **in a subprocess** through the real
`load_generators` path and asserts `ModelGenerator`'s `:orm` default and the
resolved scaffold class.[^railtie-test] It cannot run in-process because
`test_helper` already loads every generator — see
[Test harness](/testing/test-harness.md).
52 changes: 52 additions & 0 deletions .okf/architecture/option-propagation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
---
type: Pitfall
title: Option propagation down the hook chain
description: Sub-generators receive options by Thor re-parsing the original init args, so flags must be declared where they are read and mutations of `options` never propagate.
tags: [generators, rails-internals, flags]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T15:00:00Z
sources:
- id: entry
title: RubyUiScaffoldGenerator#initialize
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
- id: controller
title: ScaffoldControllerGenerator class_options
resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb
- id: views
title: ScaffoldGenerator class_options
resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb
---

# Overview

When a hook fires, Thor invokes the sub-generator by **re-parsing the original
init options** stored in `@_initializer` (`Thor::Invocation#_parse_initialization_options`).
Two consequences:

- A flag only has a value in a generator that declares it as a `class_option`.
- Mutating `options` after parse in a parent never reaches the children. That is
why `--skip-model` injects `--force` into the **raw** args in `initialize`
([Skip-model](/generators/skip-model.md)).[^entry]

# Current declarations

| Flag | Entry | Controller | Views | Read by |
|---|---|---|---|---|
| `--datatable` | yes | yes | yes | controller + views |
| `--phlex_layout` | yes | yes | yes | controller (`layout false`) + views |
| `--literal` | yes | **no** | yes | views only |
| `--skip_install` | yes | yes (pass-through only) | yes | views |
| `--skip_model` | yes | no | no | entry only |

Sources: [^entry] [^controller] [^views]

# Rule

**Declare a flag on every generator that reads it, and on the entry generator so
the CLI accepts it.** `--literal` is not declared on the controller generator and
still works, because the views generator re-parses the raw args itself.
Adding it to the controller would be harmless and keep
`rails g ruby_ui_scaffold:scaffold_controller --help` honest.

See [Generator flags](/generators/flags.md) for what each flag does.
35 changes: 35 additions & 0 deletions .okf/generators/auto-install.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
---
type: Decision
title: Scaffold auto-runs the installer in a subprocess
description: When phlex or ruby_ui isn't detected, the views generator shells out to `bin/rails g ruby_ui_scaffold:install` instead of invoking it in-process, and degrades to a warning when it can't.
tags: [install, generators]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: views
title: ScaffoldGenerator#ensure_phlex_and_ruby_ui_installed / run_install!
resource: ../../lib/generators/ruby_ui_scaffold/scaffold/scaffold_generator.rb
---

# Decision

`preflight_checks` in the [Views generator](/generators/views-generator.md)
runs the idempotent [Install generator](/generators/install-generator.md) via
`system("bin/rails", "generate", "ruby_ui_scaffold:install")`.[^views]

# Why a subprocess

The installer calls `exit(1)` on unrecoverable errors. In-process `invoke`
would let that tear down the whole scaffold run; a subprocess contains it, and
the scaffold continues writing files with a yellow warning.[^views]

# When it only warns (never aborts)

- `--skip-install` is passed, or
- there is no app `bin/rails` to drive it — notably the generator test harness,
which writes into `test/tmp/`.

The same gate (`--skip-install` / no `bin/rails`) applies to on-demand
component install ([Component resolution](/runtime/component-resolution.md)),
which is why generator tests never shell out.[^views]
40 changes: 40 additions & 0 deletions .okf/generators/controller-generator.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
---
type: Component
title: Controller generator (ScaffoldControllerGenerator)
description: Subclass of Rails' scaffold_controller that renders Phlex view classes instead of ERB and redirects the template_engine hook to the gem's views generator.
resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb
tags: [generators, datatable]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: controller
title: scaffold_controller_generator.rb
resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/scaffold_controller_generator.rb
- id: dt-template
title: controller_data_table.rb.tt
resource: ../../lib/generators/ruby_ui_scaffold/scaffold_controller/templates/controller_data_table.rb.tt
---

# Overview

Overrides `create_controller_files` to pick `controller.rb.tt` or
`controller_data_table.rb.tt` by `--datatable`, and re-hooks
`template_engine` with `as: :scaffold, default: "ruby_ui_scaffold"` (skipped
when `--api`).[^controller] It requires the views generator directly so a
standalone `rails g ruby_ui_scaffold:scaffold_controller` also resolves the
hook — the same first-match lookup issue described in
[Lazy generator loading](/architecture/lazy-generator-loading.md).

# Generated controller shape

- Actions render `::Views::<Resource>::Index.new(...)` etc. — fully qualified to
avoid clashing with ERB siblings ([View conventions](/views/view-conventions.md)).
- `--phlex_layout` emits `layout false`.
- Failed create/update render the New/Edit view with
`ActionDispatch::Constants::UNPROCESSABLE_CONTENT`, and `set_*` uses
`params.expect` — both Rails 8-era APIs inherited from the Rails template.[^dt-template]

The DataTable variant's query building is described in
[Index variants](/views/index-variants.md). Which columns participate comes from
[Attribute helpers](/runtime/attribute-helpers.md).
30 changes: 30 additions & 0 deletions .okf/generators/entry-generator.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
---
type: Component
title: Entry generator (RubyUiScaffoldGenerator)
description: The `rails g ruby_ui_scaffold` entry point — subclasses Rails' ScaffoldGenerator, forces a flat namespace, redirects the controller hook and owns the CLI flags.
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
tags: [generators, flags]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: entry
title: ruby_ui_scaffold_generator.rb
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
---

# Responsibilities

- Inherits model/migration/route/test/helper generation from
`Rails::Generators::ScaffoldGenerator`.[^entry]
- `namespace "ruby_ui_scaffold"` — see [Flat namespace](/architecture/flat-namespace.md).
- `remove_hook_for :scaffold_controller` + `hook_for :scaffold_controller, as:
:scaffold_controller, required: true` — hands off to the
[Controller generator](/generators/controller-generator.md).[^entry]
- Declares every user-facing flag ([Generator flags](/generators/flags.md)).
- Eager-requires its sub-generators — see
[Lazy generator loading](/architecture/lazy-generator-loading.md).
- Implements `--skip-model` by overriding the Thor-generated
`_invoke_from_option_orm` — see [Skip-model](/generators/skip-model.md).

Its position in the pipeline is drawn in [Generator chain](/architecture/generator-chain.md).
29 changes: 29 additions & 0 deletions .okf/generators/flags.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
type: Reference
title: Generator flags
description: What each `rails g ruby_ui_scaffold` flag changes in the generated output and where it is implemented.
tags: [flags, datatable, generators]
generated:
by: claude-code/claude-opus-5-5
at: 2026-11-13T12:00:00Z
sources:
- id: readme
title: README — Optional flags
resource: https://github.com/jacksonpires/ruby_ui_scaffold/blob/main/README.md
- id: entry
title: class_option declarations
resource: ../../lib/generators/ruby_ui_scaffold/ruby_ui_scaffold_generator.rb
---

# Flags

| Flag | Effect | Details |
|---|---|---|
| `--datatable` | Index uses ruby_ui `DataTable` (search, per-page, sortable headers, pagination); controller gains `SORTABLE_COLUMNS` + param parsing + scope building | [Index variants](/views/index-variants.md) |
| `--literal` | Views use Literal `prop` macros instead of `def initialize`; injects `extend Literal::Properties` into `Components::Base` | [View conventions](/views/view-conventions.md) |
| `--phlex_layout=Class` | Each `view_template` wraps its body in `render(Class) do ... end`; controller gets `layout false` | [View conventions](/views/view-conventions.md) |
| `--skip-install` | Never auto-run the installer or component install — only warn | [Auto-install](/generators/auto-install.md) |
| `--skip-model` | Skip the `:orm` hook; implies `--force` | [Skip-model](/generators/skip-model.md) |

Declared on the entry generator;[^entry] the README is the authoritative user-facing spec for these;[^readme] how they
travel between generators is in [Option propagation](/architecture/option-propagation.md).
10 changes: 10 additions & 0 deletions .okf/generators/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
# Generators

* [Entry generator](entry-generator.md) - `rails g ruby_ui_scaffold` entry point.
* [Controller generator](controller-generator.md) - Phlex-rendering controller and template_engine redirect.
* [Views generator](views-generator.md) - The template engine: views, helper injection, component install.
* [Install generator](install-generator.md) - Idempotent one-shot installer.
* [Generator flags](flags.md) - What each flag changes.
* [Skip-model](skip-model.md) - Re-runs that regenerate controller/views only, implying --force.
* [Auto-install](auto-install.md) - Scaffold runs the installer in a subprocess, or warns.
* [ruby_ui gem ownership](ruby-ui-gem-ownership.md) - ruby_ui belongs to the host Gemfile; installer adds it on demand.
Loading
Loading