Task Plan: Item Module Stream

Author: Miguel Pinilla Date: 2026-05-07 Status: Planning

Summary

Tiny stream — branch service/ItemPrinter.signImageUrl on host so that non-CDN image URLs (specifically Amazon-hosted product images) pass through to the print template unchanged, while existing CDN-host URLs continue to be CloudFront-signed exactly as today. Roughly two files: service/ItemPrinter.kt and the corresponding unit-test additions in business/ItemPrinterTest.kt.

This stream is independent of the other three streams at the code level. It is also independent of them at the deployment level — operations deploys via its own pipeline, and the change has no relationship to whether arda-frontend-app is also deployed.

Scope (cite of `goal.md`)

Goal §“Repositories” — operations row.
Goal §“Success Criteria” — item 1.
Goal §“Scope > In Scope” — the operations bullet.
Context does not require a citation for this stream — the change is settled by reading the existing operations source code (persistence/ItemValidator.kt:76-96, the ItemValidatorImageUrlTest.kt test “accepts non-CDN external URL without validation” at lines 299-314 verifying that the save-time validator already accepts non-CDN URLs by design, and service/ItemPrinter.kt:84-87 showing the unconditional urlSigner.sign call that needs the host-branch).

Repository

Repository	Branch	Worktree
`Arda-cards/operations`	`jmpicnic/amazon-client-integration` (existing)	`/Users/jmp/code/arda/projects/amazon-item-import-worktrees/operations` (existing)

Single worktree, single PR.

Tasks

#	Task	Depends on	Notes
1	In `src/main/kotlin/cards/arda/operations/reference/item/service/ItemPrinter.kt`, modify `signImageUrl(imageUrl: java.net.URL?)`: add a host check before calling `urlSigner.sign`. If `imageUrl.host` matches the configured CDN host (already known to `ItemPrinter`’s collaborators — it’s threaded through the constructor via `urlSigner`’s configuration; see `Module.kt` for how the CDN host is wired up and reuse the same source), call `urlSigner.sign(imageUrl.toString())` as today. If `imageUrl.host` is not the CDN host, return `Result.success(imageUrl.toString())` — i.e. pass the URL string through unchanged.	—	The CDN-host comparison should be case-insensitive (matches the existing `ItemValidator.validateImageUrl` convention at `persistence/ItemValidator.kt:85`).
2	Determine how the CDN host is most naturally available to `ItemPrinter`. Options to weigh during implementation: (a) thread the `cdnHost` string into `ItemPrinter`’s constructor from `Module.kt` (alongside the existing `urlSigner` parameter); (b) expose a getter on `urlSigner` (CloudFrontUrlSigner already has the host implicitly via the keyPairId). Pick the smaller diff. No new HOCON config is needed — the host is already known at construction.	1	Implementation detail to settle in the PR; record the choice in the CHANGELOG entry.
3	In `src/test/kotlin/cards/arda/operations/reference/item/business/ItemPrinterTest.kt` (or wherever the existing `ItemPrinter` tests live), add coverage: (a) a CDN-host URL still passes to the signer (delegation behaviour unchanged); (b) a non-CDN URL (use a representative Amazon image URL like `https://m.media-amazon.com/images/I/41FYkVPzrIL.jpg`) is returned by `signImageUrl` unchanged without invoking `urlSigner.sign`.	1	Mock the signer with MockK so calls are verifiable per the workspace’s existing patterns.
4	Pre-push: `./gradlew check` (compile + tests + static analysis) green, `make clq` (run clq linter) green.	1, 2, 3	Per workspace `feedback_always_run_checks` rule.
5	CHANGELOG entry in `operations/CHANGELOG.md` under `Fixed` (internal change; per workspace memory `feedback_changelog_categories`, internal changes go under Fixed unless API-breaking). Cite PDEV-446.	—
6	Open the PR; run `/pr-steward`.	4, 5

Acceptance criteria

./gradlew check green locally.
CI green on the PR.
New unit tests verify both branches of signImageUrl (CDN-host signed; non-CDN passed through unchanged) — and the existing tests for signImageUrl still pass.
No change to ItemValidator.kt (the save-time validator is already correct, per ItemValidatorImageUrlTest.kt line 299 “accepts non-CDN external URL without validation”).

Merge gate

CI green on the PR.
No dependency on other streams. Can merge in any order, before or after bff, infrastructure, operator.

Files to be created or modified

Modified:

src/main/kotlin/cards/arda/operations/reference/item/service/ItemPrinter.kt (one method, plus possibly the constructor signature).
src/main/kotlin/cards/arda/operations/reference/item/Module.kt (only if Task 2 picks the constructor-parameter option; one-line change).
src/test/kotlin/cards/arda/operations/reference/item/business/ItemPrinterTest.kt (new test cases).
CHANGELOG.md (Fixed entry).

References

../../goal.md — project goal.
../../context-exploration.md § “Item Module: Image URL Validation” (informally — the operational reading is in the parked exploration; the v1 conclusion is just “no validator change needed; only signImageUrl host-branch needed”).