familia 2.0.0.pre5 → 2.0.0.pre7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5517961b53f3213a7d92f9bd07001291bcdae102f1ca5cf59570537020e4fc2f
-  data.tar.gz: 44610f83cf5b65d1cde483c91b9a259816bb1040da2b1ff77867061be8aeaf36
+  metadata.gz: 7a93de51c8a35c420067d9e48895af37862866667af224a8e13f44647c4e4c76
+  data.tar.gz: bbdf64f77c182a0498fc757c393071b04b5da3594b4c7d5c12992fe058b44777
 SHA512:
-  metadata.gz: 9e02c91aa204b248bf6853637c21ffdeabc90d7b04661c5ddc2cb99260fc0ebb6cc2d4780aed0d45e6f30e64e49229e15201551073f5c804fa8c2a0add328c97
-  data.tar.gz: ef296043a9b843fa27745d15b505fa11f2df4f5baeb505189d02013fb3f02cfccb49f9d3606912b101ed95ef6b2f3967ade5b8ff79e67c6e50ebda7a81ef0e15
+  metadata.gz: 59a39a481db42739bbebabab9211645b2f7e9eb605742ab936c0b65dfc32973931b1b1f8a1c5d725fed5f5eb0ebdbb87c1c405f87108390ad3b6eb8f5ca89c5a
+  data.tar.gz: 4dc7dededb21bd7ee988a4d260e30eceb43f19be4c3f5d99f87bac5d632af6e517af5eab2633758e0c6b1552a2635bd0e024ace2210ee1ee83362aa811458b8c

data/.github/workflows/claude-code-review.yml

@@ -0,0 +1,57 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@beta
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # Optional: Use sticky comments to make Claude reuse the same comment on subsequent pushes to the same PR
+          use_sticky_comment: true
+
+          prompt: |
+            Please review this pull request and provide feedback on:
+            - Code quality and best practices
+            - Potential bugs or issues
+            - Performance considerations
+            - Security concerns
+            - Test coverage
+
+            Use the repository's CLAUDE.md for guidance on style and conventions. Be constructive and helpful in your feedback.
+
+            Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
+          claude_args: '--allowed-tools "Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'

data/.github/workflows/claude.yml

@@ -0,0 +1,71 @@
+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
+
+          # Optional: Specify model (defaults to Claude Sonnet 4, uncomment for Claude Opus 4)
+          # model: "claude-opus-4-20250514"
+
+          # Optional: Customize the trigger phrase (default: @claude)
+          # trigger_phrase: "/claude"
+
+          # Optional: Trigger when specific user is assigned to an issue
+          # assignee_trigger: "claude-bot"
+
+          # Optional: Allow Claude to run specific commands
+          # allowed_tools: "Bash(npm install),Bash(npm run build),Bash(npm run test:*),Bash(npm run lint:*)"
+
+          # Optional: Add custom instructions for Claude to customize its behavior for your project
+          # custom_instructions: |
+          #   Follow our coding standards
+          #   Ensure all new code has tests
+          #   Use TypeScript for new files
+
+          # Optional: Custom environment variables for Claude
+          # claude_env: |
+          #   NODE_ENV: test
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://docs.anthropic.com/en/docs/claude-code/sdk#command-line for available options
+          # claude_args: '--model claude-opus-4-1-20250805 --allowed-tools Bash(gh pr:*)'

data/.gitignore

@@ -1,14 +1,19 @@
 .DS_Store
 .bundle
 .byebug*
+.ruby-lsp
 .prompts
 .history
 .devcontainer
 .vscode
+.serena
+.claude
+.yardoc
 .*.json
 *.env
 *.log
 *.md
+.mcp.json
 !README.md
 !CLAUDE.md
 *.txt
@@ -21,7 +26,6 @@ tmp
 vendor
 *.gem
 doc/
-.yardoc
 !docs/overview.md
 !docs/connection_pooling.md
 !docs/wiki/**/*.md

data/.rubocop.yml

@@ -80,3 +80,6 @@ Naming/AsciiIdentifiers:
 
 Style/FrozenStringLiteralComment:
   Enabled: false
+
+Naming/MemoizedInstanceVariableName:
+  Enabled: false

data/CLAUDE.md

@@ -6,16 +6,38 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing
 
-A couple rules when writing tests:
-1) Every tryouts file has three sections: setup, testcases, teardown.
-2) Every tryouts testcase also has three parts: description, code, expectations.
-3) Tryouts tests are meant to double as documentation examples; keep that in mind when considering syntax choices.
-4) There are multiple kinds of expectations: `#=>` is the default comparison, `#=:>` is a class comparison via `is_a?` or `kind_of?`, `#=!>` is an exception class which allows you to knowingly raise an exception without needing a begin/rescue.
-
-- **Run tests**: `bundle exec try` (uses tryouts testing framework)
-- **Run specific test file, verbose**: `bundle exec try -v try/specific_test_try.rb`
-- **Debug mode**: `FAMILIA_DEBUG=1 bundle exec try -D`
-- **Trace mode**: `FAMILIA_TRACE=1 bundle exec try -D` (detailed Redis operation logging)
+**Tryouts framework rules:**
+1. **Structure**: Each file has 3 sections - setup (optional), testcases, teardown (optional); each testcase has 3 required parts: description, code, expectations.
+2. **Test cases**: Use `##` line prefix for test descriptions, Ruby code, then `#=>` expectations
+3. **Variables**: Instance variables (`@var`) persist across sections; local variables do not.
+4. **Expectations**: Multiple expectation types available (`#=>`, `#==>`, `#=:>`, `#=!>`, etc.); each testcase can have multiple expectations.
+5. **Comments**: Use single `#` prefix, but DO NOT label file sections
+6. **Philosophy**: Plain realistic code, avoid mocks/test DSL
+7. **Result**: Last expression in each test case is the result
+
+**Running tests:**
+- **Basic**: `bundle exec try` (auto-discovers `*_try.rb` and `*.try.rb` files)
+- **All options**: `bundle exec try --help` (complete CLI reference with agent-specific notes)
+
+**Agent-optimized workflow:**
+- **Default agent mode**: `bundle exec try --agent` (structured, token-efficient output for LLMs)
+- **Focus modes**: `bundle exec try --agent --agent-focus summary` (options: `summary|first-failure|critical`)
+  - `summary`: Overview of test results only
+  - `first-failure`: Stop at first failure with details
+  - `critical`: Only show critical issues and summary
+
+**Framework integration:**
+- **RSpec**: `bundle exec try --rspec` (generates RSpec-compatible output)
+- **Minitest**: `bundle exec try --minitest` (generates Minitest-compatible output)
+
+**Debugging options:**
+- **Stack traces**: `bundle exec try -s` (stack traces without debug logging)
+- **Debug mode**: `bundle exec try -D` (additional logging including stack traces)
+- **Verbose failures**: `bundle exec try -vf` (detailed failure output)
+- **Fresh context**: `bundle exec try --fresh-context` (isolate test cases)
+
+*Note: Use `--agent` mode for optimal token efficiency when analyzing test results programmatically.*
+
 
 ### Development Setup
 - **Install dependencies**: `bundle install`

data/Gemfile

@@ -9,7 +9,7 @@ group :test do
     gem 'tryouts', path: '../tryouts'
     gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
-    gem 'tryouts', '~> 3.2.2', require: false
+    gem 'tryouts', '~> 3.5.1', require: false
   end
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'
@@ -19,13 +19,13 @@ end
 group :development, :test do
   # byebug only works with MRI
   gem 'byebug', '~> 11.0', require: false if RUBY_ENGINE == 'ruby'
+  gem 'irb', '~> 1.15.2', require: false
   gem 'kramdown', require: false # Required for YARD markdown processing
   gem 'pry-byebug', '~> 3.10.1', require: false if RUBY_ENGINE == 'ruby'
   gem 'rubocop', require: false
   gem 'rubocop-performance', require: false
   gem 'rubocop-thread_safety', require: false
   gem 'yard', '~> 0.9', require: false
-  gem 'irb', '~> 1.15.2', require: false
 end
 
 group :optional do

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre5)
+    familia (2.0.0.pre6)
       benchmark
       connection_pool
       csv
@@ -113,7 +113,8 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.2.2)
+    tryouts (3.5.1)
+      concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
       pastel (~> 0.8)
@@ -147,7 +148,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.2.2)
+  tryouts (~> 3.5.1)
   yard (~> 0.9)
 
 BUNDLED WITH

data/docs/wiki/API-Reference.md

@@ -55,9 +55,21 @@ vault.secret_data(passphrase_value: "user_passphrase")
 
 ## Familia::Encryption Module
 
+### manager
+
+Creates a manager instance with optional algorithm selection.
+
+```ruby
+# Use best available provider
+mgr = Familia::Encryption.manager
+
+# Use specific algorithm
+mgr = Familia::Encryption.manager(algorithm: 'xchacha20poly1305')
+```
+
 ### encrypt
 
-Encrypts plaintext with context-specific key.
+Encrypts plaintext using the default provider.
 
 ```ruby
 Familia::Encryption.encrypt(plaintext,
@@ -66,16 +78,20 @@ Familia::Encryption.encrypt(plaintext,
 )
 ```
 
-**Parameters:**
-- `plaintext` (String) - Data to encrypt
-- `context` (String) - Key derivation context
-- `additional_data` (String, nil) - Optional AAD for authentication
+### encrypt_with
+
+Encrypts plaintext with a specific algorithm.
 
-**Returns:** JSON string with encrypted data structure
+```ruby
+Familia::Encryption.encrypt_with('aes-256-gcm', plaintext,
+  context: "User:favorite_snack:user123",
+  additional_data: nil
+)
+```
 
 ### decrypt
 
-Decrypts ciphertext with context-specific key.
+Decrypts ciphertext (auto-detects algorithm from JSON).
 
 ```ruby
 Familia::Encryption.decrypt(encrypted_json,
@@ -84,12 +100,33 @@ Familia::Encryption.decrypt(encrypted_json,
 )
 ```
 
-**Parameters:**
-- `encrypted_json` (String) - JSON-encoded encrypted data
-- `context` (String) - Key derivation context
-- `additional_data` (String, nil) - Optional AAD for verification
+### status
 
-**Returns:** Decrypted plaintext string
+Returns current encryption configuration and available providers.
+
+```ruby
+Familia::Encryption.status
+# => {
+#   default_algorithm: "xchacha20poly1305",
+#   available_algorithms: ["xchacha20poly1305", "aes-256-gcm"],
+#   preferred_available: "Familia::Encryption::Providers::XChaCha20Poly1305Provider",
+#   using_hardware: false,
+#   key_versions: [:v1],
+#   current_version: :v1
+# }
+```
+
+### benchmark
+
+Benchmarks available providers.
+
+```ruby
+Familia::Encryption.benchmark(iterations: 1000)
+# => {
+#   "xchacha20poly1305" => { time: 0.45, ops_per_sec: 4444, priority: 100 },
+#   "aes-256-gcm" => { time: 0.52, ops_per_sec: 3846, priority: 50 }
+# }
+```
 
 ### validate_configuration!
 
@@ -100,17 +137,57 @@ Familia::Encryption.validate_configuration!
 # Raises Familia::EncryptionError if configuration invalid
 ```
 
-### with_key_cache
+### derivation_count / reset_derivation_count!
 
-Provides request-scoped key caching.
+Monitors key derivation operations (for testing and debugging).
 
 ```ruby
-Familia::Encryption.with_key_cache do
-  # Operations here share derived keys
-  users.each { |u| u.decrypt_fields }
-end
+# Check how many key derivations have occurred
+count = Familia::Encryption.derivation_count.value
+# => 42
+
+# Reset counter
+Familia::Encryption.reset_derivation_count!
 ```
 
+## Familia::Encryption::Manager
+
+Low-level manager class for direct provider control.
+
+### initialize
+
+```ruby
+# Use default provider
+manager = Familia::Encryption::Manager.new
+
+# Use specific algorithm
+manager = Familia::Encryption::Manager.new(algorithm: 'aes-256-gcm')
+```
+
+### encrypt / decrypt
+
+Same interface as module-level methods but tied to specific provider.
+
+## Familia::Encryption::Registry
+
+Provider management system.
+
+### setup!
+
+Registers all available providers.
+
+### get
+
+Returns provider instance by algorithm name.
+
+### default_provider
+
+Returns highest-priority available provider instance.
+
+### available_algorithms
+
+Returns array of available algorithm names.
+
 ## Configuration
 
 ### Familia.configure