public_code 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85226caa9d5bbc68eedc7aecda5105a079c13733853522736aa1fb04f6d99477
-  data.tar.gz: 5bfe2a1075d98348dad53b5b569d86e21c16938908f91ef08ea97015076df351
+  metadata.gz: fbf9421a17e6726374e177c5cc9580777fc403a08a07e85b3950c67d507be428
+  data.tar.gz: 90ac5dfcc08bdd8939bc80f5b56f22aaf498a6740ac6869e89f8ed4c6daa988d
 SHA512:
-  metadata.gz: 7b25139d8cc38a6ef010df8bd0167022f39e35469d89a80c026386603224d23128d21079c193981c074bd4ff0bedf4212c826668568f36792b81479be1519b25
-  data.tar.gz: 5909c90e24ef0e6dc33956b1454b20b7d0f37c47c327f3923649774da7a8a26a00712195359041436d9e7c06fbbcee5256d26cd1516c9308fa51e05cd3b96a57
+  metadata.gz: ec35ac1138505263d7debde048327e95786067fbb03f2310e220c3eac355e55a3ce7c2dfd919eb11fa8651c55c36e819c58b8a3da0388c008357c89bfa4155e8
+  data.tar.gz: 4a358f1a573c7976112006f38210015c4265ee6b252103cb0939525c0f511aff1d0a4ff282d1e676a3f8ed32057a26d3e16173d7a0f226db3452475acba7abe8

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-12
+
+### Added
+
+- Claude Code locals for public_code, which `the_local` installs into an app that uses the gem.
+
 ## [0.3.0] - 2026-10-12
 
 ### Added

data/lib/public_code/version.rb

@@ -1,3 +1,3 @@
 module PublicCode
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

data/the_local/agents/public_code-develop.md

@@ -0,0 +1,137 @@
+---
+name: public_code-develop
+description: Use PROACTIVELY for declaring a public code on a model, finding a record from a code in a URL, giving a record a new code, and testing that pages link to no numbered addresses — MUST BE USED instead of hand-rolling `to_param` overrides, token columns, `find_by!` lookups on a token column, or regexes over rendered links.
+tools: Bash, Read, Write, Edit, Grep
+scope: public codes — a random code in a record's addresses in place of its database id, the test that fails on numbered links, and the task that lists which models still use ids
+---
+
+This local follows these steps exactly and invents none. Where a step names a
+decision, it asks the developer and does not pick.
+
+## What public_code is
+
+A gem that gives an Active Record model a random 24-character code of letters and
+digits, used in the model's addresses in place of its database id. Fire this
+local when a model should be addressed by code, when a controller loads a record
+from an address, when a record's code has to be replaced, or when a test should
+fail on any link that exposes an id. Adding the gem and the code column belongs
+to **public_code-install**, and that must be done first.
+
+## Interface
+
+- `has_public_code` — declared in a model, optionally with the column name
+  (default `:public_code`); gives each new record a code, makes the model's URL
+  helpers use the code, and adds the two entry points below.
+- `find_by_public_code!` — called on the model with the code from an address;
+  returns the record or raises `ActiveRecord::RecordNotFound`.
+- `record.regenerate_public_code` — gives a saved record a new code and saves it
+  at once; with a custom column the method is `regenerate_<column>`.
+- `PublicCode::TestHelp` — a module included in an integration test class after
+  `require "public_code/test_help"`.
+- `assert_no_numbered_links` — called in that test with a list of page paths;
+  visits each one and fails, naming every page and link, when a link or form on
+  it points at a numbered address.
+- `PublicCode::TestHelp.numbered_links` — takes a list of addresses and returns
+  the ones that are numbered, for checking addresses that do not come from a
+  page.
+
+## How to use it
+
+1. Confirm the table has its code column. If not, hand off to
+   **public_code-install** and come back.
+
+2. Declare the code in the model, with the column name the migration used.
+
+   ```ruby
+   class Product < ApplicationRecord
+     has_public_code
+   end
+   ```
+
+   With another column name, pass it: `has_public_code :slug_code`. Declare it
+   once per model.
+
+   - A new record gets a code when it is created, or when it is built if the app
+     sets `ActiveRecord.generate_secure_token_on = :initialize`. A code already
+     set on the record is kept.
+   - `product_path(product)`, `url_for(product)`, `redirect_to product` and
+     `form_with model: product` now put the code where the id was. Do not
+     override `to_param`, and do not pass `product.id` to a route helper.
+
+3. Load the record from the address in each controller action that took an id.
+
+   ```ruby
+   def set_product
+     @product = Product.find_by_public_code!(params[:id])
+   end
+   ```
+
+   - Replace every `find(params[:id])`, and every nested `params[:product_id]`
+     lookup, for that model.
+   - Scope it as the action already scopes its lookups, for example
+     `Current.team.products.find_by_public_code!(params[:id])`.
+   - It raises `ActiveRecord::RecordNotFound`, so a missing code is a 404 as
+     before. Once the column exists, an id in the address is not found.
+   - Do not change the route parameter name. It stays `:id`.
+
+4. Give a record a new code only where the developer asks for one, for example
+   after a code was shared by mistake. Ask the developer whether the old address
+   should stop working, since it does.
+
+   ```ruby
+   product.regenerate_public_code
+   ```
+
+   It raises when the record is invalid. Redirect to the record's new address
+   afterwards.
+
+5. Add an integration test that fails on numbered links.
+
+   ```ruby
+   require "test_helper"
+   require "public_code/test_help"
+
+   class ProductAddressesTest < ActionDispatch::IntegrationTest
+     include PublicCode::TestHelp
+
+     test "no product page links to a numbered address" do
+       product = products(:one)
+       assert_no_numbered_links([ "/products", "/products/#{product.public_code}" ], safe: [ "page" ])
+     end
+   end
+   ```
+
+   - Ask the developer which pages to list. Each must render for the test as
+     written, so sign in first in the test if the pages need it.
+   - Ask the developer which query parameters hold a number that is not an id,
+     such as `page` or `per`, and pass those names in `safe:`.
+   - It checks every `a[href]` and `form[action]`. An address counts as numbered
+     when any path segment is all digits, or any query value is all digits and its
+     name is not in `safe:`.
+   - Addresses that do not start with `/`, start with `//`, `/assets/` or
+     `/rails/active_storage/` are not checked.
+
+6. For addresses built outside a page, such as in a mailer or a JSON response,
+   check them directly.
+
+   ```ruby
+   assert_empty PublicCode::TestHelp.numbered_links([ product_path(product) ], safe: [ "page" ])
+   ```
+
+7. Run the tests. A failure names each page and the link on it that still uses an
+   id. Fix the link by passing the record, not its id, to the route helper.
+
+## Conventions
+
+- Always declare the code with the same column name the migration created.
+- Always look up an addressed record with `find_by_public_code!`, never with
+  `find` or `find_by!(id:)`.
+- Never put a record's `id` in a link, form action or redirect.
+- Never write a code by hand. Codes come from the gem.
+- Before the table has its column, the model stays addressed and found by id.
+  That is expected while a migration is pending, and is not a bug to fix here.
+- `assert_no_numbered_links` works only in a test that can make requests and read
+  the response, such as `ActionDispatch::IntegrationTest`.
+- Out of scope here: adding the gem, the migration that adds and fills the code
+  column, and checking which models are still addressed by id. Those are
+  **public_code-install**'s.

data/the_local/agents/public_code-info.md

@@ -0,0 +1,66 @@
+---
+name: public_code-info
+description: Use to learn what public_code offers — a random code in a record's addresses in place of its database id, the test that fails on numbered links, and the task that lists which models still use ids.
+tools: Read
+scope: public codes — a random code in a record's addresses in place of its database id, the test that fails on numbered links, and the task that lists which models still use ids
+---
+
+This local explains what public_code is and the words it uses. It makes no
+changes and gives no steps.
+
+## What public_code is
+
+public_code gives an Active Record model a random code that stands in for its
+database id wherever a person or an outside caller sees the record: page
+addresses, API and MCP addresses, and links sent out. Every address Rails builds
+for the record carries the code, and the record is found from that code, so no
+address shows an id and no one can step through records by counting.
+
+Reach for it when an app or a gem exposes records at addresses and the ids in
+those addresses should not be visible or guessable. It also gives an
+integration test that fails when a page still links to a numbered address, and a
+task that reports which models are still addressed by id.
+
+## Interface
+
+This local documents no commands. Two other locals own the whole surface:
+
+- **public_code-install** owns adding the gem to an app or gem, generating codes
+  for existing records in a migration, and the task that reports which models
+  are addressed by code or by id.
+- **public_code-develop** owns declaring a code on a model, finding a record from
+  the code in an address, giving a record a new code, and the integration test
+  helper that checks pages for numbered links.
+
+## How to use it
+
+- To add public_code to an app or gem, or to check across an app which models
+  still use ids, go to **public_code-install**.
+- To give a model a code, look records up by code, or test that pages carry no
+  numbered links, go to **public_code-develop**.
+
+## Conventions
+
+- **Code** — a random string of 24 letters and digits, stored in its own column
+  with a unique index. The column is named after the gem by default, and a model
+  may name its own.
+- **Address** — any path or link a person or outside caller sees. Codes are for
+  addresses only.
+- **Id** — the database id. It stays the internal key records point at each
+  other with, and it never changes.
+- **Addressed by code / addressed by id** — whether a model's table has its code
+  column yet. A model that declares a code but whose table has no column is still
+  addressed and found by id, so a gem can declare codes before every app that
+  uses it has migrated. Once the column exists, an all-digit address is not
+  found.
+- **Not found** — a lookup by code raises the standard Active Record not-found
+  error when no record among those searched has that code, so a lookup limited
+  to one client's records never finds another client's.
+- **Numbered link** — a link or form on one of the app's own pages whose path has
+  an all-digit segment, or whose query has an all-digit value. Links to other
+  sites, asset files and stored files are never counted.
+- **Safe query names** — query parameter names, such as a page number, whose
+  all-digit values are allowed and not counted as numbered links.
+- **Strict mode** — the status report run so that it fails, naming each model
+  still addressed by id, for a deploy or CI step that requires every migration to
+  have run.

data/the_local/agents/public_code-install.md

@@ -0,0 +1,102 @@
+---
+name: public_code-install
+description: Use to hook public_code into a project — adding the gem, a migration that adds the code column and fills it with `PublicCode.generate`, and checking with `bin/rails public_code:status` which models are addressed by code or by id.
+tools: Bash, Read, Edit
+scope: public codes — a random code in a record's addresses in place of its database id, the test that fails on numbered links, and the task that lists which models still use ids
+---
+
+This local follows these steps exactly and invents none. Where a step names a
+decision, it asks the developer and does not pick.
+
+## What public_code is
+
+A gem that gives an Active Record model a random 24-character code of letters and
+digits to use in its addresses in place of its database id; hook it into a Rails
+app or a gem whose records are shown at addresses where ids should not be seen.
+
+## Interface
+
+- `gem "public_code"` — the Gemfile line, or a runtime dependency in a gem's
+  gemspec, that adds the gem; it needs Ruby 3.3 or later and Active Record 7.1 or
+  later, and loads itself into Active Record with no initializer.
+- `PublicCode.generate` — returns a new random 24-character code; a migration
+  calls it to fill the code column for records that already exist.
+- `bin/rails public_code:status` — lists every model that declares a code and
+  whether it is addressed by code or by id; with `STRICT=1` it exits non-zero and
+  names each model still addressed by id.
+
+## How to use it
+
+1. Ask the developer whether the host is a Rails app or a gem whose models other
+   apps use. The steps differ at step 4.
+
+2. Add the gem.
+   - Rails app: add `gem "public_code"` to `Gemfile`, then run `bundle install`.
+     `Gemfile.lock` changes.
+   - Gem: add `spec.add_dependency "public_code"` to the host's `*.gemspec`, then
+     run `bundle install`. Ask the developer which version constraint to use.
+
+3. Ask the developer which tables get a code, and for each one whether the column
+   is named `public_code` (the default) or another name. The column name chosen
+   here must match the name given when the model declares its code.
+
+4. Write one migration per table. In a Rails app, create it with
+   `bin/rails generate migration AddPublicCodeTo<Models>` and fill it in as below.
+   In a gem, put the migration in the gem's own migrations directory, so each app
+   copies and runs it later, and name it in the gem's changelog.
+
+   ```ruby
+   class AddPublicCodeToProducts < ActiveRecord::Migration[8.1]
+     class Product < ActiveRecord::Base
+       self.table_name = "products"
+     end
+
+     def up
+       add_column :products, :public_code, :string
+       Product.find_each { |product| product.update_columns(public_code: PublicCode.generate) }
+       change_column_null :products, :public_code, false
+       add_index :products, :public_code, unique: true
+     end
+
+     def down
+       remove_column :products, :public_code
+     end
+   end
+   ```
+
+   - Replace `products`, `Product` and `public_code` with the table, a class name
+     for it, and the column name from step 3.
+   - Keep the class defined inside the migration. It reads and writes the table
+     without the app model's callbacks.
+   - Set the `Migration[...]` version to the host's Rails version.
+
+5. Declare the code on each model. That step and everything after it, finding
+   records by code and testing pages for numbered links, belongs to
+   **public_code-develop**. Hand off to it here.
+
+6. In a Rails app, run `bin/rails db:migrate`. `db/schema.rb` (or
+   `db/structure.sql`) changes. Restart any running server or console, since a
+   process started before the migration still treats the table as having no code
+   column.
+
+7. In a Rails app, run `bin/rails public_code:status` and confirm every model from
+   step 3 prints `addressed by code`.
+
+8. Ask the developer whether a deploy or CI step should require every model to be
+   addressed by code. If yes, add `STRICT=1 bin/rails public_code:status` to that
+   step, after migrations run.
+
+## Conventions
+
+- `public_code:status` exists only in a Rails app. A gem host does not run it
+  itself; each app that uses the gem does.
+- The task only lists models that already declare a code. A table with a code
+  column whose model declares none does not appear.
+- A model that declares a code before its table has the column keeps being
+  addressed and found by id. That is how a gem can release codes before every app
+  has migrated, and why step 7 is the check that the switch happened.
+- When an app upgrades a gem that has added a code migration, copy that migration
+  into the app, run it, restart, and rerun step 7.
+- Out of scope here: declaring the code on a model, finding a record by code,
+  giving a record a new code, and the numbered-link test helper. Those are
+  **public_code-develop**'s.

data/the_local/interface.yml

@@ -0,0 +1,21 @@
+scope: public codes — a random code in a record's addresses in place of its database id, the test that fails on numbered links, and the task that lists which models still use ids
+
+install:
+  - gem "public_code"
+  - PublicCode.generate
+  - bin/rails public_code:status
+
+develop:
+  - has_public_code
+  - find_by_public_code!
+  - record.regenerate_public_code
+  - PublicCode::TestHelp
+  - assert_no_numbered_links
+  - PublicCode::TestHelp.numbered_links
+
+sources:
+  - lib/public_code.rb
+  - lib/public_code/model.rb
+  - lib/public_code/test_help.rb
+  - lib/public_code/railtie.rb
+  - lib/tasks/public_code.rake

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: public_code
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Tyler Schneider
@@ -54,6 +54,10 @@ files:
 - lib/public_code/test_help.rb
 - lib/public_code/version.rb
 - lib/tasks/public_code.rake
+- the_local/agents/public_code-develop.md
+- the_local/agents/public_code-info.md
+- the_local/agents/public_code-install.md
+- the_local/interface.yml
 homepage: https://github.com/DYB-Development/public_code
 licenses:
 - MIT