Implement clickwrap 0.1.0

.github/workflows/claude.yml

@@ -0,0 +1,41 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read

.github/workflows/test.yml

@@ -0,0 +1,181 @@
+name: Tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  # Static gates: style, autoload health, and a buildable gem — fast,
+  # independent of the database matrix.
+  lint:
+    runs-on: ubuntu-latest
+
+    env:
+      RAILS_ENV: test
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - name: RuboCop
+        run: bundle exec rubocop
+
+      - name: Prepare dummy database
+        run: bundle exec rake db:create db:migrate
+
+      - name: Zeitwerk eager-load check
+        working-directory: test/dummy
+        run: bundle exec rails zeitwerk:check
+
+      - name: Gem builds
+        run: gem build clickwrap.gemspec
+
+  # Main test suite - tests Ruby versions and Rails compatibility with SQLite
+  sqlite:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby_version: ["3.2", "3.3", "3.4", "4.0"]
+        gemfile:
+          - Gemfile
+          - gemfiles/rails_7.1.gemfile
+          - gemfiles/rails_7.2.gemfile
+          - gemfiles/rails_8.0.gemfile
+          - gemfiles/rails_8.1.gemfile
+
+    env:
+      RAILS_ENV: test
+      BUNDLE_GEMFILE: ${{ github.workspace }}/${{ matrix.gemfile }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby_version }}
+          bundler-cache: true
+
+      - name: Prepare database and run tests
+        # Exercise the real migration path in SQLite too so dummy/test schema
+        # drift is caught in the default matrix, not only adapter-specific jobs.
+        #
+        # Use `db:create db:migrate` rather than `db:migrate:reset`: the reset macro
+        # runs db:drop + db:create + db:migrate IN ONE PROCESS, and on SQLite the
+        # db:migrate step then writes through a stale connection to the just-dropped
+        # file, so nothing persists and the suite boots into "pending migrations"
+        # (PG/MySQL survive it because the DB server reconnects). CI runners start
+        # fresh, so no drop is needed.
+        run: bundle exec rake db:create db:migrate test
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-sqlite-ruby-${{ matrix.ruby_version }}-${{ strategy.job-index }}
+          path: test/reports/
+          retention-days: 7
+
+  # PostgreSQL compatibility tests
+  postgres:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby_version: ["3.4"]
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: clickwrap_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd="pg_isready -U postgres"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+
+    env:
+      RAILS_ENV: test
+      DATABASE_URL: postgres://postgres:postgres@localhost:5432/clickwrap_test
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby_version }}
+          bundler-cache: true
+
+      - name: Prepare database
+        # Use db:migrate:reset instead of db:test:prepare to avoid loading schema.rb
+        # which has SQLite-specific defaults that fail on PostgreSQL.
+        # db:migrate:reset does: db:drop, db:create, db:migrate (using migrations, not schema.rb)
+        run: bundle exec rake db:migrate:reset
+
+      - name: Run tests
+        run: bundle exec rake test
+
+  # MySQL compatibility tests
+  mysql:
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby_version: ["3.4"]
+
+    services:
+      mysql:
+        image: mysql:8.4
+        env:
+          MYSQL_ROOT_PASSWORD: root
+          MYSQL_DATABASE: clickwrap_test
+        ports:
+          - 3306:3306
+        options: >-
+          --health-cmd="mysqladmin ping -h localhost -uroot -proot"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=5
+
+    env:
+      RAILS_ENV: test
+      DATABASE_URL: mysql2://root:root@127.0.0.1:3306/clickwrap_test
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby ${{ matrix.ruby_version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby_version }}
+          bundler-cache: true
+
+      - name: Prepare database
+        # Use db:migrate:reset instead of db:test:prepare to avoid loading schema.rb
+        # which has SQLite-specific defaults that fail on MySQL (JSON column defaults).
+        # db:migrate:reset does: db:drop, db:create, db:migrate (using migrations, not schema.rb)
+        run: bundle exec rake db:migrate:reset
+
+      - name: Run tests
+        run: bundle exec rake test

.gitignore

@@ -1,2 +1,36 @@
+/.bundle/
+/.yardoc/
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/dist/
+/log/
+
+# For gems, ignore all lockfiles (root and appraisal) to allow flexible dependency resolution
+# But commit the Appraisal Gemfiles themselves (not the .lock files)
+Gemfile.lock
+gemfiles/*.lock
+
+test/dummy/db/*.sqlite3*
+# A `db:test:prepare` roundtrip can leave an empty schema.rb here, and while it
+# exists `maintain_test_schema!` loads it over the real one and the whole suite
+# dies with "Migrations are pending". The migrations are the source of truth.
+test/dummy/db/schema.rb
+test/dummy/log/*.log*
+test/dummy/tmp/
+test/dummy/storage/
+test/dummy/.bundle/
+
+.DS_Store
+.ruby-lsp/
+
+TODO
+.cursor/
+
+# Owner-directed: the product research corpus stays out of the published
+# repository. See docs/strategy/03-readiness-market-and-next-steps.md.
 /docs/
 /*.gem

.rubocop.yml

@@ -0,0 +1,90 @@
+# MERGE our excludes with rubocop's defaults (vendor/, node_modules/, …) —
+# a bare Exclude key would REPLACE them.
+inherit_mode:
+  merge:
+    - Exclude
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  SuggestExtensions: false
+  Exclude:
+    # The dummy host app mirrors what a real application looks like, including
+    # migrations copied verbatim from the install generator's templates —
+    # don't lint a generated-code mirror against the gem's own style.
+    - test/dummy/**/*
+    # Generator templates are emitted into HOST apps (host style, and some
+    # carry ERB tags rubocop can't parse as Ruby).
+    - lib/generators/clickwrap/templates/**/*
+    # Appraisal-generated Gemfiles.
+    - gemfiles/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+# Hard size metrics fight readable, well-commented domain code and thorough
+# test classes; we optimize for the latter. A policy compiler that explains
+# every refusal in a full sentence is longer than one that raises "invalid",
+# and the long version is the product.
+Metrics:
+  Enabled: false
+
+# Evidence code carries short, standard names for the things it records.
+Naming/MethodParameterName:
+  AllowedNames: [at, by, id, ip, to, ua, key]
+
+# `has_clickwraps` is the macro and the product — it matches the ecosystem
+# grammar (has_sessions, has_credits, has_api_keys), not a predicate.
+Naming/PredicatePrefix:
+  AllowedMethods: [has_clickwraps, has_clickwrap_evidence]
+
+# Receipt and verification predicates read as questions about a recorded fact:
+# `recorded_ip_address?`, `ip_geolocation_was_estimated?`,
+# `browser_user_agent_was_client_supplied?`. Renaming them to satisfy a
+# prefix cop would break the plain-English naming contract these methods exist
+# to honor.
+Naming/PredicateMethod:
+  Enabled: false
+
+# %{policy} / %{document} are I18n interpolation tokens — annotated tokens
+# aren't a thing in I18n templates.
+Style/FormatStringToken:
+  EnforcedStyle: template
+
+# Adapter contracts (IP geolocation resolvers, anchors, timestamp providers)
+# fix keyword names even where a no-op implementation ignores them. The names
+# ARE the documented interface.
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+# The codebase consistently names a rescued exception `error` — it reads as a
+# noun in the sentences these rescue blocks are written as.
+Naming/RescuedExceptionsVariableName:
+  PreferredName: error
+
+# Configuration's readers are grouped by section, matching the order and shape
+# of the generated initializer — which is the main thing a host ever reads
+# about this gem. Collapsing them into one declaration produces a single
+# thousand-character line and loses that structure entirely.
+Style/AccessorGrouping:
+  Exclude:
+    - lib/clickwrap/configuration.rb
+
+# `->(http_request) { http_request.remote_ip }` keeps the parameter name, and
+# the parameter name is the point: the naming contract says `http_request`, not
+# a bare `&:remote_ip` whose receiver is anybody's guess when a host overrides
+# the reader.
+Style/SymbolProc:
+  Exclude:
+    - lib/clickwrap/configuration.rb
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - clickwrap.gemspec # the long-form rubygems description is one line by design