tokenize_attr 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: abf1c8d9447a7b940dca5bd4759bf60c82ffb967dfcffa18d5df14b41512cfe2
-  data.tar.gz: c88d3236ac9fae09d5c9d879f4ac0baba43df11ebe8408db5d039fae58b2bd6c
+  metadata.gz: 75324e12ad6bd3f86dbd34d10e2a9784d1d7235c0bd821006cd9129008b9835d
+  data.tar.gz: 489806ddb67867c16c7e1a09af4da63784044da15fe30b6c1579ce37f326e1ad
 SHA512:
-  metadata.gz: f50afa2586d8689212b18a1577da21b372cf499fb1022279475ed609adc0dea4ddcfa712d7ecaa6d70a9fba38732886b68445737f82f8541cd0cf8ba620da4b5
-  data.tar.gz: d6e087c763c99973351e884a3cb81b7a13527b04e8664cbe15946fbb1bb77d7fe5bec4a49dfc1827271206f827681c68c3ca782f4386a3a0b76e023edee827b0
+  metadata.gz: 4a2dbbc09633a58b9c62f813858318b99dd5f1b33a74033b7d11b6531be139e1155e8f837e92fca1894c7468063877109fa6c1a6add0ab9481798fac88f27273
+  data.tar.gz: ab5dc72978cde93bb5093357a52881d9f66be064247d7dc7cfbcbfa3404faedbd565eb314885e29f66f0fa7c57fa796ba8da0d87708bbbf03a5f9e8b83c50317

data/AGENTS.md

@@ -27,22 +27,32 @@ unavailable), `tokenize` installs a `before_create` callback that:
 5. Retries up to `retries` times (default 3).
 6. Raises `TokenizeAttr::RetryExceededError` if all retries are exhausted.
 
+**Rails integration** is wired via an installer task. Running
+`rails tokenize_attr:install` generates
+`config/initializers/tokenize_attr.rb` which calls
+`ActiveSupport.on_load(:active_record)` to include `TokenizeAttr::Concern`
+into every `ActiveRecord::Base` subclass automatically.
+
 ---
 
 ## File map
 
-| File                              | Role                                                              |
-|-----------------------------------|-------------------------------------------------------------------|
-| `lib/tokenize_attr.rb`            | Entry point. Requires sub-files and registers the on_load hook.   |
-| `lib/tokenize_attr/version.rb`    | `TokenizeAttr::VERSION` constant.                                 |
-| `lib/tokenize_attr/errors.rb`     | `TokenizeAttr::Error` and `TokenizeAttr::RetryExceededError`.     |
-| `lib/tokenize_attr/tokenizer.rb`  | `TokenizeAttr::Tokenizer` — all token-generation logic (private). |
-| `lib/tokenize_attr/concern.rb`    | `TokenizeAttr::Concern` — thin concern with the `tokenize` macro. |
-| `test/test_helper.rb`             | In-memory SQLite setup, loads the gem.                            |
-| `test/test_tokenize_attr.rb`      | Full test suite.                                                  |
-| `sig/tokenize_attr.rbs`           | RBS type signatures.                                              |
-| `llms/overview.md`                | Internal design notes for LLMs.                                   |
-| `llms/usage.md`                   | Common usage patterns for LLMs.                                   |
+| File                                   | Role                                                              |
+|----------------------------------------|-------------------------------------------------------------------|
+| `lib/tokenize_attr.rb`                 | Entry point. Requires sub-files; loads Railtie when in Rails.     |
+| `lib/tokenize_attr/version.rb`         | `TokenizeAttr::VERSION` constant.                                 |
+| `lib/tokenize_attr/errors.rb`          | `TokenizeAttr::Error` and `TokenizeAttr::RetryExceededError`.     |
+| `lib/tokenize_attr/tokenizer.rb`       | `TokenizeAttr::Tokenizer` — all token-generation logic (private). |
+| `lib/tokenize_attr/concern.rb`         | `TokenizeAttr::Concern` — thin concern with the `tokenize` macro. |
+| `lib/tokenize_attr/installer.rb`       | `TokenizeAttr::Installer` — writes/removes the Rails initializer. |
+| `lib/tokenize_attr/railtie.rb`         | `TokenizeAttr::Railtie` — registers rake tasks in Rails.          |
+| `lib/tasks/tokenize_attr.rake`         | `tokenize_attr:install` and `tokenize_attr:uninstall` rake tasks. |
+| `test/test_helper.rb`                  | In-memory SQLite setup; simulates the installed initializer.      |
+| `test/test_tokenize_attr.rb`           | Full integration test suite.                                      |
+| `test/tokenize_attr/installer_test.rb` | Unit tests for `TokenizeAttr::Installer`.                         |
+| `sig/tokenize_attr.rbs`                | RBS type signatures.                                              |
+| `llms/overview.md`                     | Internal design notes for LLMs.                                   |
+| `llms/usage.md`                        | Common usage patterns for LLMs.                                   |
 
 ---
 
@@ -80,6 +90,14 @@ mixed into the user's model class. This eliminates any risk of method-name
 collisions for models that happen to define methods with similar names.
 `Concern` only exposes the single public `tokenize` macro.
 
+### Why use an installer task instead of an inline `on_load`?
+The installer pattern (also used by `inquiry_attrs`) gives host applications
+explicit, auditable control over when the concern is included. The generated
+initializer is checked into the host app's source control, making the
+integration visible and easy to remove or customise. An inline `on_load` in
+the gem's main file would silently include the concern on every `require`,
+which is less predictable in non-Rails contexts.
+
 ---
 
 ## Guardrails
@@ -94,6 +112,8 @@ collisions for models that happen to define methods with similar names.
   callers can handle it.
 - **Keep `TokenizeAttr::Tokenizer` methods private** (except `apply`). The
   class is `@api private`; only `apply` is the stable internal contract.
+- **`TokenizeAttr::Installer` must not depend on Rake or Rails**. All
+  file-system logic lives in plain Ruby so it can be unit-tested in isolation.
 
 ---
 
@@ -108,3 +128,8 @@ collisions for models that happen to define methods with similar names.
 - Model classes share `self.table_name = "records"` so the schema stays flat.
 - All column names used by test models must exist in the `records` table
   defined in `test/test_helper.rb`.
+- `test/test_helper.rb` simulates the initializer generated by
+  `rails tokenize_attr:install` by calling `ActiveSupport.on_load(:active_record)`
+  manually — no full Rails boot is required.
+- Installer tests in `test/tokenize_attr/installer_test.rb` use `Dir.mktmpdir`
+  to create a throwaway filesystem tree; no Rails environment is needed.

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-03-07
+
+### Added
+- `TokenizeAttr::Installer` class — manages creation and removal of the
+  Rails initializer (`config/initializers/tokenize_attr.rb`) that wires the
+  gem into `ActiveRecord::Base` via `ActiveSupport.on_load(:active_record)`.
+- `TokenizeAttr::Railtie` — registers `rails tokenize_attr:install` and
+  `rails tokenize_attr:uninstall` rake tasks in Rails applications.
+- `lib/tasks/tokenize_attr.rake` — the rake task implementations.
+- `test/tokenize_attr/installer_test.rb` — full unit-test coverage for the
+  installer (create, skip-if-exists, uninstall, content validity).
+
+### Changed
+- `lib/tokenize_attr.rb` no longer calls `ActiveSupport.on_load` directly.
+  The `on_load` hook is now installed by the generated initializer
+  (`rails tokenize_attr:install`) rather than at require-time. This mirrors
+  the pattern used by `inquiry_attrs` and gives host applications explicit
+  control over when and whether the concern is included.
+- Gem renamed from `token_attr` to `tokenize_attr`; module namespace renamed
+  from `TokenAttr` to `TokenizeAttr` across all files.
+- `TokenAttr::Tokenizer` extracted as a dedicated private class so that no
+  internal helper methods are mixed into model classes.
+
+## [0.1.0] - 2026-02-01
+
+### Added
+- Initial release.
+- `tokenize` class macro for ActiveRecord models.
+- Transparent delegation to `has_secure_token` (Rails 5+) when no prefix or
+  custom generator is provided.
+- Custom `before_create` callback backed by `SecureRandom.base58` when a
+  prefix is required or `has_secure_token` is unavailable.
+- `size:` option (default 64) controlling token length.
+- `prefix:` option prepending `"prefix-<token>"`.
+- `retries:` option (default 3) with `TokenizeAttr::RetryExceededError` raised
+  when all attempts are exhausted.
+- Custom generator support: proc as second positional argument, block, or
+  method reference via `&`.
+
+[Unreleased]: https://github.com/pniemczyk/tokenize_attr/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/pniemczyk/tokenize_attr/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/pniemczyk/tokenize_attr/releases/tag/v0.1.0

data/CLAUDE.md

@@ -11,3 +11,18 @@ Before writing any code, read these files in order:
 ---
 
 ## Project context
+
+`tokenize_attr` v0.2.0 — declarative secure token generation for ActiveRecord
+model attributes. See `@AGENTS.md` for the full design context.
+
+### Key commands
+
+```bash
+# Run the full test suite (without Rails/Rake)
+~/.local/share/mise/installs/ruby/3.4.6/bin/ruby -Ilib:test test/test_tokenize_attr.rb
+~/.local/share/mise/installs/ruby/3.4.6/bin/ruby -Ilib:test test/tokenize_attr/installer_test.rb
+
+# In a Rails app
+rails tokenize_attr:install    # create the initializer
+rails tokenize_attr:uninstall  # remove the initializer
+```

data/README.md

@@ -17,6 +17,22 @@ Add to your Gemfile:
 gem "tokenize_attr"
 ```
 
+Then run the install task to wire the gem into your Rails app:
+
+```bash
+rails tokenize_attr:install
+```
+
+This creates `config/initializers/tokenize_attr.rb`, which calls
+`ActiveSupport.on_load(:active_record)` so that every model gains the
+`tokenize` macro automatically.
+
+To remove the initializer:
+
+```bash
+rails tokenize_attr:uninstall
+```
+
 ## Usage
 
 ### Basic — delegates to `has_secure_token`
@@ -138,12 +154,13 @@ end
 
 ## Rails integration
 
-When loaded inside a Rails application `TokenizeAttr::Concern` is
-auto-included into `ActiveRecord::Base` via `ActiveSupport.on_load`, so
-every model gains the `tokenize` macro without an explicit include.
+Run `rails tokenize_attr:install` once after adding the gem. The generated
+initializer (`config/initializers/tokenize_attr.rb`) hooks into
+`ActiveSupport.on_load(:active_record)` so every model gains the `tokenize`
+macro without an explicit include.
 
-Outside of Rails (or with non-AR classes that provide `before_create` and
-`exists?`) include the concern manually:
+For non-Rails classes that provide `before_create` and `exists?` include the
+concern manually:
 
 ```ruby
 class MyModel

data/Rakefile

@@ -3,7 +3,9 @@
 require "bundler/gem_tasks"
 require "minitest/test_task"
 
-Minitest::TestTask.create
+Minitest::TestTask.create(:test) do |t|
+  t.test_globs = ["test/**/{test_*,*_test}.rb"]
+end
 
 require "rubocop/rake_task"
 

data/lib/tasks/tokenize_attr.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "tokenize_attr/installer"
+
+namespace :tokenize_attr do
+  INITIALIZER_RELATIVE = TokenizeAttr::Installer::INITIALIZER_PATH.to_s
+
+  desc "Install an initializer that auto-includes TokenizeAttr::Concern into ActiveRecord"
+  task :install do
+    result = TokenizeAttr::Installer.install!(Rails.root)
+
+    case result
+    when :created then printf "  %-10s %s\n", "create", INITIALIZER_RELATIVE
+    when :skipped then printf "  %-10s %s\n", "skip",   "#{INITIALIZER_RELATIVE} already exists"
+    end
+  end
+
+  desc "Remove the tokenize_attr initializer"
+  task :uninstall do
+    result = TokenizeAttr::Installer.uninstall!(Rails.root)
+
+    case result
+    when :removed then printf "  %-10s %s\n", "remove", INITIALIZER_RELATIVE
+    when :skipped then printf "  %-10s %s\n", "skip",   "#{INITIALIZER_RELATIVE} not found"
+    end
+  end
+end

data/lib/tokenize_attr/installer.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module TokenizeAttr
+  # Manages the lifecycle of the tokenize_attr initializer inside a Rails app.
+  #
+  # This class holds all file-system logic so it can be unit-tested without
+  # requiring a full Rails boot or Rake DSL. The rake tasks are thin shells
+  # that delegate here.
+  #
+  # @example From a Rake task (or Rails generator):
+  #   TokenizeAttr::Installer.install!(Rails.root)
+  #   TokenizeAttr::Installer.uninstall!(Rails.root)
+  #
+  class Installer
+    INITIALIZER_PATH = Pathname.new("config/initializers/tokenize_attr.rb")
+
+    INITIALIZER_CONTENT = <<~RUBY
+      # frozen_string_literal: true
+
+      # Auto-include TokenizeAttr::Concern into every ActiveRecord model so that
+      # the .tokenize macro is available without an explicit include in each class.
+      #
+      # Generated by: rails tokenize_attr:install
+      #
+      # To opt out of auto-include, remove this file and add
+      #   include TokenizeAttr::Concern
+      # to whichever models need it.
+      ActiveSupport.on_load(:active_record) do
+        include TokenizeAttr::Concern
+      end
+    RUBY
+
+    # Write the initializer to +rails_root/config/initializers/tokenize_attr.rb+.
+    #
+    # @param rails_root [Pathname, String] the root directory of the Rails app
+    # @return [:created, :skipped]
+    def self.install!(rails_root)
+      destination = Pathname.new(rails_root).join(INITIALIZER_PATH)
+
+      return :skipped if destination.exist?
+
+      destination.write(INITIALIZER_CONTENT)
+      :created
+    end
+
+    # Remove the initializer if it exists.
+    #
+    # @param rails_root [Pathname, String]
+    # @return [:removed, :skipped]
+    def self.uninstall!(rails_root)
+      destination = Pathname.new(rails_root).join(INITIALIZER_PATH)
+
+      return :skipped unless destination.exist?
+
+      destination.delete
+      :removed
+    end
+  end
+end

data/lib/tokenize_attr/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module TokenizeAttr
+  class Railtie < Rails::Railtie
+    railtie_name :tokenize_attr
+
+    # Expose `rails tokenize_attr:install` and `rails tokenize_attr:uninstall`
+    # to the host application.
+    rake_tasks do
+      load File.expand_path("../tasks/tokenize_attr.rake", __dir__)
+    end
+  end
+end

data/lib/tokenize_attr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TokenizeAttr
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/tokenize_attr.rb

@@ -8,11 +8,28 @@ require_relative "tokenize_attr/version"
 require_relative "tokenize_attr/errors"
 require_relative "tokenize_attr/tokenizer"
 require_relative "tokenize_attr/concern"
+require_relative "tokenize_attr/installer"
 
+# TokenizeAttr adds a declarative +tokenize+ class macro to ActiveRecord models.
+#
+# In a Rails app, run the install task to wire the gem in:
+#
+#   rails tokenize_attr:install
+#
+# That creates +config/initializers/tokenize_attr.rb+ which calls
+# +ActiveSupport.on_load(:active_record)+ so that every ActiveRecord model
+# gets the +tokenize+ macro without an explicit include.
+#
+# For non-Rails classes that provide +before_create+ and +exists?+, include
+# the concern manually:
+#
+#   class MyModel
+#     include TokenizeAttr::Concern
+#   end
+#
 module TokenizeAttr
-  # When loaded inside a Rails application, auto-include the concern into
-  # ActiveRecord::Base so every model gains the +tokenize+ macro without
-  # an explicit include. If ActiveRecord is already loaded (e.g. in tests
-  # without a full Rails boot) the block executes immediately.
-  ActiveSupport.on_load(:active_record) { include TokenizeAttr::Concern }
 end
+
+# Register the Railtie when running inside a Rails application.
+# The Railtie exposes the `rails tokenize_attr:install` rake task.
+require "tokenize_attr/railtie" if defined?(Rails::Railtie)

data/llms/overview.md

@@ -27,6 +27,37 @@ tokenize(attribute, generator = nil, size: 64, prefix: nil, retries: 3, &block)
 
 ---
 
+## Rails installation
+
+`tokenize_attr` does not auto-include itself at require time. In a Rails app,
+run once after adding the gem to the Gemfile:
+
+```bash
+rails tokenize_attr:install
+```
+
+This creates `config/initializers/tokenize_attr.rb`:
+
+```ruby
+# frozen_string_literal: true
+ActiveSupport.on_load(:active_record) do
+  include TokenizeAttr::Concern
+end
+```
+
+To remove:
+
+```bash
+rails tokenize_attr:uninstall
+```
+
+The Railtie (`TokenizeAttr::Railtie`) is loaded automatically when
+`Rails::Railtie` is defined (i.e. inside a Rails app). In plain
+`activerecord` contexts (tests, scripts) include the concern manually or
+call `ActiveSupport.on_load` directly, as the test helper does.
+
+---
+
 ## Internal decision tree
 
 All logic below lives in `TokenizeAttr::Tokenizer` (see
@@ -57,6 +88,24 @@ tokenize called  →  TokenizeAttr::Tokenizer.apply(klass, attribute, ...)
 
 ---
 
+## Installer class
+
+`TokenizeAttr::Installer` is a plain Ruby class (no Rake or Rails dependency)
+that handles the filesystem operations for the initializer lifecycle.
+
+```
+TokenizeAttr::Installer
+  .install!(rails_root)    → :created | :skipped
+  .uninstall!(rails_root)  → :removed | :skipped
+
+  INITIALIZER_PATH = Pathname("config/initializers/tokenize_attr.rb")
+```
+
+`TokenizeAttr::Railtie` loads the rake task file and delegates to
+`Installer` from within the `task :install` and `task :uninstall` blocks.
+
+---
+
 ## Error class hierarchy
 
 ```
@@ -70,10 +119,13 @@ StandardError
 ## Key constraints
 
 - Only `activesupport` is a hard runtime dependency.
-- `ActiveRecord::Base` receives the concern via `ActiveSupport.on_load(:active_record)`.
+- `ActiveRecord::Base` receives the concern via the generated initializer
+  (`rails tokenize_attr:install`), not at require time.
 - All generation helpers live in `TokenizeAttr::Tokenizer`, not in the model
   class. This prevents method-name collisions on user models. Only the
   `tokenize` macro is mixed in via `Concern`.
+- `TokenizeAttr::Installer` must stay dependency-free (no Rake, no Rails) so
+  it can be unit-tested without a Rails boot.
 - Tests use bare `activerecord` + SQLite3 — no `rails` gem.
 - `has_secure_token` delegation is skipped when `prefix:` is provided
   because that built-in has no prefix support.

data/llms/usage.md

@@ -4,6 +4,23 @@
 
 ---
 
+## Installation in a Rails app
+
+```bash
+rails tokenize_attr:install    # creates config/initializers/tokenize_attr.rb
+rails tokenize_attr:uninstall  # removes the initializer
+```
+
+The generated initializer wires the gem into ActiveRecord:
+
+```ruby
+ActiveSupport.on_load(:active_record) do
+  include TokenizeAttr::Concern
+end
+```
+
+---
+
 ## Basic (no prefix) — delegates to `has_secure_token`
 
 ```ruby

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tokenize_attr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Pawel Niemczyk
@@ -42,13 +42,17 @@ extensions: []
 extra_rdoc_files: []
 files:
 - AGENTS.md
+- CHANGELOG.md
 - CLAUDE.md
 - LICENSE.txt
 - README.md
 - Rakefile
+- lib/tasks/tokenize_attr.rake
 - lib/tokenize_attr.rb
 - lib/tokenize_attr/concern.rb
 - lib/tokenize_attr/errors.rb
+- lib/tokenize_attr/installer.rb
+- lib/tokenize_attr/railtie.rb
 - lib/tokenize_attr/tokenizer.rb
 - lib/tokenize_attr/version.rb
 - llms/overview.md