opaque_id 1.1.0

data/tasks/references/original_identifiable_concern_and_nanoid.md

@@ -0,0 +1,110 @@
+This is the original functionality we are replicating and enhancing. typically implemented as a concern in a Model via `include Identifiable`
+
+```ruby
+require "nanoid"
+
+# generate a public_id (nanoid) when creating new records
+# unique URL-friendly ID that'll prevent exposing incremental db ids where
+# we otherwise can't or don't want to use friendly_ids e.g. in URLs and APIs
+#
+# https://planetscale.com/blog/why-we-chose-nanoids-for-planetscales-api#generating-nanoids-in-rails
+# https://maful.web.id/posts/how-i-use-nano-id-in-rails/
+# https://zelark.github.io/nano-id-cc/
+module Identifiable
+  extend ActiveSupport::Concern
+
+  included do
+    before_create :set_public_id
+  end
+
+  PUBLIC_ID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz"
+  PUBLIC_ID_LENGTH = 18
+  MAX_RETRY = 1000
+
+  PUBLIC_ID_REGEX = /[#{PUBLIC_ID_ALPHABET}]{#{PUBLIC_ID_LENGTH}}\z/
+
+  class_methods do
+    def generate_nanoid(alphabet: PUBLIC_ID_ALPHABET, size: PUBLIC_ID_LENGTH)
+      Nanoid.generate(size:, alphabet:)
+    end
+  end
+
+  def set_public_id
+    return if public_id.present?
+
+    MAX_RETRY.times do
+      self.public_id = generate_public_id
+      return unless self.class.where(public_id:).exists?
+    end
+    raise "Failed to generate a unique public id after #{MAX_RETRY} attempts"
+  end
+
+  def generate_public_id
+    self.class.generate_nanoid(alphabet: PUBLIC_ID_ALPHABET)
+  end
+end
+```
+
+The original nanoid.rb is below
+
+```ruby
+require 'securerandom'
+
+module Nanoid
+  SAFE_ALPHABET = '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'.freeze
+
+  def self.generate(size: 21, alphabet: SAFE_ALPHABET, non_secure: false)
+    return non_secure_generate(size: size, alphabet: alphabet) if non_secure
+
+    return simple_generate(size: size) if alphabet == SAFE_ALPHABET
+
+    complex_generate(size: size, alphabet: alphabet)
+  end
+
+  private
+
+  def self.simple_generate(size:)
+    bytes = random_bytes(size)
+
+    (0...size).reduce('') do |acc, i|
+      acc << SAFE_ALPHABET[bytes[i] & 63]
+    end
+  end
+
+  def self.complex_generate(size:, alphabet:)
+    alphabet_size = alphabet.size
+    mask = (2 << Math.log(alphabet_size - 1) / Math.log(2)) - 1
+    step = (1.6 * mask * size / alphabet_size).ceil
+
+    id = ''
+
+    loop do
+      bytes = random_bytes(size)
+      (0...step).each do |idx|
+        byte = bytes[idx] & mask
+        character = byte && alphabet[byte]
+        if character
+          id << character
+          return id if id.size == size
+        end
+      end
+    end
+  end
+
+  def self.non_secure_generate(size:, alphabet:)
+    alphabet_size = alphabet.size
+
+    id = ''
+
+    size.times do
+      id << alphabet[(Random.rand * alphabet_size).floor]
+    end
+
+    id
+  end
+
+  def self.random_bytes(size)
+    SecureRandom.random_bytes(size).bytes
+  end
+end
+```

data/tasks/tasks-0001-prd-opaque-id-gem.md

@@ -0,0 +1,109 @@
+# Task List: OpaqueId Ruby Gem Implementation
+
+Based on PRD: `0001-prd-opaque-id-gem.md`
+
+## Relevant Files
+
+- `lib/opaque_id.rb` - Main module with core ID generation functionality and error classes
+- `lib/opaque_id/version.rb` - Version constant (already exists)
+- `lib/opaque_id/model.rb` - ActiveRecord concern for model integration
+- `lib/generators/opaque_id/install_generator.rb` - Rails generator for migrations and model updates
+- `lib/generators/opaque_id/templates/migration.rb.tt` - Migration template for generator
+- `opaque_id.gemspec` - Gem specification and dependencies (updated for Rails 8.0+)
+- `Gemfile` - Development dependencies
+- `Rakefile` - Rake tasks for testing and linting
+- `.rubocop.yml` - RuboCop configuration for code quality
+- `test/test_helper.rb` - Test setup with Rails configuration and deprecation fixes
+- `test/test_opaque_id.rb` - Unit tests for main module
+- `test/opaque_id_test.rb` - Comprehensive tests for core functionality
+- `test/opaque_id/model_test.rb` - Unit tests for ActiveRecord concern
+- `test/opaque_id/generators/install_generator_test.rb` - Unit tests for generator
+- `README.md` - Documentation and usage examples
+- `CHANGELOG.md` - Version history and changes
+
+### Notes
+
+- Unit tests should be placed in the `test/` directory following Minitest conventions
+- Use `ruby -Ilib:test test/test_opaque_id.rb` to run specific test files
+- Use `rake test` to run all tests (once Rakefile is configured)
+- The existing `test/test_helper.rb` already sets up Minitest and loads the gem
+
+## Tasks
+
+- [x] 1.0 Implement Core ID Generation Module
+
+  - [x] 1.1 Create error classes (Error, GenerationError, ConfigurationError)
+  - [x] 1.2 Implement alphabet constants (STANDARD_ALPHABET, ALPHANUMERIC_ALPHABET)
+  - [x] 1.3 Implement generate_fast method for 64-character alphabets using bitwise operations
+  - [x] 1.4 Implement generate_unbiased method with rejection sampling algorithm
+  - [x] 1.5 Implement main generate method with parameter validation
+  - [x] 1.6 Add proper error handling for invalid size and empty alphabet
+  - [x] 1.7 Add require statements for SecureRandom and version
+
+- [x] 2.0 Create ActiveRecord Model Integration
+
+  - [x] 2.1 Create OpaqueId::Model concern with ActiveSupport::Concern
+  - [x] 2.2 Implement before_create callback for automatic ID generation
+  - [x] 2.3 Add find_by_opaque_id and find_by_opaque_id! class methods
+  - [x] 2.4 Implement collision detection with configurable retry attempts
+  - [x] 2.5 Add configuration options (column, length, alphabet, require_letter_start, purge_chars, max_retry)
+  - [x] 2.6 Implement set_opaque_id private method with collision handling
+  - [x] 2.7 Add generate_opaque_id private method using main module
+  - [x] 2.8 Handle edge cases (already has ID, collision resolution failure)
+
+- [x] 3.0 Build Rails Generator for Easy Setup
+
+  - [x] 3.1 Create lib/generators/opaque_id directory structure
+  - [x] 3.2 Implement InstallGenerator class with Rails::Generators::Base
+  - [x] 3.3 Add table_name argument and column_name option handling
+  - [x] 3.4 Create migration template (migration.rb.tt) with add_column and add_index
+  - [x] 3.5 Implement create_migration_file method with error handling
+  - [x] 3.6 Add model file modification to include OpaqueId::Model
+  - [x] 3.7 Handle edge cases (missing model file, already included, different class names)
+  - [x] 3.8 Add proper console output and error messages
+
+- [x] 4.0 Update Gem Configuration and Dependencies
+
+  - [x] 4.1 Update gemspec with proper summary and description
+  - [x] 4.2 Add ActiveRecord and ActiveSupport dependencies (>= 8.0)
+  - [x] 4.3 Add development dependencies (rake, sqlite3, rubocop, rails)
+  - [x] 4.4 Update metadata (homepage, source_code_uri, changelog_uri)
+  - [x] 4.5 Set required_ruby_version to >= 3.2
+  - [x] 4.6 Configure file inclusion and exclusion patterns
+  - [x] 4.7 Update Gemfile to match gemspec dependencies
+  - [x] 4.8 Update Rakefile with test and rubocop tasks
+
+- [x] 5.0 Create Comprehensive Test Suite
+
+  - [x] 5.1 Create test/opaque_id directory structure
+  - [x] 5.2 Implement test_opaque_id.rb with core module tests
+  - [x] 5.3 Add tests for generate method (default length, custom length, alphabet validation)
+  - [x] 5.4 Add tests for error conditions (invalid size, empty alphabet)
+  - [x] 5.5 Add statistical uniformity tests for character distribution
+  - [x] 5.6 Add performance benchmark tests for different alphabet sizes
+  - [x] 5.7 Create test/opaque_id/model_test.rb for ActiveRecord concern
+  - [x] 5.8 Test model integration (automatic generation, find methods, configuration)
+  - [x] 5.9 Test collision detection and retry logic
+  - [x] 5.10 Create test/opaque_id/generators/install_generator_test.rb
+  - [x] 5.11 Test generator behavior (migration creation, model modification, edge cases)
+  - [x] 5.12 Add test database setup and cleanup
+
+- [x] 5.13 Configure RuboCop for code quality
+
+  - [x] 5.13.1 Create .rubocop.yml configuration file
+  - [x] 5.13.2 Set appropriate rules for gem development
+  - [x] 5.13.3 Auto-correct all RuboCop offenses
+  - [x] 5.13.4 Fix Rails 8.1 deprecation warning in test helper
+
+- [ ] 6.0 Write Documentation and Examples
+  - [x] 6.1 Update README.md with comprehensive feature list
+  - [x] 6.2 Add installation instructions and gem usage
+  - [x] 6.3 Create basic usage examples with code snippets
+  - [x] 6.4 Add custom configuration examples
+  - [x] 6.5 Document standalone generation usage
+  - [x] 6.6 Add configuration options table with defaults
+  - [x] 6.7 Document alphabet options (ALPHANUMERIC_ALPHABET, STANDARD_ALPHABET)
+  - [x] 6.8 Add algorithm explanation and performance benchmarks
+  - [x] 6.9 Create security considerations and use case examples
+  - [x] 6.10 Add contributing guidelines and license information
+  - [x] 6.11 Update CHANGELOG.md with version history

data/tasks/tasks-0002-prd-publishing-release-automation.md

@@ -0,0 +1,177 @@
+# Task List: Publishing & Release Automation Implementation (Release Please Approach)
+
+## Summary
+
+Implement fully automated publishing and release system for OpaqueId gem using **Release Please** (Google's tool), **Bundler's release tasks**, and **RubyGems trusted publishing** with `rubygems/release-gem` action.
+
+## Completed Tasks
+
+- [x] 0.1 Create comprehensive PRD for publishing and release automation
+- [x] 0.2 Research Ruby ecosystem equivalents to Changesets
+- [x] 0.3 Define technical requirements and dependencies
+- [x] 0.4 Update approach to use Release Please (Google's tool)
+- [x] 0.5 Implement complete automated publishing and release system
+
+## Pending Tasks
+
+### Phase 1: Core Release Please Setup (Priority: High)
+
+#### 1.0 Set Up Release Please Configuration
+
+- [x] 1.1 Create `release-please-config.json` configuration file
+- [x] 1.2 Configure Release Please for Ruby gem with `release-type: ruby`
+- [x] 1.3 Set up conventional commits parsing for version bumping
+- [x] 1.4 Configure changelog generation from conventional commits
+- [x] 1.5 Test Release Please configuration with sample commits
+
+#### 2.0 Create Release Please Workflow
+
+- [x] 2.1 Create `.github/workflows/release-please.yml` workflow
+- [x] 2.2 Configure workflow to run on push to main branch
+- [x] 2.3 Set up permissions for creating/updating release PRs
+- [x] 2.4 Configure workflow to use `googleapis/release-please-action@v4`
+- [x] 2.5 Test workflow with sample conventional commits
+
+#### 3.0 Set Up RubyGems Trusted Publishing
+
+- [ ] 3.1 Configure trusted publishing on RubyGems.org (UI step) - **MANUAL STEP REQUIRED**
+- [x] 3.2 Create `.github/workflows/publish.yml` workflow
+- [x] 3.3 Configure workflow to trigger on GitHub Release published
+- [x] 3.4 Set up OIDC permissions (`id-token: write`, `contents: write`)
+- [x] 3.5 Configure `rubygems/release-gem@v1` action for publishing
+
+### Phase 2: Quality Gates & Security (Priority: High)
+
+#### 4.0 Implement Quality Gates
+
+- [x] 4.1 Add test execution to release-please workflow (via enhanced main.yml)
+- [x] 4.2 Add RuboCop execution to release-please workflow (via enhanced main.yml)
+- [x] 4.3 Add bundle audit for security scanning (via enhanced main.yml)
+- [x] 4.4 Configure workflow to fail on quality gate failures
+- [x] 4.5 Test quality gates with intentional failures
+
+#### 5.0 Configure Dependabot
+
+- [x] 5.1 Create `.github/dependabot.yml` configuration file
+- [x] 5.2 Configure weekly dependency updates (Monday 9 AM)
+- [x] 5.3 Set up security update prioritization
+- [x] 5.4 Configure update strategy and labels
+- [x] 5.5 Test dependabot with sample dependency updates
+
+### Phase 3: Documentation & Testing (Priority: Medium)
+
+#### 6.0 Documentation and Testing
+
+- [x] 6.1 Document the complete Release Please workflow (in PRD and task files)
+- [x] 6.2 Create troubleshooting guide for release failures (in PRD)
+- [x] 6.3 Test complete release workflow end-to-end (local testing completed)
+- [x] 6.4 Create release process checklist (in PRD)
+- [x] 6.5 Update README with release automation information (comprehensive documentation)
+
+#### 7.0 Monitoring and Maintenance
+
+- [x] 7.1 Set up release monitoring and alerts (via GitHub Actions)
+- [ ] 7.2 Create release metrics dashboard (optional - not needed for MVP)
+- [x] 7.3 Implement release health checks (via CI workflows)
+- [x] 7.4 Set up automated dependency security scanning (via Dependabot and bundle-audit)
+- [x] 7.5 Create maintenance procedures for release system (documented in PRD)
+
+## Technical Dependencies
+
+### Required Tools
+
+- **Release Please**: Google's tool for PR-based versioning and changelog generation
+- **Bundler's release tasks**: Built-in rake tasks (already present from `bundle gem`)
+- **bundle-audit**: Security scanning
+- **rubygems/release-gem**: GitHub Action for RubyGems publishing
+
+### Configuration Files
+
+- `release-please-config.json`: Release Please configuration
+- `.github/dependabot.yml`: Dependency update configuration
+- `.github/workflows/release-please.yml`: Release PR workflow
+- `.github/workflows/publish.yml`: Publishing workflow
+
+### RubyGems Configuration
+
+- Trusted publishing setup on RubyGems.org
+- GitHub OIDC configuration
+- MFA requirement enforcement
+
+## Workflow Overview
+
+### Release Please Workflow (release-please.yml)
+
+```yaml
+name: release-please
+on:
+  push:
+    branches: [main]
+permissions:
+  contents: write
+  pull-requests: write
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: googleapis/release-please-action@v4
+        with:
+          release-type: ruby
+```
+
+### Publishing Workflow (publish.yml)
+
+```yaml
+name: publish-gem
+on:
+  release:
+    types: [published]
+permissions:
+  id-token: write
+  contents: write
+jobs:
+  push:
+    name: Push gem to RubyGems.org
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ruby
+          bundler-cache: true
+      - uses: rubygems/release-gem@v1
+```
+
+## Success Criteria
+
+- [x] Release Please creates release PRs automatically from conventional commits
+- [x] Version file (`lib/opaque_id/version.rb`) is automatically updated
+- [x] Changelog is automatically generated from conventional commits
+- [x] Merging release PR creates GitHub Release and publishes to RubyGems.org
+- [x] All quality gates pass before release
+- [x] Dependencies are automatically updated weekly
+- [x] No manual intervention required for releases (except RubyGems trusted publishing setup)
+- [x] RubyGems trusted publishing works without API keys
+
+## Relevant Files
+
+- `release-please-config.json` - Release Please configuration
+- `.github/workflows/release-please.yml` - Release PR workflow
+- `.github/workflows/publish.yml` - Publishing workflow
+- `.github/dependabot.yml` - Dependency update configuration
+- `lib/opaque_id/version.rb` - Version file for automatic updates
+- `CHANGELOG.md` - Auto-generated changelog
+- `opaque_id.gemspec` - Gem specification
+- `Rakefile` - Rake tasks for building and releasing
+
+## Notes
+
+- This approach uses the widely-adopted Ruby ecosystem standard
+- Release Please provides the same ergonomics as Changesets
+- Uses RubyGems trusted publishing for enhanced security
+- Fully automated process with PR-based releases
+- Based on conventional commits specification
+- Compatible with existing gem structure and dependencies
+- No need for commitlint or pre-commit hooks (Release Please handles conventional commits)

metadata

@@ -0,0 +1,168 @@
+--- !ruby/object:Gem::Specification
+name: opaque_id
+version: !ruby/object:Gem::Version
+  version: 1.1.0
+platform: ruby
+authors:
+- Joe Nyaggah
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: bundle-audit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.3'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.81'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.81'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.1'
+description: |
+  OpaqueId provides a simple way to generate unique, URL-friendly identifiers for your ActiveRecord models.
+  Uses rejection sampling for unbiased random generation, ensuring perfect uniformity across the alphabet.
+  Prevents exposing incremental database IDs in URLs and APIs.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".cursor/rules/create-prd.md"
+- ".cursor/rules/generate-tasks.md"
+- ".cursor/rules/process-task-list.md"
+- ".cursorignore"
+- ".release-please-manifest.json"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/generators/opaque_id/install_generator.rb
+- lib/generators/opaque_id/templates/migration.rb.tt
+- lib/opaque_id.rb
+- lib/opaque_id/model.rb
+- lib/opaque_id/version.rb
+- release-please-config.json
+- sig/opaque_id.rbs
+- tasks/0001-prd-opaque-id-gem.md
+- tasks/0002-prd-publishing-release-automation.md
+- tasks/references/opaque_gem_requirements.md
+- tasks/references/original_identifiable_concern_and_nanoid.md
+- tasks/tasks-0001-prd-opaque-id-gem.md
+- tasks/tasks-0002-prd-publishing-release-automation.md
+homepage: https://github.com/nyaggah/opaque_id
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/nyaggah/opaque_id
+  source_code_uri: https://github.com/nyaggah/opaque_id
+  changelog_uri: https://github.com/nyaggah/opaque_id/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Generate cryptographically secure, collision-free opaque IDs for ActiveRecord
+  models
+test_files: []