active_shrine 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c8e608b43c2c62c71a1a476bedc6511be6aef1be62c2a264e881bcc3944e2f1
-  data.tar.gz: d7833ce493df81523712856818248859ece92c6562c1736698165cf417c21345
+  metadata.gz: b0330c7363b9c8b14e0f718886933c33dff3998618da11b47e5d14e813def269
+  data.tar.gz: eda5c702640dd7c6b884ffd6aea3bf9246dffb729100d8d762bb109a6e35e79e
 SHA512:
-  metadata.gz: 2bcb62909d42c8db6f1c9f7c5fa1533a77032ccb7960f9a63c23cd1acc3f4f680eff8c2633970487d10c4beefb00252233efa1329a1a0403e865c1db1ad15d5e
-  data.tar.gz: eae0c637b8671eafcd12bbf6026b39149ee06d359c1060f5ac661052cf5b8a8dfdf1c2a0ed29ad4892a3503097ff0e279c858d4be13049ebea7867ff6350480e
+  metadata.gz: 31e7f98809b76810e2056389ef8512c1f990864d6ec05324bee267b00f9381aace0182fb1a4fb1043d54617d42ab45ccae12199af112df55beeff016115ce307
+  data.tar.gz: 9010a2da61a53f475fc24b258892a179848dcd93e36fe38f7e3a257d451b0ad43977497d5a63e4f68c95b30f47f63a9f6764324a5780de56c8e40315b416677d

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+## [0.7.0] - 2026-04-15
+
+- Support `variant:` and `strict:` options in `Attachment#url`
+
 ## [0.1.0] - 2023-12-01
 
 - Initial release

data/docs/superpowers/plans/2026-04-14-attachment-url-primitive.md

@@ -0,0 +1,235 @@
+# Attachment URL Primitive Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers-extended-cc:subagent-driven-development (recommended) or superpowers-extended-cc:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Enhance `ActiveShrine::Attachment#url` to accept a variant and a `strict:` kwarg, replacing the caller-side boilerplate for Shrine's two-phase upload lifecycle.
+
+**Architecture:** A single small change to `Attachment#url` (lib/active_shrine/attachment.rb:40). Non-strict default returns cache URL during pending; strict mode returns nil until promotion. Variant-missing falls back to original. The delegation in `Attached::One` / `Attached::Many` (via `delegate_missing_to :attachment, allow_nil: true`) propagates the new signature automatically — no changes needed there.
+
+**Tech Stack:** Ruby, Shrine, Minitest, Combustion.
+
+**User Verification:** NO — no user verification required. Automated tests cover the full matrix.
+
+---
+
+## File Structure
+
+- **Modify:** `lib/active_shrine/attachment.rb` — enhance the `url` method in `AttachmentMethods`.
+- **Modify:** `test/internal/config/initializers/shrine.rb` — add the `derivatives` plugin so tests can exercise variant URLs.
+- **Create:** `test/attachment_test.rb` — covers the full strict/non-strict × cached/stored × variant matrix.
+
+## Task 1: Enable derivatives in test shrine config
+
+**Goal:** Add the Shrine `derivatives` plugin to the test environment so tests can attach, promote, and read variant URLs.
+
+**Files:**
+- Modify: `test/internal/config/initializers/shrine.rb`
+
+**Acceptance Criteria:**
+- [ ] `Shrine.plugin :derivatives` is loaded in the test init file.
+- [ ] `bundle exec rake test` still runs (no regressions in existing tests).
+
+**Verify:** `bundle exec rake test` → existing tests pass.
+
+**Steps:**
+
+- [ ] **Step 1: Add the derivatives plugin**
+
+Edit `test/internal/config/initializers/shrine.rb`. Add this line after the existing plugin calls (e.g. after `Shrine.plugin :refresh_metadata`):
+
+```ruby
+Shrine.plugin :derivatives
+```
+
+- [ ] **Step 2: Run existing tests**
+
+Run: `bundle exec rake test`
+Expected: All existing tests continue to pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add test/internal/config/initializers/shrine.rb
+git commit -m "test: enable Shrine derivatives plugin in test config"
+```
+
+## Task 2: Implement `Attachment#url` with variant + strict support
+
+**Goal:** Replace the no-arg `url` method with a signature that accepts a variant and a `strict:` kwarg, with TDD driving the full behavior matrix.
+
+**Files:**
+- Create: `test/attachment_test.rb`
+- Modify: `lib/active_shrine/attachment.rb` (method at line 40-42)
+
+**Acceptance Criteria:**
+- [ ] `Attachment#url` accepts `(variant = nil, strict: false)`.
+- [ ] Non-strict, no variant, stored → returns original storage URL.
+- [ ] Non-strict, no variant, cached → returns cache URL.
+- [ ] Non-strict, variant, stored, derivative present → returns variant URL.
+- [ ] Non-strict, variant, stored, derivative absent → falls back to original URL.
+- [ ] Non-strict, variant, cached → falls back to cache URL.
+- [ ] Strict, no variant, stored → returns original URL.
+- [ ] Strict, no variant, cached → returns nil.
+- [ ] Strict, variant, stored, derivative present → returns variant URL.
+- [ ] Strict, variant, stored, derivative absent → falls back to original URL.
+- [ ] Strict, variant, cached → returns nil.
+- [ ] No existing caller that passes zero args is broken.
+
+**Verify:** `bundle exec rake test TEST=test/attachment_test.rb` → all 11 cases pass.
+
+**Steps:**
+
+- [ ] **Step 1: Write the failing test file**
+
+Create `test/attachment_test.rb` with the full matrix. This uses `TestModel` (has_one_attached :file), attaches a real uploaded file, and toggles between cached and stored states by saving the record (which triggers promotion via the inline background blocks in the test setup — the test forces synchronous promotion by calling `file_attacher.promote` directly so we don't depend on ActiveJob).
+
+```ruby
+require "test_helper"
+require "stringio"
+
+class AttachmentUrlTest < Minitest::Test
+  def setup
+    @model = TestModel.create!
+    io = StringIO.new("hello world")
+    io.define_singleton_method(:original_filename) { "hello.txt" }
+    io.define_singleton_method(:content_type) { "text/plain" }
+    @model.file = io
+    @model.save!
+    @attachment = @model.file_attachment
+  end
+
+  def teardown
+    @model&.file_attacher&.destroy
+    @model&.destroy
+  end
+
+  # --- helpers -------------------------------------------------------------
+
+  def promote!
+    @attachment.file_attacher.promote
+    @attachment.save!
+  end
+
+  def add_thumb_derivative!
+    promote!
+    thumb_io = StringIO.new("thumb bytes")
+    @attachment.file_attacher.add_derivatives(thumb: thumb_io)
+    @attachment.save!
+  end
+
+  # --- non-strict (default) ------------------------------------------------
+
+  def test_non_strict_no_variant_stored_returns_original_url
+    promote!
+    assert_match %r{/uploads/}, @attachment.url
+    refute_match %r{/uploads/cache/}, @attachment.url
+  end
+
+  def test_non_strict_no_variant_cached_returns_cache_url
+    assert_match %r{/uploads/cache/}, @attachment.url
+  end
+
+  def test_non_strict_variant_stored_with_derivative_returns_variant_url
+    add_thumb_derivative!
+    assert_match %r{/uploads/.+/thumb}, @attachment.url(:thumb)
+  end
+
+  def test_non_strict_variant_stored_without_derivative_falls_back_to_original
+    promote!
+    url = @attachment.url(:thumb)
+    assert_match %r{/uploads/}, url
+    refute_match %r{thumb}, url
+  end
+
+  def test_non_strict_variant_cached_falls_back_to_cache_url
+    assert_match %r{/uploads/cache/}, @attachment.url(:thumb)
+  end
+
+  # --- strict --------------------------------------------------------------
+
+  def test_strict_no_variant_stored_returns_original_url
+    promote!
+    assert_match %r{/uploads/}, @attachment.url(strict: true)
+  end
+
+  def test_strict_no_variant_cached_returns_nil
+    assert_nil @attachment.url(strict: true)
+  end
+
+  def test_strict_variant_stored_with_derivative_returns_variant_url
+    add_thumb_derivative!
+    assert_match %r{/uploads/.+/thumb}, @attachment.url(:thumb, strict: true)
+  end
+
+  def test_strict_variant_stored_without_derivative_falls_back_to_original
+    promote!
+    url = @attachment.url(:thumb, strict: true)
+    assert_match %r{/uploads/}, url
+    refute_match %r{thumb}, url
+  end
+
+  def test_strict_variant_cached_returns_nil
+    assert_nil @attachment.url(:thumb, strict: true)
+  end
+end
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `bundle exec rake test TEST=test/attachment_test.rb`
+Expected: failures — some pass (the no-arg stored case already works), but tests passing kwargs or variants will fail with `ArgumentError: wrong number of arguments` because the current `url` method takes zero arguments.
+
+- [ ] **Step 3: Update `Attachment#url`**
+
+In `lib/active_shrine/attachment.rb`, replace the existing method (lines 40-42):
+
+```ruby
+      def url
+        file_url
+      end
+```
+
+with:
+
+```ruby
+      # Returns a URL for this attachment.
+      #
+      # @param variant [Symbol, nil] derivative name (e.g. :thumb). If the
+      #   derivative does not exist, falls back to the original.
+      # @param strict [Boolean] when true, returns nil unless the file has
+      #   been promoted to permanent storage. Defaults to false, which returns
+      #   the cache URL during the pending window so uploads are visible
+      #   immediately.
+      def url(variant = nil, strict: false)
+        attacher = file_attacher
+        return nil if strict && !attacher.stored?
+
+        (variant && attacher.url(variant)) || attacher.url
+      end
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `bundle exec rake test TEST=test/attachment_test.rb`
+Expected: all 11 test cases pass.
+
+- [ ] **Step 5: Run the full test suite for regressions**
+
+Run: `bundle exec rake test`
+Expected: no regressions in existing tests (the new signature is backward-compatible — existing `url` callers pass zero args and still work).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add lib/active_shrine/attachment.rb test/attachment_test.rb
+git commit -m "feat: support variant and strict mode in Attachment#url"
+```
+
+---
+
+## Self-Review
+
+- **Spec coverage:** both design decisions from the spec (enhance rather than add, lenient default, variant fallback to original) are covered in Task 2. Test matrix matches the spec's "Tests" section 1:1.
+- **Placeholder scan:** no TBD/TODO; all code blocks are concrete.
+- **Type consistency:** `variant`, `strict:`, `file_attacher`, `stored?` used consistently across plan, code, and tests.
+- **Verification requirement scan:** NO — spec contains no human-in-the-loop verification requirement.

data/docs/superpowers/plans/2026-04-14-attachment-url-primitive.md.tasks.json

@@ -0,0 +1,19 @@
+{
+  "planPath": "docs/superpowers/plans/2026-04-14-attachment-url-primitive.md",
+  "tasks": [
+    {
+      "id": 1,
+      "subject": "Task 1: Enable derivatives in test shrine config",
+      "status": "pending",
+      "description": "**Goal:** Add the Shrine `derivatives` plugin to the test environment so tests can exercise variant URLs.\n\n**Files:**\n- Modify: `test/internal/config/initializers/shrine.rb`\n\n**Acceptance Criteria:**\n- [ ] `Shrine.plugin :derivatives` is loaded in the test init file.\n- [ ] Existing test suite still passes.\n\n**Verify:** `bundle exec rake test` → existing tests pass.\n\n```json:metadata\n{\"files\": [\"test/internal/config/initializers/shrine.rb\"], \"verifyCommand\": \"bundle exec rake test\", \"acceptanceCriteria\": [\"derivatives plugin loaded\", \"existing tests pass\"], \"requiresUserVerification\": false}\n```"
+    },
+    {
+      "id": 2,
+      "subject": "Task 2: Implement Attachment#url with variant + strict support",
+      "status": "pending",
+      "blockedBy": [1],
+      "description": "**Goal:** Replace the no-arg `url` method with a signature that accepts a variant and a `strict:` kwarg, driven by the full behavior matrix in tests.\n\n**Files:**\n- Create: `test/attachment_test.rb`\n- Modify: `lib/active_shrine/attachment.rb` (method at line 40-42)\n\n**Verify:** `bundle exec rake test TEST=test/attachment_test.rb` → all 11 cases pass.\n\n```json:metadata\n{\"files\": [\"test/attachment_test.rb\", \"lib/active_shrine/attachment.rb\"], \"verifyCommand\": \"bundle exec rake test TEST=test/attachment_test.rb\", \"acceptanceCriteria\": [\"new signature accepts variant and strict\", \"non-strict fallback chain works\", \"strict returns nil until stored\", \"no regressions in existing callers\"], \"requiresUserVerification\": false}\n```"
+    }
+  ],
+  "lastUpdated": "2026-04-14"
+}

data/docs/superpowers/specs/2026-04-14-attachment-url-primitive-design.md

@@ -0,0 +1,118 @@
+# Attachment URL primitive
+
+## Problem
+
+`ActiveShrine::Attachment#url` (lib/active_shrine/attachment.rb:40) delegates
+to Shrine's `file_url` with no variant handling and no awareness of Shrine's
+two-phase upload lifecycle (cache → promotion → stored). Callers end up
+reimplementing the same safety logic repeatedly:
+
+```ruby
+def image_url(variant = nil)
+  attacher = image_attachment&.file_attacher
+  return nil unless attacher&.stored?
+  variant ? (attacher.url(variant) || attacher.url) : attacher.url
+end
+```
+
+This duplicates three concerns that belong in the gem:
+
+1. Skipping the cache phase.
+2. Falling back to the original when a derivative is missing.
+3. Passing a variant through at all.
+
+## Design
+
+Enhance `Attachment#url` to accept a variant and a `strict:` kwarg. No new
+method — there should be one way to get a URL for an attachment.
+
+```ruby
+# Returns a URL for this attachment.
+#
+# @param variant [Symbol, nil] derivative name (e.g. :thumb). If the
+#   derivative does not exist, falls back to the original.
+# @param strict [Boolean] when true, returns nil unless the file has been
+#   promoted to permanent storage. Defaults to false, which returns the
+#   cache URL during the pending window so uploads are visible immediately.
+def url(variant = nil, strict: false)
+  attacher = file_attacher
+  return nil if strict && !attacher.stored?
+
+  (variant && attacher.url(variant)) || attacher.url
+end
+```
+
+### Fallback chain
+
+Non-strict (default):
+
+```
+variant URL (if stored & derivative exists)
+  → original storage URL (if stored)
+  → cache URL (if still pending)
+  → nil (nothing attached)
+```
+
+Strict:
+
+```
+variant URL (if derivative exists)
+  → original storage URL
+  → nil (anything not yet promoted)
+```
+
+### Call sites
+
+`Attached::One` and `Attached::Many` use `delegate_missing_to :attachment,
+allow_nil: true` (lib/active_shrine/attached/one.rb:28), so the new signature
+flows through automatically:
+
+```ruby
+user.avatar.url                       # original; cache URL during pending
+user.avatar.url(:thumb)               # thumb → original → cache → nil
+user.avatar.url(:thumb, strict: true) # nil until promoted
+```
+
+### Design decisions
+
+- **Lenient default, strict opt-in.** Active Storage and CarrierWave return
+  a usable URL immediately after attach. Defaulting to nil-until-promoted
+  would surprise users by making uploads appear to vanish during background
+  processing. The strict mode exists for callers who explicitly want to hide
+  half-processed attachments.
+- **Enhance `url`, don't add a new method.** Avoids two APIs doing almost
+  the same thing. The existing no-arg `url` behavior is preserved.
+- **Variant-missing falls back to original.** Derivatives are often
+  aspirational — added after the fact, or missing because processing failed.
+  A broken `<img>` tag is worse than a wrong-size image.
+- **No app-wide default for `strict:`.** Per-call only. Global config invites
+  action-at-a-distance bugs, and the kwarg is cheap at the call site.
+
+## Tests
+
+Exercise the full matrix in `spec/active_shrine/attachment_spec.rb` (or
+equivalent). Required cases:
+
+**Non-strict (default):**
+- No variant, stored → original URL.
+- No variant, cached (not stored) → cache URL.
+- Variant, stored, derivative exists → variant URL.
+- Variant, stored, derivative missing → original URL (fallback).
+- Variant, cached → cache URL (fallback through variant/original).
+
+**Strict:**
+- No variant, stored → original URL.
+- No variant, cached → nil.
+- Variant, stored, derivative exists → variant URL.
+- Variant, stored, derivative missing → original URL.
+- Variant, cached → nil.
+
+Tests should use Shrine's memory storage and derivatives plugin to exercise
+real stored/cached/derivative transitions rather than mocking the attacher.
+
+## Out of scope
+
+- Changing `Attached::One`/`Attached::Many` — delegation handles it.
+- Any new helper methods (`derivative_url`, `safe_url`, etc.).
+- Configuration hooks or initializers.
+- Changes to `representable?`, `content_type`, or other attachment metadata.

data/lib/active_shrine/attachment.rb

@@ -37,8 +37,19 @@ module ActiveShrine
     before_save :maybe_store_record
 
     module AttachmentMethods
-      def url
-        file_url
+      # Returns a URL for this attachment.
+      #
+      # @param variant [Symbol, nil] derivative name (e.g. :thumb). If the
+      #   derivative does not exist, falls back to the original.
+      # @param strict [Boolean] when true, returns nil unless the file has
+      #   been promoted to permanent storage. Defaults to false, which
+      #   returns the cache URL during the pending window so uploads are
+      #   visible immediately.
+      def url(variant = nil, strict: false)
+        attacher = file_attacher
+        return nil if strict && !attacher.stored?
+
+        (variant && attacher.url(variant)) || attacher.url
       end
 
       def content_type

data/lib/active_shrine/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveShrine
-  VERSION = "0.6.1"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_shrine
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Radioactive Labs
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-05 00:00:00.000000000 Z
+date: 2026-04-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -150,6 +150,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: marcel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mini_mime
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Write a longer description or delete this line.
 email:
 executables: []
@@ -165,6 +193,9 @@ files:
 - README.md
 - Rakefile
 - config.ru
+- docs/superpowers/plans/2026-04-14-attachment-url-primitive.md
+- docs/superpowers/plans/2026-04-14-attachment-url-primitive.md.tasks.json
+- docs/superpowers/specs/2026-04-14-attachment-url-primitive-design.md
 - gemfiles/rails_7.1.gemfile
 - gemfiles/rails_8.gemfile
 - lib/active_shrine.rb