familia 2.0.0.pre6 → 2.0.0.pre7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 93cb8ea627c19daff3566c7373aa45ff04adb6d37a3346c3b3049712c18838ea
-  data.tar.gz: 9d359e2067062a4c6afe91a76985362989a569611400f10f7155e505dd55e39b
+  metadata.gz: 7a93de51c8a35c420067d9e48895af37862866667af224a8e13f44647c4e4c76
+  data.tar.gz: bbdf64f77c182a0498fc757c393071b04b5da3594b4c7d5c12992fe058b44777
 SHA512:
-  metadata.gz: e020a48703858e929eeb11188029893656ef84ce98113e4c448d41e354edb4fe77df420aa4bab33b7775f0719ad5a693fc672c8159cd0e963be7750daa12d5b9
-  data.tar.gz: c3e66800df77ccd33ccd5a6027d031173642446210309e60bf83243f59585a0416ea99002063f0080828eb24d1aa1fa50f3013e7dbf408b2299f2fea617b2fa3
+  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,19 +6,38 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ### Testing
 
-Tryouts framework rules:
-1) **Structure**: 3 sections - setup (optional), testcases, teardown (optional)
-2) **Test cases**: Use `##` for descriptions, Ruby code, then `#=>` expectations
-3) **Variables**: Instance variables (`@var`) persist across all sections
-4) **Expectations**: `#=>` (value), `#==>` (boolean), `#=:>` (type), `#=!>` (exception)
-5) **Comments**: Use single `#` prefix, DO NOT label sections
-6) **Philosophy**: Plain realistic code, avoid mocks/test DSL
-7) **Result**: Last expression in each test case is the result
-
-- **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.3.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

@@ -113,7 +113,7 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.3.2)
+    tryouts (3.5.1)
       concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
@@ -148,7 +148,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.3.2)
+  tryouts (~> 3.5.1)
   yard (~> 0.9)
 
 BUNDLED WITH

data/docs/wiki/Feature-System-Guide.md

@@ -104,6 +104,42 @@ client.auth_token.expose { |token| make_api_call(token) }
 client.auth_token.clear!  # Explicit cleanup
 ```
 
+#### Relationships
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  identifier_field :custid
+  field :custid, :name, :email
+
+  # Define relationship collections
+  tracked_in :active_users, type: :sorted_set
+  indexed_by :email_lookup, field: :email
+  set :domains
+end
+
+class Domain < Familia::Horreum
+  feature :relationships
+
+  identifier_field :domain_id
+  field :domain_id, :name
+
+  # Declare membership in customer collections
+  member_of Customer, :domains, type: :set
+end
+
+# Usage
+customer = Customer.new(custid: "cust123", name: "Acme Corp")
+domain = Domain.new(domain_id: "dom456", name: "acme.com")
+
+# Establish bidirectional relationships
+domain.add_to_customer_domains(customer.custid)
+customer.domains.add(domain.identifier)
+
+# Query relationships
+domain.in_customer_domains?(customer.custid)  # => true
+```
+
 #### Quantization
 ```ruby
 class Metric < Familia::Horreum
@@ -487,10 +523,6 @@ end
 class Model < Familia::Horreum
   feature :expiration
 
-  def has_ttl_support?
-    self.class.features_enabled.include?(:expiration)
-  end
-
   def available_features
     self.class.features_enabled
   end
@@ -498,7 +530,6 @@ end
 
 model = Model.new
 model.available_features  # => [:expiration]
-model.has_ttl_support?    # => true
 ```
 
 ## Testing Features

data/docs/wiki/Home.md

@@ -10,15 +10,15 @@ Welcome to the comprehensive documentation for Familia v2.0. This wiki covers al
 2. **[Transient Fields Guide](Transient-Fields-Guide.md)** - Non-persistent secure data handling with RedactedString
 3. **[Security Model](Security-Model.md)** - Cryptographic design and Ruby memory limitations
 
-### 🏗️ Architecture & System Design  
+### 🏗️ Architecture & System Design
 
 4. **[Feature System Guide](Feature-System-Guide.md)** - Modular architecture with dependencies and conflict resolution _(new!)_
 5. **[Connection Pooling Guide](Connection-Pooling-Guide.md)** - Provider pattern for efficient Redis/Valkey pooling _(new!)_
-6. **[RelatableObjects Guide](RelatableObjects-Guide.md)** - Object relationships and ownership system _(new!)_
+6. **[Relationships Guide](Relationships-Guide.md)** - Object relationships and membership system _(new!)_
 
 ### 🛠️ Implementation & Usage
 
-7. **[Implementation Guide](Implementation-Guide.md)** - Configuration, providers, and advanced usage  
+7. **[Implementation Guide](Implementation-Guide.md)** - Configuration, providers, and advanced usage
 8. **[API Reference](API-Reference.md)** - Complete class and method documentation
 
 ### 🚀 Operations (As Needed)
@@ -52,7 +52,7 @@ class Customer < Familia::Horreum
   feature :safe_dump       # API-safe serialization
   feature :expiration      # TTL support
   feature :encrypted_fields # Secure storage
-  
+
   field :name, :email
   encrypted_field :api_key
   default_expiration 24.hours
@@ -66,36 +66,46 @@ end
 Familia.connection_provider = lambda do |uri|
   parsed = URI.parse(uri)
   pool_key = "#{parsed.host}:#{parsed.port}/#{parsed.db || 0}"
-  
+
   @pools[pool_key] ||= ConnectionPool.new(size: 10) do
     Redis.new(host: parsed.host, port: parsed.port, db: parsed.db || 0)
   end
-  
+
   @pools[pool_key].with { |conn| conn }
 end
 ```
 
-### Object Relationships (RelatableObjects)
+### Object Relationships
 ```ruby
 class Customer < Familia::Horreum
-  feature :relatable_object
-  self.logical_database = 0
-  field :name, :email
+  feature :relationships
+  identifier_field :custid
+  field :custid, :name, :email
+
+  # Customer collections
+  set :domains
 end
 
-class Domain < Familia::Horreum  
-  feature :relatable_object
-  self.logical_database = 0
-  field :name, :dns_zone
+class Domain < Familia::Horreum
+  feature :relationships
+  identifier_field :domain_id
+  field :domain_id, :name, :dns_zone
+
+  # Declare membership in customer collections
+  member_of Customer, :domains, type: :set
 end
 
-# Create objects with automatic ID generation
-customer = Customer.new(name: "Acme Corp")
-domain = Domain.new(name: "acme.com")
+# Create objects and establish relationships
+customer = Customer.new(custid: "cust123", name: "Acme Corp")
+domain = Domain.new(domain_id: "dom456", name: "acme.com")
+
+# Establish bidirectional relationship
+domain.add_to_customer_domains(customer.custid)
+customer.domains.add(domain.identifier)
 
-# Establish ownership
-Customer.owners.set(domain.objid, customer.objid)
-domain.owner?(customer)  # => true
+# Query relationships
+domain.in_customer_domains?(customer.custid)  # => true
+customer.domains.member?(domain.identifier)   # => true
 ```